feat(contentunderstanding): Copilot skills for authoring custom analyzers

sdk/contentunderstanding/ai-content-understanding/.github/skills/_shared/.gitignore

@@ -0,0 +1,13 @@
+# The skill tool is intentionally NOT registered as a pnpm workspace member
+# (its `package.json` would otherwise be picked up by the repo-root `sdk/**`
+# glob in pnpm-workspace.yaml, and Turbo would try to build it during CI
+# without any way to install its deps). Instead, `package.json.template` is
+# the tracked file; the skill scripts copy it into place before running
+# `npm install`. See README.md for the exact sequence.
+package.json
+
+# Skill tool dependencies — installed per-user via `npm install`, never committed.
+node_modules/
+package-lock.json
+dist/
+.tshy/

sdk/contentunderstanding/ai-content-understanding/.github/skills/_shared/README.md

@@ -0,0 +1,81 @@
+# `_shared/` — library, not a skill
+
+Pure-TypeScript helpers used by the authoring skill scripts under
+`.github/skills/cu-sdk-author-analyzer*/`.
+
+The leading underscore marks this as a **library directory**, not a skill. It
+is intentionally excluded from the Copilot skill picker.
+
+Rules for `schemaValidator.ts` (the validator):
+
+- **No `@azure/*` imports.** No network calls. No I/O beyond reading /
+  parsing caller-provided JSON.
+- **No new runtime dependencies.** Native Node `fs` only.
+- **Stable, small, well-tested.** Anything here is referenced by multiple skill
+  scripts; breakage cascades.
+
+The CLI command modules (`extractLayoutCommand.ts`, `createAndTestCommand.ts`,
+`createAndTestRouterCommand.ts`) wrap the `ContentUnderstandingClient` from
+`@azure/ai-content-understanding`. They are allowed to import `@azure/*` since
+they're the bridge between the validator and the service.
+
+Current modules:
+
+- [`schemaValidator.ts`](src/schemaValidator.ts) — validates analyzer schema
+  JSON before any service call (catches `baseAnalyzerId` typos, missing
+  `fieldSchema`, missing `contentCategories` analyzer routes, etc.). Pure
+  TypeScript.
+- [`cli.ts`](src/cli.ts) — subcommand dispatcher.
+- [`clientHelpers.ts`](src/clientHelpers.ts) — client builder + raw-response
+  capture policy + JS-SDK serializer translation (`items` →
+  `itemDefinition`).
+- [`extractLayoutCommand.ts`](src/extractLayoutCommand.ts) — Stage 1: extract
+  document layout.
+- [`createAndTestCommand.ts`](src/createAndTestCommand.ts) — Stage 2
+  (single-type).
+- [`createAndTestRouterCommand.ts`](src/createAndTestRouterCommand.ts) —
+  Stage 2 (classify-and-route).
+
+## Install
+
+The tool is **intentionally NOT part of the pnpm workspace** — it's a
+standalone CLI that lives outside the published source tree under
+`.github/skills/_shared/`, so it has zero effect on the published
+`@azure/ai-content-understanding` artifact.
+
+To keep pnpm's repo-root `sdk/**` workspace glob from picking this directory
+up (which would fail CI because the tool's deps aren't in the top-level
+lockfile), the tracked file is `package.json.template` — the runtime
+`package.json` is `.gitignore`d and generated locally on install:
+
+```bash
+(cd .github/skills/_shared && \
+    [ -f package.json ] || cp package.json.template package.json && \
+    npm install)
+```
+
+The tool depends on the published `@azure/ai-content-understanding` package
+from npm, not the in-tree source, so contributors can iterate without first
+running a repo-root build.
+
+## Run
+
+```bash
+(cd .github/skills/_shared && \
+    node_modules/.bin/tsx src/cli.ts extract-layout \
+    --input <file-or-folder> --output <dir>)
+```
+
+Or, with the npm script wrapper:
+
+```bash
+(cd .github/skills/_shared && \
+    npm run cli -- extract-layout \
+    --input <file-or-folder> --output <dir>)
+```
+
+## Run tests
+
+```bash
+(cd .github/skills/_shared && npm test)
+```

sdk/contentunderstanding/ai-content-understanding/.github/skills/_shared/package.json.template

@@ -0,0 +1,23 @@
+{
+  "name": "cu-skill",
+  "version": "0.1.0",
+  "description": "Companion CLI for the cu-sdk-author-analyzer / cu-sdk-author-analyzer-classify-route GitHub Copilot skills. Wraps the @azure/ai-content-understanding SDK with three subcommands (extract-layout, create-and-test, create-and-test-router) and a pure-TypeScript schema validator.",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "cli": "tsx src/cli.ts",
+    "test": "tsx --test src/*.test.ts"
+  },
+  "dependencies": {
+    "@azure/ai-content-understanding": "^1.2.0-beta.2",
+    "@azure/core-auth": "^1.5.0",
+    "@azure/core-rest-pipeline": "^1.13.0",
+    "@azure/identity": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "~5.7.0"
+  }
+}

sdk/contentunderstanding/ai-content-understanding/.github/skills/_shared/src/cli.ts

@@ -0,0 +1,59 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+/*
+ * Subcommand dispatcher for the cu-skill tool. Mirrors Python's
+ * extract_layout.py / create_and_test.py / create_and_test_router.py
+ * entry points, the .NET Program.cs, and the Java Cli.java.
+ */
+
+import { runExtractLayout } from "./extractLayoutCommand.js";
+import { runCreateAndTest } from "./createAndTestCommand.js";
+import { runCreateAndTestRouter } from "./createAndTestRouterCommand.js";
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || isHelp(args[0])) {
+    printUsage();
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+  const subcommand = args[0];
+  const subArgs = args.slice(1);
+  let exit = 0;
+  switch (subcommand) {
+    case "extract-layout":
+      exit = await runExtractLayout(subArgs);
+      break;
+    case "create-and-test":
+      exit = await runCreateAndTest(subArgs);
+      break;
+    case "create-and-test-router":
+      exit = await runCreateAndTestRouter(subArgs);
+      break;
+    default:
+      console.error(`unknown subcommand: ${subcommand}`);
+      printUsage();
+      exit = 1;
+  }
+  process.exit(exit);
+}
+
+function isHelp(arg: string): boolean {
+  return arg === "-h" || arg === "--help" || arg === "help";
+}
+
+function printUsage(): void {
+  console.log("cu-skill — Content Understanding analyzer-authoring tool.");
+  console.log();
+  console.log("Subcommands:");
+  console.log("  extract-layout              extract document layout (stage 1)");
+  console.log("  create-and-test             validate, create, batch-test a single-type analyzer");
+  console.log("  create-and-test-router      classify-and-route variant (N inner + 1 outer)");
+  console.log();
+  console.log("Use '<subcommand> --help' for per-command flags.");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});