fix(skills): regenerate the 20 SKILL.md files drifted since #14381

changelog.d/maintenance/15945-skills-sync-regen.md

@@ -0,0 +1,2 @@
+- **fix(skills):** regenerate the 20 `SKILL.md` files that had drifted from their generator (#15945). `check:agent-skills-sync` was failing on the `release/v3.8.52` tip, which blocked every PR into the branch rather than just one: `.mergify.yml` names `Merge integrity (changelog + generated skills)` as the always-on anchor that must be an affirmative `check-success`, and the only failure it tolerates is `Build (advisory)`. The cause was #14381 (`4df9ceae03`), which extracted the curl examples out of `src/lib/agentSkills/generator.ts` into the new `apiOperationExample.ts` and replaced the hardcoded `https://localhost:20128` with `resolveOmniRouteBaseUrl()`, whose default is `http://localhost:20128`; the committed files were never regenerated, so every generated example disagreed with the generator from that commit onward. This is the mechanical output of `node --import tsx/esm scripts/skills/generate-agent-skills.mjs --apply` with no base-url env vars set — the documented default and the environment CI runs in — so the diff is the `https:` → `http:` scheme change plus the endpoint-reference content that moved with it. No instruction text is added or edited, which matters because `skills/**/SKILL.md` is an agent-instruction surface. The gate goes from 20 drifted to 0 (`Generated: 0 · Unchanged: 46 · Errors: 0`), with `check:changelog-integrity` and `check:docs-all` also clean. One latent cause is deliberately left alone: `apiOperationExample.ts` and `cliConfigurationExample.ts` resolve the base URL from `process.env` (`OMNIROUTE_BASE_URL`, `BASE_URL`, `NEXT_PUBLIC_BASE_URL`, `PORT`, …), so anyone running `--apply` with one of those set re-bakes their own host into the committed artifact and re-opens this drift. Making generation env-independent touches shared runtime code used by the A2A skills, the MCP internal fetch and two API routes, so it belongs in its own PR rather than a base-red drain.
+- **fix(skills):** follow the current `sync pull [outPath]` archive-download contract from #16707, remove the unsupported source/merge/replace/dry-run options, and generate a concrete archive filename in the executable example. The regression checks both the generated and published skill against the real CLI registry; the earlier base-URL determinism fix remains separate in #15948.

skills/cli-backup-sync/SKILL.md

@@ -234,7 +234,7 @@ omniroute sync push
 **Example:**
 
 ```bash
-omniroute sync pull [outPath]
+omniroute sync pull omniroute-export.tar.gz
 ```
 
 ### `sync bundle <outPath>`

src/lib/agentSkills/generator.ts

@@ -32,8 +32,9 @@ const GENERATED_COMMENT =
 const CUSTOM_START_MARKER = "<!-- skill:custom-start -->";
 const CUSTOM_END_MARKER = "<!-- skill:custom-end -->";
 
-// Runnable examples for commands whose syntax alone would omit safety-critical flags.
+// Runnable examples for commands that need concrete arguments or safety-critical flags.
 const CLI_PREVIEW_EXAMPLES: Record<string, string> = {
+  "sync pull [outPath]": "sync pull omniroute-export.tar.gz",
   "models test-add <model>":
     "models test-add example-model --provider example-provider --connection example-connection --dry-run",
 };

tests/unit/agentSkills-sync-pull-example.test.ts

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import test from "node:test";
+import { buildSkillMarkdown } from "../../src/lib/agentSkills/generator.ts";
+import { parseCliRegistry } from "../../src/lib/agentSkills/cliRegistryParser.ts";
+
+test("sync pull skill uses a concrete archive path and no removed flags", () => {
+  const sources = {
+    openapi: { paths: new Map(), areas: new Map() },
+    cliRegistry: parseCliRegistry(),
+  };
+  const { body } = buildSkillMarkdown("cli-backup-sync", sources);
+  const published = fs.readFileSync(
+    new URL("../../skills/cli-backup-sync/SKILL.md", import.meta.url),
+    "utf8"
+  );
+  for (const markdown of [body, published]) {
+    const section = markdown.split("### `sync pull [outPath]`\n")[1]?.split("\n### ")[0];
+    assert.ok(section, "the optional output-path signature must match the real CLI registry");
+    assert.match(section, /```bash\nomniroute sync pull omniroute-export\.tar\.gz\n```/);
+    assert.doesNotMatch(section, /--(?:source|merge|replace|dry-run)\b/);
+    assert.doesNotMatch(section, /```bash\nomniroute sync pull \[outPath\]/);
+  }
+});