Perform code optimization and document cleanup (#1)

## Summary - add repository-wide quality tooling and verification scaffolding, including CI workflows, pnpm workspace setup, ESLint/Prettier/markdown checks, and generated-output verification helpers - reorganize skill sources and generation flow by introducing canonical `_source` variants, generator/manifests, reusable helper abstractions, and shared web-automation/browser utilities - clean up and expand documentation so the root README flows into docs and skill docs, with clearer development, reviewer, installer, and workflow guidance ## Notable changes - docs flow and consistency cleanup across `README.md`, `docs/README.md`, and related docs - new scripts for `check`, docs verification, generated-file verification, shell portability, and safe directory replacement - refactors in Atlassian and web-automation skill runtimes to reduce duplication and centralize reusable code - changelog, development documentation, and CI surface updates ## Test Plan - [ ] `pnpm run check` - [ ] review generated/manifests and skill sync outputs - [ ] smoke-check docs flow from `README.md` to `docs/README.md` to skill docs ## Notes - this branch currently includes tracked `skills/web-automation/shared/node_modules` content that should be reviewed carefully as potentially noisy/accidental committed artifacts Co-authored-by: Stefano Fiorini <stefano.fiorini@firsthorizon.com> Reviewed-on: #1
2026-05-04 04:41:34 +00:00
parent 2deab1c1b4
commit 251148c3ff
373 changed files with 28504 additions and 1281 deletions
@@ -0,0 +1,616 @@
+#!/usr/bin/env node
+/**
+ * generate-skills.mjs — shared-source generator for agent variants (M3, S-302)
+ *
+ * Generates every agent-variant directory (`skills/<skill>/<agent>/`) and
+ * `pi-package/skills/<skill>/` mirror from canonical sources.  Generated files
+ * carry file-type-aware headers; each generated root gets a non-self-referential
+ * `.generated-manifest.json`.
+ *
+ * Usage:
+ *   node scripts/generate-skills.mjs          # regenerate everything
+ *   pnpm run sync:pi                           # same via pnpm alias
+ *
+ * Exported helpers (used by verify-generated.mjs and tests):
+ *   detectFileType(filePath) → string
+ *   applyHeader(content, fileType, canonicalHint) → string
+ *   makePackageJsonContent(sourcePkg, skillName, agentName) → object
+ *   getGeneratedRoots(repoRoot?) → string[]
+ *   buildManifest(generatedRootAbs, generatedRootRel) → Promise<object>
+ *   generateSkills(repoRoot, options?) → Promise<{generatedRoots: string[]}>
+ */
+
+import {
+  lstat,
+  mkdir,
+  readdir,
+  readFile,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import crypto from "node:crypto";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const REPO_ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+
+// ── Constants ──────────────────────────────────────────────────────────────
+
+const MANIFEST_SCHEMA =
+  "https://ai-coding-skills.dev/schemas/generated-manifest/v1.json";
+const MANIFEST_GENERATOR = "scripts/generate-skills.mjs";
+const MANIFEST_FILENAME = ".generated-manifest.json";
+
+const AGENTS = ["claude-code", "codex", "cursor", "opencode", "pi"];
+
+/**
+ * Canonical list of all generated roots, relative to repo root.
+ * Verifier uses this to know which directories to walk.
+ */
+const GENERATED_ROOTS = [
+  // atlassian agent variants
+  "skills/atlassian/claude-code",
+  "skills/atlassian/codex",
+  "skills/atlassian/cursor",
+  "skills/atlassian/opencode",
+  "skills/atlassian/pi",
+  // web-automation agent variants
+  "skills/web-automation/claude-code",
+  "skills/web-automation/codex",
+  "skills/web-automation/cursor",
+  "skills/web-automation/opencode",
+  "skills/web-automation/pi",
+  // create-plan agent variants
+  "skills/create-plan/claude-code",
+  "skills/create-plan/codex",
+  "skills/create-plan/cursor",
+  "skills/create-plan/opencode",
+  "skills/create-plan/pi",
+  // do-task agent variants
+  "skills/do-task/claude-code",
+  "skills/do-task/codex",
+  "skills/do-task/cursor",
+  "skills/do-task/opencode",
+  "skills/do-task/pi",
+  // implement-plan agent variants
+  "skills/implement-plan/claude-code",
+  "skills/implement-plan/codex",
+  "skills/implement-plan/cursor",
+  "skills/implement-plan/opencode",
+  "skills/implement-plan/pi",
+  // reviewer-runtime pi variant
+  "skills/reviewer-runtime/pi",
+  // pi-package mirrors
+  "pi-package/skills/atlassian",
+  "pi-package/skills/create-plan",
+  "pi-package/skills/do-task",
+  "pi-package/skills/implement-plan",
+  "pi-package/skills/web-automation",
+];
+
+// ── File-type detection ────────────────────────────────────────────────────
+
+/**
+ * Classify a file path into a header policy category.
+ * @param {string} filePath - Relative or absolute path to the file.
+ * @returns {'markdown'|'shell'|'ts'|'js'|'json'|'yaml'|'jsonc'|'unknown'}
+ */
+export function detectFileType(filePath) {
+  const base = path.basename(filePath);
+  const ext = path.extname(base).toLowerCase();
+
+  if (ext === ".md") return "markdown";
+  if (ext === ".sh") return "shell";
+  if (ext === ".ts") return "ts";
+  if (ext === ".js") return "js";
+  if (ext === ".jsonc") return "jsonc";
+  if (ext === ".json") return "json";
+  if (ext === ".yaml" || ext === ".yml") return "yaml";
+  return "unknown";
+}
+
+// ── Header insertion ──────────────────────────────────────────────────────
+
+const HEADER_MSG = (hint) =>
+  `⚠️ GENERATED FILE – do not edit directly. Edit the canonical source in ${hint} and run \`pnpm run sync:pi\`.`;
+
+/**
+ * Insert a file-type-aware generated-file header into content.
+ *
+ * Policy:
+ *   markdown  → HTML comment after YAML front matter (or at top if no front matter)
+ *   shell     → # comment after shebang (never before it)
+ *   ts/js     → // comment at top
+ *   jsonc     → // comment at top
+ *   yaml      → # comment at top  (pnpm-lock.yaml skipped by caller)
+ *   json      → no header (recorded in .generated-manifest.json)
+ *   unknown   → no header
+ *
+ * @param {string} content - Original file content.
+ * @param {string} fileType - Output of detectFileType().
+ * @param {string} canonicalHint - Human-readable hint to canonical source location.
+ * @returns {string} Content with header inserted, or original if no header applies.
+ */
+export function applyHeader(content, fileType, canonicalHint) {
+  const msg = HEADER_MSG(canonicalHint);
+
+  switch (fileType) {
+    case "markdown": {
+      // Insert HTML comment after YAML front matter closing ---, or at top
+      if (content.startsWith("---\n")) {
+        const closingIdx = content.indexOf("\n---\n", 4);
+        if (closingIdx !== -1) {
+          const after = closingIdx + 5; // length of "\n---\n"
+          const before = content.slice(0, after);
+          const rest = content.slice(after);
+          // Ensure the comment is on its own line, with a blank line before/after
+          return `${before}\n<!-- ${msg} -->\n${rest}`;
+        }
+      }
+      return `<!-- ${msg} -->\n${content}`;
+    }
+
+    case "shell": {
+      // Insert # comment AFTER shebang line (never before it)
+      const lines = content.split("\n");
+      if (lines[0].startsWith("#!")) {
+        return [lines[0], `# ${msg}`, ...lines.slice(1)].join("\n");
+      }
+      return `# ${msg}\n${content}`;
+    }
+
+    case "ts":
+    case "js":
+    case "jsonc": {
+      // Insert after shebang if present (TypeScript requires #! on line 1)
+      const lines = content.split("\n");
+      if (lines[0].startsWith("#!")) {
+        return [lines[0], `// ${msg}`, ...lines.slice(1)].join("\n");
+      }
+      return `// ${msg}\n${content}`;
+    }
+
+    case "yaml": {
+      return `# ${msg}\n${content}`;
+    }
+
+    case "json":
+    case "unknown":
+    default:
+      return content;
+  }
+}
+
+// ── package.json transformation ───────────────────────────────────────────
+
+/**
+ * Produce a modified package.json object with a unique scoped name and
+ * `"private": true` for an agent-variant generated root.
+ *
+ * @param {object} sourcePkg - Parsed source package.json object.
+ * @param {string} skillName - Skill identifier (e.g. "atlassian").
+ * @param {string} agentName - Agent identifier (e.g. "claude-code").
+ * @returns {object} New object (source is not mutated).
+ */
+export function makePackageJsonContent(sourcePkg, skillName, agentName) {
+  return {
+    ...sourcePkg,
+    name: `@ai-coding-skills/${skillName}-${agentName}`,
+    private: true,
+  };
+}
+
+// ── Generated-root list ───────────────────────────────────────────────────
+
+/**
+ * Return the authoritative list of generated roots as repo-relative paths.
+ * Callers (verify-generated.mjs) use this to know which directories to walk.
+ *
+ * @returns {string[]} Sorted array of relative paths.
+ */
+export function getGeneratedRoots() {
+  return [...GENERATED_ROOTS];
+}
+
+// ── Manifest construction ─────────────────────────────────────────────────
+
+/**
+ * Walk a directory recursively and return all file paths (abs).
+ * Skips node_modules.
+ */
+async function walkDir(dir) {
+  const results = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    if (entry.name === "node_modules") continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const sub = await walkDir(full);
+      results.push(...sub);
+    } else if (entry.isFile()) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Build a .generated-manifest.json object for a generated root.
+ *
+ * The manifest lists every file in the generated root EXCEPT itself.
+ * Files are sorted by relative path for stable canonical serialization.
+ *
+ * @param {string} generatedRootAbs - Absolute path to the generated root directory.
+ * @param {string} generatedRootRel - Repo-relative path (e.g. "skills/create-plan/pi").
+ * @returns {Promise<object>} Manifest object (not yet serialized to disk).
+ */
+export async function buildManifest(generatedRootAbs, generatedRootRel) {
+  const allFiles = await walkDir(generatedRootAbs);
+  const entries = [];
+
+  for (const absPath of allFiles) {
+    const relPath = path.relative(generatedRootAbs, absPath).replace(/\\/g, "/");
+
+    // Non-self-referential: the manifest never lists itself
+    if (relPath === MANIFEST_FILENAME) continue;
+
+    const contentBuf = await readFile(absPath);
+    const sha256 = crypto.createHash("sha256").update(contentBuf).digest("hex");
+
+    const st = await lstat(absPath);
+    const mode = (st.mode & 0o777).toString(8).padStart(3, "0");
+
+    entries.push({
+      path: relPath,
+      kind: "file",
+      mode,
+      sha256,
+    });
+  }
+
+  entries.sort((a, b) => a.path.localeCompare(b.path));
+
+  return {
+    $schema: MANIFEST_SCHEMA,
+    generator: MANIFEST_GENERATOR,
+    generatedRoot: generatedRootRel,
+    files: entries,
+  };
+}
+
+// ── Core generation helpers ───────────────────────────────────────────────
+
+/**
+ * Copy a single file from source to destination, inserting a header.
+ * Skips header for:
+ *   - pnpm-lock.yaml (managed by pnpm, would be stripped on next install)
+ *   - JSON files (per header policy, no in-file header)
+ *   - node_modules (never copied)
+ */
+async function copyWithHeader(srcAbs, dstAbs, canonicalHint) {
+  const basename = path.basename(srcAbs);
+  // Skip pnpm-lock.yaml header (pnpm regenerates without comment)
+  const skipHeader = basename === "pnpm-lock.yaml";
+
+  const raw = await readFile(srcAbs, "utf8");
+  const fileType = skipHeader ? "unknown" : detectFileType(srcAbs);
+  const content = applyHeader(raw, fileType, canonicalHint);
+
+  await mkdir(path.dirname(dstAbs), { recursive: true });
+  await writeFile(dstAbs, content, "utf8");
+}
+
+/**
+ * Recursively copy a directory tree, adding headers to text files.
+ */
+async function copyDirWithHeaders(srcDir, dstDir, canonicalHint) {
+  const entries = await readdir(srcDir, { withFileTypes: true });
+  await mkdir(dstDir, { recursive: true });
+
+  for (const entry of entries) {
+    if (entry.name === "node_modules") continue;
+    const src = path.join(srcDir, entry.name);
+    const dst = path.join(dstDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDirWithHeaders(src, dst, canonicalHint);
+    } else if (entry.isFile()) {
+      await copyWithHeader(src, dst, canonicalHint);
+    }
+  }
+}
+
+/**
+ * Write a .generated-manifest.json file into a generated root.
+ */
+async function writeManifest(generatedRootAbs, generatedRootRel) {
+  const manifest = await buildManifest(generatedRootAbs, generatedRootRel);
+  const dstPath = path.join(generatedRootAbs, MANIFEST_FILENAME);
+  await writeFile(dstPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+}
+
+// ── Skill-family generators ───────────────────────────────────────────────
+
+/**
+ * Generate one agent variant for a "skills-only" skill
+ * (create-plan, do-task, implement-plan).
+ *
+ * Canonical source: skills/<skill>/_source/<agent>/
+ * Generated root:   skills/<skill>/<agent>/
+ *
+ * @param {string} writeRoot - Root directory to write output into (defaults to repoRoot).
+ */
+async function generateSkillOnlyVariant(repoRoot, writeRoot, skillName, agentName, generatedRootRel) {
+  const sourceDir = path.join(repoRoot, "skills", skillName, "_source", agentName);
+  const targetDir = path.join(writeRoot, generatedRootRel);
+  const canonicalHint = `skills/${skillName}/_source/${agentName}/`;
+
+  // Clear previous generated content (preserve node_modules if any)
+  await clearGeneratedRoot(targetDir);
+
+  // Copy all files from source with headers
+  await copyDirWithHeaders(sourceDir, targetDir, canonicalHint);
+
+  // Write manifest
+  await writeManifest(targetDir, generatedRootRel);
+}
+
+/**
+ * Generate one agent variant for a "scripts+skill" skill
+ * (atlassian, web-automation).
+ *
+ * For atlassian:
+ *   - SKILL.md from skills/atlassian/_source/<agent>/SKILL.md
+ *   - scripts/* from skills/atlassian/shared/scripts/
+ *     (only src/, tsconfig.json, pnpm-lock.yaml — not tests/ or scripts/sync-*)
+ *
+ * For web-automation:
+ *   - SKILL.md from skills/web-automation/_source/<agent>/SKILL.md
+ *   - scripts/* from skills/web-automation/shared/
+ *
+ * @param {string} [packageAgentName] - Override the agent name used only for the
+ *   package.json `name` field.  Defaults to `agentName`.  Use this to give
+ *   pi-package mirrors a distinct name (e.g. "pi-mirror") so workspace package
+ *   names are unique even when two roots share the same source agent.
+ */
+async function generateScriptsSkillVariant(
+  repoRoot,
+  writeRoot,
+  skillName,
+  agentName,
+  generatedRootRel,
+  config,
+  packageAgentName,
+) {
+  const targetDir = path.join(writeRoot, generatedRootRel);
+  await clearGeneratedRoot(targetDir);
+
+  // 1. Copy SKILL.md from per-agent canonical source
+  const skillMdSrc = path.join(repoRoot, "skills", skillName, "_source", agentName, "SKILL.md");
+  const skillMdDst = path.join(targetDir, "SKILL.md");
+  const skillMdHint = `skills/${skillName}/_source/${agentName}/SKILL.md`;
+  await copyWithHeader(skillMdSrc, skillMdDst, skillMdHint);
+
+  // 2. Copy scripts
+  const scriptsTargetDir = path.join(targetDir, "scripts");
+  await mkdir(scriptsTargetDir, { recursive: true });
+
+  const canonicalScripts = path.join(repoRoot, config.canonicalScripts);
+  const scriptsHint = `${config.canonicalScripts}/`;
+
+  for (const entry of config.scriptFiles) {
+    const srcPath = path.join(canonicalScripts, entry);
+    const dstPath = path.join(scriptsTargetDir, entry); // scriptsTargetDir already uses writeRoot
+
+    // Check if source exists
+    let st;
+    try {
+      st = await lstat(srcPath);
+    } catch {
+      continue; // skip if file doesn't exist in canonical
+    }
+
+    if (st.isDirectory()) {
+      await copyDirWithHeaders(srcPath, dstPath, scriptsHint);
+    } else {
+      await copyWithHeader(srcPath, dstPath, scriptsHint);
+    }
+  }
+
+  // 3. Generate modified package.json
+  const srcPkgPath = path.join(canonicalScripts, "package.json");
+  const srcPkg = JSON.parse(await readFile(srcPkgPath, "utf8"));
+
+  let targetPkg = makePackageJsonContent(srcPkg, skillName, packageAgentName ?? agentName);
+
+  // For atlassian variants, strip test/sync scripts (not in agent variants)
+  if (skillName === "atlassian") {
+    const agentScripts = {};
+    for (const [k, v] of Object.entries(targetPkg.scripts ?? {})) {
+      if (k !== "test" && k !== "sync:agents") agentScripts[k] = v;
+    }
+    targetPkg = { ...targetPkg, scripts: agentScripts };
+  }
+
+  const dstPkgPath = path.join(scriptsTargetDir, "package.json");
+  await writeFile(dstPkgPath, JSON.stringify(targetPkg, null, 2) + "\n", "utf8");
+
+  // 4. Write manifest
+  await writeManifest(targetDir, generatedRootRel);
+}
+
+/**
+ * Generate the reviewer-runtime pi variant from the non-Pi canonical scripts.
+ *
+ * Canonical source: skills/reviewer-runtime/{run-review.sh,notify-telegram.sh}
+ * Generated root:   skills/reviewer-runtime/pi/
+ *
+ * The pi variant is byte-identical to the canonical except for:
+ *   - A generated # comment after the shebang (replaces old "keep in sync" comment)
+ *
+ * @param {string} writeRoot - Root directory to write output into (defaults to repoRoot).
+ */
+async function generateReviewerRuntimePi(repoRoot, writeRoot) {
+  const srcDir = path.join(repoRoot, "skills", "reviewer-runtime");
+  const dstDir = path.join(writeRoot, "skills", "reviewer-runtime", "pi");
+  const canonicalHint = "skills/reviewer-runtime/";
+
+  // Clear old generated content (preserve tests/ which is canonical)
+  await clearGeneratedRoot(dstDir);
+
+  for (const fname of ["run-review.sh", "notify-telegram.sh"]) {
+    const srcPath = path.join(srcDir, fname);
+    const dstPath = path.join(dstDir, fname);
+
+    const raw = await readFile(srcPath, "utf8");
+    let content = applyHeader(raw, "shell", `${canonicalHint}${fname}`);
+
+    await mkdir(path.dirname(dstPath), { recursive: true });
+    await writeFile(dstPath, content, "utf8");
+
+    // Preserve executable bit
+    const st = await lstat(srcPath);
+    if (st.mode & 0o100) {
+      const { chmod } = await import("node:fs/promises");
+      await chmod(dstPath, 0o755);
+    }
+  }
+
+  // Write manifest (generatedRootRel is always relative to repo root, not writeRoot)
+  await writeManifest(dstDir, "skills/reviewer-runtime/pi");
+}
+
+/**
+ * Clear generated content in a root, preserving:
+ *   - node_modules (installed by pnpm) — at any depth
+ *   - .generated-manifest.json (will be rewritten after generation)
+ *
+ * Subdirectories are always recursed into before removal so that
+ * node_modules trees nested at any depth (e.g. scripts/node_modules inside
+ * atlassian or web-automation variants) are preserved.
+ */
+async function clearGeneratedRoot(rootDir) {
+  let entries;
+  try {
+    entries = await readdir(rootDir, { withFileTypes: true });
+  } catch {
+    return; // dir doesn't exist yet — nothing to clear
+  }
+
+  for (const entry of entries) {
+    if (entry.name === "node_modules") continue;
+    if (entry.name === MANIFEST_FILENAME) continue;
+    const fullPath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      // Always recurse so node_modules at any depth is preserved.
+      await clearGeneratedRoot(fullPath);
+      // Remove the directory only if nothing protected remains inside it.
+      const remaining = await readdir(fullPath).catch(() => []);
+      if (remaining.length === 0) {
+        await rm(fullPath, { recursive: true, force: true });
+      }
+    } else {
+      await rm(fullPath, { force: true });
+    }
+  }
+}
+
+// ── Skill configurations ──────────────────────────────────────────────────
+
+const SCRIPTS_SKILL_CONFIGS = {
+  atlassian: {
+    canonicalScripts: "skills/atlassian/shared/scripts",
+    // Files to copy from canonicalScripts into each agent's scripts/ dir
+    scriptFiles: ["src", "tsconfig.json", "pnpm-lock.yaml"],
+  },
+  "web-automation": {
+    canonicalScripts: "skills/web-automation/shared",
+    scriptFiles: [
+      "auth.ts",
+      "browse.ts",
+      "check-install.js",
+      "extract.js",
+      "flow.ts",
+      "lib",
+      "scan-local-app.ts",
+      "scrape.ts",
+      "test-full.ts",
+      "test-minimal.ts",
+      "test-profile.ts",
+      "tsconfig.json",
+      "turndown-plugin-gfm.d.ts",
+      "pnpm-lock.yaml",
+    ],
+  },
+};
+
+// ── Main generator ────────────────────────────────────────────────────────
+
+/**
+ * Regenerate all agent variants from canonical sources.
+ *
+ * @param {string} repoRoot - Absolute path to repo root (canonical sources are read from here).
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun] - If true, don't write files (future use).
+ * @param {string} [options.targetRoot] - Write generated output here instead of `repoRoot`.
+ *   Canonical sources are always read from `repoRoot`.  Use this to generate into a
+ *   temp directory for drift detection without modifying on-disk files.
+ * @returns {Promise<{generatedRoots: string[]}>}
+ */
+export async function generateSkills(repoRoot = REPO_ROOT, options = {}) {
+  const { dryRun = false, targetRoot } = options;
+  const writeRoot = targetRoot ?? repoRoot;
+  if (dryRun) {
+    return { generatedRoots: GENERATED_ROOTS };
+  }
+
+  const skillOnlySkills = ["create-plan", "do-task", "implement-plan"];
+
+  // 1. Generate skill-only skills (create-plan, do-task, implement-plan)
+  for (const skillName of skillOnlySkills) {
+    for (const agentName of AGENTS) {
+      const rootRel = `skills/${skillName}/${agentName}`;
+      await generateSkillOnlyVariant(repoRoot, writeRoot, skillName, agentName, rootRel);
+    }
+    // pi-package mirror (same source as pi variant)
+    const piPackageRel = `pi-package/skills/${skillName}`;
+    await generateSkillOnlyVariant(repoRoot, writeRoot, skillName, "pi", piPackageRel);
+  }
+
+  // 2. Generate scripts skills (atlassian, web-automation)
+  for (const [skillName, config] of Object.entries(SCRIPTS_SKILL_CONFIGS)) {
+    for (const agentName of AGENTS) {
+      const rootRel = `skills/${skillName}/${agentName}`;
+      await generateScriptsSkillVariant(repoRoot, writeRoot, skillName, agentName, rootRel, config);
+    }
+    // pi-package mirror: same source as pi variant but a distinct package name
+    // ("pi-mirror" suffix) so the workspace has no duplicate package names.
+    const piPackageRel = `pi-package/skills/${skillName}`;
+    await generateScriptsSkillVariant(repoRoot, writeRoot, skillName, "pi", piPackageRel, config, "pi-mirror");
+  }
+
+  // 3. Generate reviewer-runtime pi variant
+  await generateReviewerRuntimePi(repoRoot, writeRoot);
+
+  return { generatedRoots: GENERATED_ROOTS };
+}
+
+// ── CLI entry point ────────────────────────────────────────────────────────
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const result = await generateSkills(REPO_ROOT);
+    console.log(
+      `Generated ${result.generatedRoots.length} roots from canonical sources.`,
+    );
+    process.exit(0);
+  } catch (err) {
+    console.error("generate-skills: fatal error:", err.message ?? err);
+    process.exit(1);
+  }
+}