argsbarg 4.0.3 → 4.0.4

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.0.4] - 2026-06-25
+
+### Added
+
+- **MCP docs topic resources** — when `docs.enabled` and `mcpServer.enabled`, each user `docs.topics` key is auto-exposed as `<mcpId>://docs/<topicKey>` (`text/markdown`, same body as `myapp docs <topic>`). Built-in `docs schema` / `api` / `skill` / `mcp` are not auto-exposed.
+
+### Changed
+
+- **Claude Code plugin skill** — `mcp bundle` plugin zip includes an MCP routing `SKILL.md` only (no shell catalog, no `reference.md`). `install --skill` unchanged.
+- **Validation** — `mcpServer.resources` URIs that collide with auto docs topic resources are rejected at schema validation time.
+
 ## [4.0.3] - 2026-06-24
 
 
@@ -458,7 +469,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v4.0.3...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v4.0.4...HEAD
+[4.0.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.0.4
 [4.0.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.0.3
 [4.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.0.2
 [4.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.0.1

package/README.md

@@ -6,7 +6,7 @@
 [![npm version](https://img.shields.io/npm/v/argsbarg.svg)](https://www.npmjs.com/package/argsbarg)
 [![Bun](https://img.shields.io/badge/Bun-%23000000.svg?logo=bun&logoColor=white)](https://bun.sh)
 
-Build beautiful, well-behaved CLI apps with Bun — **no third-party runtime dependencies**. 
+Build beautiful, well-behaved CLI+MCP apps with Bun — **no third-party runtime dependencies**. 
 
 Why another CLI parser?
 

package/docs/ai-skills.md

@@ -48,6 +48,8 @@ Skills describe **shell invocation only** — no MCP setup, `mcp.json`, or `tool
 
 `SKILL.md` is the routing index; `reference.md` matches `docs api`. Prefer `install --skill` over `docs skill` for agents. See [cli-program.md](cli-program.md).
 
+**Claude Code plugin** (`mcp bundle` → `dist/claude-plugin/<name>.zip`) ships a separate MCP pointer skill (`SKILL.md` only) that routes agents to the bundled MCP server. `install --skill` remains shell-only.
+
 See also:
 
 - [Bundled docs](bundled-docs.md) — `docs` config and compile-time imports

package/docs/bundled-docs.md

@@ -104,6 +104,7 @@ All `docs` subcommands are hidden from MCP `tools/list` (`mcpTool: { enabled: fa
 | `docs api` | Print command tree markdown to stdout |
 | `docs schema` | Print command tree JSON to stdout |
 | `docs` | Bundled markdown topics on stdout |
+| MCP docs topic resources | User `docs.topics` on the MCP wire (`<mcpId>://docs/<topic>`) when docs + MCP enabled |
 | `mcp` | Callable tools + schema resource |
 
 Do not declare a top-level command named **`docs`** when `docs.enabled` is `true` — it is reserved.

package/docs/mcp.md

@@ -244,6 +244,20 @@ The built-in schema resource (default URI `<sanitized-key>://schema`, e.g. `nest
 | MIME type | `application/json` |
 | Contents | `cliSchemaJson(root)` — handlers omitted, built-ins excluded |
 
+### Auto docs topic resources
+
+When both **`docs.enabled`** and **`mcpServer.enabled`** are true, each user key in **`docs.topics`** is also exposed as an MCP resource:
+
+| Property | Value |
+| --- | --- |
+| URI | `<sanitized root key>://docs/<topicKey>` (e.g. `myapp://docs/readme`) |
+| MIME type | `text/markdown` |
+| Contents | Same body as `myapp docs <topicKey>` |
+
+Built-in docs subcommands (`schema`, `api`, `skill`, `mcp`) are **not** auto-exposed — use the schema resource, `install --skill`, or CLI `docs` instead. `docs` subcommands remain hidden from MCP `tools/list`.
+
+Custom `mcpServer.resources` URIs must not collide with the schema URI or any auto docs topic URI (validated at program compile time).
+
 Add custom resources on the program root:
 
 ```typescript
@@ -261,7 +275,7 @@ mcpServer: {
 },
 ```
 
-URIs must be unique and must not equal `schemaResourceUri`. `load()` runs synchronously at `resources/read` time.
+URIs must be unique and must not equal `schemaResourceUri` or any auto docs topic URI (`<mcpId>://docs/<topicKey>`). `load()` runs synchronously at `resources/read` time.
 
 ## Invocation context
 
@@ -384,9 +398,10 @@ Manifest metadata is generated from your schema (`mcpServerId`, tools, `program.
 .mcp.json
 bin/myapp
 skills/<dirName>/SKILL.md
-skills/<dirName>/reference.md
 ```
 
+The bundled `SKILL.md` is an **MCP routing stub** — it tells Claude to use the plugin’s MCP toolset (server id, `tools/list`, schema resource). It is not a shell CLI catalog and does not include `reference.md`. Use **`install --skill`** for a persisted shell-oriented skill bundle.
+
 Load locally with `claude --plugin-dir ./dist/claude-plugin/myapp.zip`.
 
 Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `install --mcp` and MCP hosts). Use **`install --mcp`** for Cursor, Claude Code, Claude Desktop, and OpenCode JSON config.

package/examples/consumer-app/README.md

@@ -11,6 +11,7 @@
 | `outputSchema` | `src/commands/status/types.ts` (`StatusJsonOutput`) → `schemas/outputSchemas.ts` |
 | Schemagen | `scripts/schemagen.ts` + `scripts/schemagen/discover-schema-roots.ts` |
 | Handler access | `ctx.appConfig` in `src/program.ts` |
+| MCP doc topics | `docs.topics` auto-exposed as `<key>://docs/<topic>` resources when docs + MCP enabled |
 | Package import | `from "argsbarg"` (not relative to argsbarg `src/`) |
 
 ## Quick start (in this repo)

package/examples/consumer-app/src/program.ts

@@ -8,6 +8,7 @@ import {
   CliOptionKind,
   type CliProgram,
 } from "argsbarg";
+import readmeText from "../README.md" with { type: "text" };
 import { APP_CONFIG_JSON_SCHEMA } from "../schemas/configSchemas.ts";
 import { STATUS_JSON_OUTPUT_SCHEMA } from "../schemas/outputSchemas.ts";
 import type { StatusJsonOutput } from "./commands/status/types.ts";
@@ -46,21 +47,12 @@ export const program = {
     enabled: true,
     topics: {
       readme: {
-        text: "# consumer-app\n\nKitchen-sink argsbarg reference. Copy this layout into a new CLI repo.\n",
+        text: readmeText,
       },
     },
   },
   mcpServer: {
     enabled: true,
-    resources: [
-      {
-        uri: "consumer-app://readme",
-        name: "readme",
-        description: "Bundled readme topic.",
-        mimeType: "text/plain",
-        load: () => "# consumer-app\n\nKitchen-sink reference.\n",
-      },
-    ],
   },
   install: {
     updateGetLatest: async () => ({

package/examples/mcp-test.ts

@@ -45,6 +45,12 @@ const program = {
       },
     ],
   },
+  docs: {
+    enabled: true,
+    topics: {
+      readme: { text: "# MCP test readme\n" },
+    },
+  },
   commands: [
     {
       key: "echo-env",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "4.0.3",
+  "version": "4.0.4",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/src/docs/mcp-guide.ts

@@ -10,6 +10,8 @@ import {
 } from "../mcp/tools.ts";
 import { collectOptionDefs } from "../parse.ts";
 import { CliOptionKind, type CliProgram } from "../types.ts";
+import { resolveDocsTopicResourceUri } from "./mcp-resources.ts";
+import { docsEnabled, docsUserTopicKeys } from "./resolve.ts";
 
 /** Extra host notes for generated `docs mcp` (manual fallbacks and ChatGPT Connectors). */
 function appendManualHostSetup(lines: string[], root: CliProgram, serverId: string): void {
@@ -210,10 +212,19 @@ export function generateMcpGuide(root: CliProgram): string {
     "| `tools/list` | Callable tools for exposed leaf commands |",
     "| `tools/call` | Runs handlers headlessly; JSON stdout becomes `structuredContent` when valid |",
     `| Schema resource | \`${schemaUri}\` — same JSON as \`${root.key} docs schema\` |`,
-    "",
-    "## Exposed tools",
-    "",
   );
+  if (docsEnabled(root)) {
+    const docs = root.docs;
+    if (docs) {
+      for (const key of docsUserTopicKeys(docs)) {
+        const uri = resolveDocsTopicResourceUri(root, key);
+        lines.push(
+          `| Docs topic \`${key}\` | \`${uri}\` — same markdown as \`${root.key} docs ${key}\` |`,
+        );
+      }
+    }
+  }
+  lines.push("", "## Exposed tools", "");
 
   if (tools.length === 0) {
     lines.push("(No MCP tools exposed.)", "");

package/src/docs/mcp-resources.test.ts

@@ -0,0 +1,63 @@
+import { expect, test } from "bun:test";
+import type { CliProgram } from "../types.ts";
+import {
+  defaultDocsTopicResourceUri,
+  docsMcpResources,
+  reservedDocsTopicResourceUris,
+  resolveDocsTopicResourceUri,
+} from "./mcp-resources.ts";
+
+function fixture(opts?: { docs?: boolean; mcp?: boolean }): CliProgram {
+  const docs = opts?.docs !== false;
+  const mcp = opts?.mcp !== false;
+  return {
+    key: "my-app",
+    version: "1.0.0",
+    description: "Test.",
+    ...(docs
+      ? {
+          docs: {
+            enabled: true,
+            topics: {
+              readme: { text: "# Readme\n", description: "User guide." },
+              arch: { text: "# Arch\n" },
+            },
+          },
+        }
+      : {}),
+    ...(mcp ? { mcpServer: { enabled: true } } : {}),
+    handler: () => {},
+  };
+}
+
+test("defaultDocsTopicResourceUri", () => {
+  expect(defaultDocsTopicResourceUri("my_app", "readme")).toBe("my_app://docs/readme");
+});
+
+test("resolveDocsTopicResourceUri sanitizes program key", () => {
+  expect(resolveDocsTopicResourceUri(fixture(), "readme")).toBe("my_app://docs/readme");
+});
+
+test("docsMcpResources when docs and MCP enabled", () => {
+  const resources = docsMcpResources(fixture());
+  expect(resources.map((r) => r.uri)).toEqual(["my_app://docs/readme", "my_app://docs/arch"]);
+  expect(resources[0]?.name).toBe("readme");
+  expect(resources[0]?.mimeType).toBe("text/markdown");
+  expect(resources[0]?.description).toBe("User guide.");
+  expect(resources[0]?.load()).toBe("# Readme\n");
+});
+
+test("docsMcpResources empty when docs disabled", () => {
+  expect(docsMcpResources(fixture({ docs: false }))).toEqual([]);
+});
+
+test("docsMcpResources empty when MCP disabled", () => {
+  expect(docsMcpResources(fixture({ mcp: false }))).toEqual([]);
+});
+
+test("reservedDocsTopicResourceUris matches docsMcpResources URIs", () => {
+  const program = fixture();
+  expect(reservedDocsTopicResourceUris(program)).toEqual(
+    docsMcpResources(program).map((r) => r.uri),
+  );
+});

package/src/docs/mcp-resources.ts

@@ -0,0 +1,68 @@
+/*
+Auto MCP resources for user docs.topics when docs and MCP are both enabled.
+*/
+
+import type { CliProgram } from "../types.ts";
+import {
+  docsEnabled,
+  docsTopicContent,
+  docsTopicDescription,
+  docsUserTopicKeys,
+} from "./resolve.ts";
+
+/** Default URI pattern for a docs topic MCP resource (`<mcpId>://docs/<topicKey>`). */
+export function defaultDocsTopicResourceUri(mcpId: string, topicKey: string): string {
+  return `${mcpId}://docs/${topicKey}`;
+}
+
+/** Sanitized MCP server id from program key (matches mcpServerId in mcp/tools.ts). */
+function mcpIdFromProgram(program: CliProgram): string {
+  return program.key.replace(/[^a-zA-Z0-9]/g, "_");
+}
+
+/** Resolved URI for one user docs topic resource. */
+export function resolveDocsTopicResourceUri(program: CliProgram, topicKey: string): string {
+  return defaultDocsTopicResourceUri(mcpIdFromProgram(program), topicKey);
+}
+
+/** All auto-generated docs topic resources (empty when docs or MCP disabled). */
+export function docsMcpResources(program: CliProgram): {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType: string;
+  load: () => string;
+}[] {
+  if (!docsEnabled(program) || program.mcpServer?.enabled !== true) {
+    return [];
+  }
+  const docs = program.docs;
+  if (!docs) {
+    return [];
+  }
+  return docsUserTopicKeys(docs).map((key) => {
+    const topic = docs.topics[key];
+    if (!topic) {
+      throw new Error(`docs topic missing: ${key}`);
+    }
+    return {
+      uri: resolveDocsTopicResourceUri(program, key),
+      name: key,
+      description: docsTopicDescription(key, topic.description),
+      mimeType: "text/markdown",
+      load: () => docsTopicContent(program, key),
+    };
+  });
+}
+
+/** Reserved MCP resource URIs from auto docs topics (for validation). */
+export function reservedDocsTopicResourceUris(program: CliProgram): string[] {
+  if (!docsEnabled(program) || program.mcpServer?.enabled !== true) {
+    return [];
+  }
+  const docs = program.docs;
+  if (!docs) {
+    return [];
+  }
+  return docsUserTopicKeys(docs).map((key) => resolveDocsTopicResourceUri(program, key));
+}

package/src/mcp/claude.test.ts

@@ -55,7 +55,7 @@ describe("claude plugin", () => {
     expect(paths.pluginZipPath).toBe(join(cwd, "dist", "claude-plugin", "myapp.zip"));
   });
 
-  test("packClaudePlugin writes zip with expected entries", () => {
+  test("packClaudePlugin writes zip with MCP pointer skill only", () => {
     const work = mkdtempSync(join(tmpdir(), "claude-plugin-test-"));
     try {
       const dist = join(work, "dist");
@@ -64,8 +64,14 @@ describe("claude plugin", () => {
       writeFileSync(binaryPath, "#!/bin/sh\n", { mode: 0o755 });
       const paths = defaultClaudePluginPaths(configFixture, work);
       packClaudePlugin(configFixture, { cwd: work, binaryPath });
-      const zipPath = paths.pluginZipPath;
-      expect(readFileSync(zipPath).length).toBeGreaterThan(0);
+      const zip = readFileSync(paths.pluginZipPath);
+      expect(zip.length).toBeGreaterThan(0);
+      const zipText = zip.toString("utf8");
+      expect(zipText).toContain("skills/myapp/SKILL.md");
+      expect(zipText).toContain("MCP toolset");
+      expect(zipText).toContain("Server id: `myapp`");
+      expect(zipText).not.toContain("skills/myapp/reference.md");
+      expect(zipText).not.toContain("Invoke via shell");
     } finally {
       rmSync(work, { recursive: true, force: true });
     }

package/src/mcp/claude.ts

@@ -17,11 +17,11 @@ import {
 import { tmpdir } from "node:os";
 import { basename, join, relative, resolve } from "node:path";
 import { buildPluginMcpEnvMapping, buildProgramUserConfig } from "../config/manifest.ts";
-import { generateSkillBundle } from "../skill/generate.ts";
-import { applySkillBundleHints } from "../skill/hint.ts";
+import { generatePluginSkillBundle } from "../skill/generate.ts";
+import { applyPluginSkillHint } from "../skill/hint.ts";
 import type { CliMcpBundleConfig, CliProgram } from "../types.ts";
 import { defaultMcpBundlePaths, type PackMcpBundleOpts } from "./bundle.ts";
-import { mcpServerId, sanitizeToolSegment } from "./tools.ts";
+import { mcpServerId } from "./tools.ts";
 import { zipStore } from "./zip.ts";
 
 const DIST_DIR = "dist";
@@ -116,13 +116,12 @@ function writePluginTree(
   binaryPath: string,
   binaryName: string,
 ): void {
-  const skillDirName = sanitizeToolSegment(program.key);
-  const bundle = generateSkillBundle(program, "claude");
-  const hinted = applySkillBundleHints(program, bundle.skillMd, bundle.referenceMd);
+  const bundle = generatePluginSkillBundle(program);
+  const skillMd = applyPluginSkillHint(program, bundle.skillMd);
 
   mkdirSync(join(pluginRoot, ".claude-plugin"), { recursive: true });
   mkdirSync(join(pluginRoot, "bin"), { recursive: true });
-  mkdirSync(join(pluginRoot, "skills", skillDirName), { recursive: true });
+  mkdirSync(join(pluginRoot, "skills", bundle.dirName), { recursive: true });
 
   writeFileSync(
     join(pluginRoot, ".claude-plugin", "plugin.json"),
@@ -133,8 +132,7 @@ function writePluginTree(
     `${JSON.stringify(generatePluginMcpJson(program, binaryName), null, 2)}\n`,
   );
   cpSync(binaryPath, join(pluginRoot, "bin", binaryName), { mode: 0o755 });
-  writeFileSync(join(pluginRoot, "skills", skillDirName, "SKILL.md"), hinted.skillMd);
-  writeFileSync(join(pluginRoot, "skills", skillDirName, "reference.md"), hinted.referenceMd);
+  writeFileSync(join(pluginRoot, "skills", bundle.dirName, "SKILL.md"), skillMd);
 }
 
 /**

package/src/mcp/tools.ts

@@ -3,6 +3,7 @@ This module maps CliProgram leaf nodes to MCP tool definitions and converts
 flat JSON tool arguments into argv for Cli.invoke.
 */
 
+import { docsMcpResources } from "../docs/mcp-resources.ts";
 import { cliResolveNotes } from "../help.ts";
 import { visibleOptions } from "../hidden.ts";
 import { collectOptionDefs } from "../parse.ts";
@@ -26,6 +27,8 @@ export function defaultMcpSchemaUri(mcpId: string): string {
   return `${mcpId}://schema`;
 }
 
+export { defaultDocsTopicResourceUri, resolveDocsTopicResourceUri } from "../docs/mcp-resources.ts";
+
 /** Sanitizes a command key segment for MCP tool names and server identity. */
 export function sanitizeToolSegment(key: string): string {
   return key.replace(/[^a-zA-Z0-9]/g, "_");
@@ -209,7 +212,7 @@ export function allMcpResources(root: CliProgram): McpResourceEntry[] {
     mimeType: r.mimeType ?? "text/plain",
     load: r.load,
   }));
-  return [builtIn, ...user];
+  return [builtIn, ...docsMcpResources(root), ...user];
 }
 
 /** Recursively collects MCP tool definitions from user leaf commands. */

package/src/mcp.integration.test.ts

@@ -480,9 +480,26 @@ test("MCP resources/list includes custom resource", async () => {
   const res = responses.get(10) as { result: { resources: { uri: string }[] } };
   const uris = res.result.resources.map((r) => r.uri);
   expect(uris).toContain("mcp_test://schema");
+  expect(uris).toContain("mcp_test://docs/readme");
   expect(uris).toContain("test://hello");
 });
 
+test("MCP resources/read returns docs topic resource body", async () => {
+  const responses = await mcpRequest(
+    [
+      {
+        jsonrpc: "2.0",
+        id: 13,
+        method: "resources/read",
+        params: { uri: "mcp_test://docs/readme" },
+      },
+    ],
+    { script: "examples/mcp-test.ts" },
+  );
+  const res = responses.get(13) as { result: { contents: { text: string }[] } };
+  expect(res.result.contents[0]?.text).toBe("# MCP test readme\n");
+});
+
 test("MCP resources/read returns custom resource body", async () => {
   const responses = await mcpRequest(
     [{ jsonrpc: "2.0", id: 11, method: "resources/read", params: { uri: "test://hello" } }],

package/src/parse.test.ts

@@ -20,7 +20,7 @@ import {
 } from "./mcp/tools.ts";
 import { ParseKind, parse, postParseValidate } from "./parse.ts";
 import { cliSchemaJson } from "./schema.ts";
-import { generateSkillBundle } from "./skill/generate.ts";
+import { generatePluginSkillBundle, generateSkillBundle } from "./skill/generate.ts";
 import { cliSkillInstall } from "./skill/install.ts";
 import {
   enumMcpFixture,
@@ -835,7 +835,7 @@ test("cliValidateProgram rejects resource URI matching default schema URI", () =
     },
     commands: [{ key: "x", description: "", handler: () => {} }],
   });
-  expect(() => cliValidateProgram(root)).toThrow(/conflicts with the built-in schema resource/);
+  expect(() => cliValidateProgram(root)).toThrow(/conflicts with built-in schema resource/);
 });
 
 test("cliValidateProgram rejects resource URI matching schemaResourceUri", () => {
@@ -849,7 +849,21 @@ test("cliValidateProgram rejects resource URI matching schemaResourceUri", () =>
     },
     commands: [{ key: "x", description: "", handler: () => {} }],
   });
-  expect(() => cliValidateProgram(root)).toThrow(/conflicts with the built-in schema resource/);
+  expect(() => cliValidateProgram(root)).toThrow(/conflicts with built-in schema resource/);
+});
+
+test("cliValidateProgram rejects resource URI matching auto docs topic", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    docs: { enabled: true, topics: { readme: { text: "# r\n" } } },
+    mcpServer: {
+      enabled: true,
+      resources: [{ uri: "app://docs/readme", name: "dup", load: () => "" }],
+    },
+    commands: [{ key: "x", description: "", handler: () => {} }],
+  });
+  expect(() => cliValidateProgram(root)).toThrow(/conflicts with auto docs topic resource/);
 });
 
 test("allMcpResources includes custom resources", () => {
@@ -867,6 +881,20 @@ test("allMcpResources includes custom resources", () => {
   expect(resources.map((r) => r.uri)).toContain("test://x");
 });
 
+test("allMcpResources includes docs topic resources", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    docs: { enabled: true, topics: { readme: { text: "# hi\n" } } },
+    mcpServer: { enabled: true },
+    commands: [{ key: "leaf", description: "", handler: () => {} }],
+  });
+  const resources = allMcpResources(root);
+  expect(resources.map((r) => r.uri)).toContain("app://docs/readme");
+  const readme = resources.find((r) => r.uri === "app://docs/readme");
+  expect(readme?.load()).toBe("# hi\n");
+});
+
 test("applyShellEnv merges PATH and preserves host vars", () => {
   const origPath = process.env.PATH ?? "";
   const origHome = process.env.HOME;
@@ -1116,6 +1144,20 @@ test("generateSkillBundle includes frontmatter and compact command index", () =>
   expect(bundle.referenceMd).not.toContain("```json");
 });
 
+test("generatePluginSkillBundle is MCP routing stub without shell catalog", () => {
+  const bundle = generatePluginSkillBundle(nestedMcpFixture);
+  expect(bundle.dirName).toBe("nested_ts");
+  expect(bundle.skillMd).toMatch(/^---\nname: nested_ts\n/);
+  expect(bundle.skillMd).toContain("MCP toolset");
+  expect(bundle.skillMd).toContain("Server id: `nested_ts`");
+  expect(bundle.skillMd).toContain("nested_ts://schema");
+  expect(bundle.skillMd).toContain("tools/list");
+  expect(bundle.skillMd).not.toContain("Invoke via shell");
+  expect(bundle.skillMd).not.toContain("reference.md");
+  expect(bundle.skillMd).not.toContain("`nested.ts stat owner lookup <path>`");
+  expect(bundle.skillMd).not.toContain("## Commands");
+});
+
 test("cliSkillInstall writes project Cursor skill files", () => {
   const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-"));
   const prev = process.cwd();

package/src/skill/generate.ts

@@ -4,7 +4,13 @@ This module generates Agent Skills content (SKILL.md + reference.md) from a CLI
 
 import { defaultConfigEntryTitle } from "../config/entry.ts";
 import { generateApiGuide } from "../docs/api-guide.ts";
-import { collectMcpTools, type McpToolDef, sanitizeToolSegment } from "../mcp/tools.ts";
+import {
+  collectMcpTools,
+  type McpToolDef,
+  mcpServerId,
+  resolveMcpSchemaUri,
+  sanitizeToolSegment,
+} from "../mcp/tools.ts";
 import { collectOptionDefs } from "../parse.ts";
 import { CliOptionKind, type CliProgram } from "../types.ts";
 
@@ -16,12 +22,28 @@ export interface SkillBundle {
   referenceMd: string;
 }
 
+/** MCP routing skill for Claude Code plugin zips (SKILL.md only). */
+export interface PluginSkillBundle {
+  dirName: string;
+  skillMd: string;
+}
+
 /** Truncates text to maxLen with ellipsis. */
 function truncate(text: string, maxLen: number): string {
   if (text.length <= maxLen) return text;
   return `${text.slice(0, maxLen - 1)}…`;
 }
 
+/** Builds MCP-oriented skill description for Claude plugin YAML frontmatter. */
+function pluginSkillDescription(root: CliProgram): string {
+  const tools = collectMcpTools(root);
+  const paths = tools.map((t) => (t.path.length > 0 ? t.path.join(" ") : root.key));
+  const sample = paths.slice(0, 5).join(", ");
+  const more = paths.length > 5 ? `, and ${paths.length - 5} more` : "";
+  const desc = `Use the ${root.key} MCP toolset (${sample}${more}). Use when the user mentions ${root.key}${paths.length > 0 ? `, ${paths.slice(0, 3).join(", ")}` : ""}, or related tasks.`;
+  return truncate(desc, 1024);
+}
+
 /** Builds third-person skill description for YAML frontmatter. */
 function skillDescription(root: CliProgram): string {
   const tools = collectMcpTools(root);
@@ -159,6 +181,54 @@ function buildReferenceMd(root: CliProgram): string {
   return generateApiGuide(root);
 }
 
+/** Builds MCP routing SKILL.md for Claude Code plugin zips. */
+function buildPluginSkillMd(root: CliProgram, dirName: string): string {
+  const name = sanitizeToolSegment(root.key);
+  const description = pluginSkillDescription(root);
+  const serverId = mcpServerId(root);
+  const schemaUri = resolveMcpSchemaUri(root);
+
+  const lines: string[] = [
+    "---",
+    `name: ${name}`,
+    `description: ${description}`,
+    "---",
+    "",
+    `# ${root.key}`,
+    "",
+    root.description,
+    "",
+    "## Execution",
+    "",
+    "This plugin bundles an MCP server. Use MCP tools to fulfill requests.",
+    "",
+    `- Server id: \`${serverId}\` (configured in plugin \`.mcp.json\`)`,
+    "- Tool names and argument shapes come from MCP `tools/list`",
+    `- Full schema: \`${schemaUri}\` (same as \`${root.key} docs schema\`)`,
+    "",
+  ];
+
+  lines.push(...buildConfigurationSection(root));
+
+  lines.push(
+    "## Claude Code plugin",
+    "",
+    `Invoke with \`/${dirName}\` or let Claude auto-match from the description.`,
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+/** Generates MCP routing SKILL.md for Claude Code plugin zips. */
+export function generatePluginSkillBundle(root: CliProgram): PluginSkillBundle {
+  const dirName = sanitizeToolSegment(root.key);
+  return {
+    dirName,
+    skillMd: buildPluginSkillMd(root, dirName),
+  };
+}
+
 /** Generates SKILL.md and reference.md for Cursor or Claude Code. */
 export function generateSkillBundle(root: CliProgram, target: SkillTarget): SkillBundle {
   const dirName = sanitizeToolSegment(root.key);

package/src/skill/hint.ts

@@ -58,3 +58,8 @@ export function applySkillBundleHints(
     referenceMd: insertGeneratedHint(referenceMd, hint),
   };
 }
+
+/** Applies bundle hint to plugin SKILL.md (after frontmatter). */
+export function applyPluginSkillHint(program: CliProgram, skillMd: string): string {
+  return insertGeneratedHint(skillMd, skillBundleHint(program), { afterFrontmatter: true });
+}

package/src/validate.ts

@@ -3,6 +3,7 @@ This module validates CLI schemas before execution.
 */
 
 import { reservedCommandNames, resolveCapabilities } from "./capabilities.ts";
+import { reservedDocsTopicResourceUris } from "./docs/mcp-resources.ts";
 import { DOCS_BUILTIN_TOPIC_KEYS } from "./docs/resolve.ts";
 import { validateFormatValue } from "./formats.ts";
 import { resolveMcpSchemaUri } from "./mcp/tools.ts";
@@ -209,11 +210,15 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
 
   if (isRoot && program.mcpServer?.enabled === true && program.mcpServer.resources) {
     const schemaUri = resolveMcpSchemaUri(program);
+    const reserved = new Set([schemaUri, ...reservedDocsTopicResourceUris(program)]);
     const uris = program.mcpServer.resources.map((r) => r.uri);
-    if (uris.includes(schemaUri)) {
-      throw new CliSchemaValidationError(
-        `mcpServer.resources URI '${schemaUri}' conflicts with the built-in schema resource`,
-      );
+    for (const uri of uris) {
+      if (reserved.has(uri)) {
+        const kind = uri === schemaUri ? "built-in schema resource" : "auto docs topic resource";
+        throw new CliSchemaValidationError(
+          `mcpServer.resources URI '${uri}' conflicts with ${kind}`,
+        );
+      }
     }
     if (new Set(uris).size !== uris.length) {
       throw new CliSchemaValidationError("mcpServer.resources URIs must be unique");