argsbarg 1.4.2 → 1.4.3

package/.private/scratch.md

@@ -1 +1,2 @@
-- [x] --schema feature for ai agents
+- [x] --schema feature for ai agents
+- [ ] auto-generate/install a cursor skill  format for ~/.cursor/skills?

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.3] - 2026-06-19
+
+### Added
+
+- **`ai` built-in group** — `myapp ai skill cursor` and `myapp ai skill claude` install Agent Skills (`SKILL.md` + `reference.md`) to project or global skill directories.
+- **`aiSkill`** root config to opt out of skill install (`{ enabled: false }`).
+
+### Changed (breaking)
+
+- **`myapp mcp`** → **`myapp ai mcp`**
+- Reserved top-level command **`mcp`** → **`ai`** (user commands may now be named `mcp`)
+
 ## [1.4.2] - 2026-06-19
 
 ### Added
@@ -123,7 +135,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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/v1.4.2...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.4.3...HEAD
+[1.4.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.3
 [1.4.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.2
 [1.4.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.1
 [1.4.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.0

package/README.md

@@ -16,7 +16,7 @@ Why another CLI parser?
 
 *Shell completions* — `completion bash` and `completion zsh` built-ins generate installable scripts from your schema so users get tab completion for commands, flags, and positionals without extra tooling.
 
-*Optional MCP server* — set `mcpServer: {}` on the program root to expose leaf commands as MCP tools and the full CLI tree as a schema resource (`myapp mcp` over stdio). See [docs/mcp.md](docs/mcp.md).
+*Optional MCP server* — set `mcpServer: {}` on the program root to expose leaf commands as MCP tools and the full CLI tree as a schema resource (`myapp ai mcp` over stdio). See [docs/mcp.md](docs/mcp.md). Install Cursor/Claude skills with `myapp ai skill cursor|claude` — see [docs/ai-skills.md](docs/ai-skills.md).
 
 *Bun-optimized* — built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
 
@@ -96,19 +96,30 @@ Every app gets:
 - `-h` / `--help` at any routing depth (scoped help).
 - **`--schema`** at the program root — print the full command tree as JSON (for tooling and agents).
 - **`completion bash` / `completion zsh`** — print shell completion scripts to stdout (injected by `cliRun`).
-- **`mcp`** — when `mcpServer: {}` is set on the program root, run an MCP server over stdio (`myapp mcp`).
+- **`ai`** — AI agent integration: `ai mcp` (when `mcpServer` is set), `ai skill cursor`, `ai skill claude` (install agent skills; opt out with `aiSkill: { enabled: false }`).
 
 Do not declare a top-level command named **`completion`** — it is reserved for this built-in.
-Do not declare a top-level command named **`mcp`** — it is reserved when MCP is enabled.
+Do not declare a top-level command named **`ai`** — it is reserved for this built-in.
 Do not declare an option named **`schema`** — it is reserved for `--schema`.
 
 
 ### MCP (AI agents)
 
-Opt in on the program root with `mcpServer: {}` (or `{ name, version, … }`), then run `myapp mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `argsbarg://schema`. Handlers can read `ctx.invocation` and use `cliInvoke` for headless testing.
+Opt in on the program root with `mcpServer: {}` (or `{ name, version, … }`), then run `myapp ai mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `argsbarg://schema`. Handlers can read `ctx.invocation` and use `cliInvoke` for headless testing.
 
 See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details.
 
+### Agent skills
+
+Install Cursor or Claude Code skills (command catalog + schema reference) with:
+
+```bash
+myapp ai skill cursor          # .cursor/skills/<name>/
+myapp ai skill claude --global # ~/.claude/skills/<name>/
+```
+
+See **[docs/ai-skills.md](docs/ai-skills.md)** for opt-out, flags, and file layout.
+
 
 ### Shell completions
 

package/docs/ai-skills.md

@@ -0,0 +1,75 @@
+# Agent skills install
+
+ArgsBarg can install [Agent Skills](https://code.claude.com/docs/en/skills) content for **Cursor** and **Claude Code** from your CLI schema. Each install writes two files:
+
+| File | Purpose |
+| --- | --- |
+| `SKILL.md` | Frontmatter + command catalog, execution notes, pitfalls |
+| `reference.md` | Full `--schema` JSON export |
+
+Skills are **install-only** — there is no print-to-stdout mode, because the artifact is always a two-file directory.
+
+## Quick start
+
+```bash
+# Project skill (commit .cursor/skills/ with your repo)
+myapp ai skill cursor
+
+# User-wide Claude Code skill
+myapp ai skill claude --global
+```
+
+On success, one line is printed to **stderr** with the install path (not the skill body).
+
+## Opt-out
+
+Skill install is **enabled by default**. Opt out on the program root:
+
+```typescript
+const cli: CliCommand = {
+  key: "myapp",
+  description: "My app.",
+  aiSkill: { enabled: false },
+  commands: [/* ... */],
+};
+```
+
+Optional custom skill directory name:
+
+```typescript
+aiSkill: { name: "my-custom-skill" },
+```
+
+## Flags
+
+Available on `ai skill cursor` and `ai skill claude`:
+
+| Flag | Effect |
+| --- | --- |
+| `--global` | Install under the user skills directory instead of the project |
+| `--force` | Overwrite an existing skill directory |
+
+## Install locations
+
+| Target | Project (default) | `--global` |
+| --- | --- | --- |
+| Cursor | `.cursor/skills/<name>/` | `~/.cursor/skills/<name>/` |
+| Claude Code | `.claude/skills/<name>/` | `~/.claude/skills/<name>/` |
+
+`<name>` defaults to the sanitized program root `key` (same rules as MCP tool name segments).
+
+Do **not** install under `~/.cursor/skills-cursor/` — that path is reserved for Cursor built-ins.
+
+## MCP vs skills
+
+| Mechanism | Purpose |
+| --- | --- |
+| **`myapp ai mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
+| **`myapp ai skill cursor\|claude`** | Static discovery and conventions for agents |
+
+Generated `SKILL.md` recommends MCP when `mcpServer` is configured, and documents shell invocation as a fallback.
+
+## Related
+
+- [MCP server](mcp.md) — `mcpServer` config and `ai mcp` protocol
+- [README built-ins](../README.md#built-ins) — reserved command `ai`

package/docs/mcp.md

@@ -22,17 +22,19 @@ const cli: CliCommand = {
 2. Run the MCP server:
 
 ```bash
-myapp mcp
+myapp ai mcp
 ```
 
 The process reads NDJSON requests from stdin and writes NDJSON responses to stdout. It stays alive until stdin closes.
 
 3. Point your MCP client at that command. See [Client setup](#client-setup).
 
+Optionally install an agent skill for discovery without MCP: see [docs/ai-skills.md](ai-skills.md).
+
 The `examples/nested.ts` demo enables MCP — try:
 
 ```bash
-bun run examples/nested.ts mcp
+bun run examples/nested.ts ai mcp
 ```
 
 ## Client setup
@@ -46,17 +48,17 @@ Add a server entry under `mcpServers` in your Cursor MCP config:
   "mcpServers": {
     "myapp": {
       "command": "bun",
-      "args": ["run", "myapp.ts", "mcp"]
+      "args": ["run", "myapp.ts", "ai", "mcp"]
     }
   }
 }
 ```
 
-Use your real binary or script path. For a compiled CLI, `command` can be the installed binary and `args` can be `["mcp"]` only.
+Use your real binary or script path. For a compiled CLI, `command` can be the installed binary and `args` can be `["ai", "mcp"]`.
 
 ### Other MCP hosts
 
-Any host that spawns a subprocess and wires stdin/stdout works the same way: the **command** is your app, and **`mcp`** is the subcommand that starts the server.
+Any host that spawns a subprocess and wires stdin/stdout works the same way: the **command** is your app, and **`ai mcp`** starts the server.
 
 ## Configuration
 
@@ -83,7 +85,7 @@ mcpServer: {
 
 ## Tools
 
-Every **user-defined leaf command** in your schema becomes one MCP tool. Built-ins (`completion`, `mcp`) are not exposed as tools.
+Every **user-defined leaf command** in your schema becomes one MCP tool. Built-ins (`completion`, `ai`) are not exposed as tools.
 
 ### Tool names
 
@@ -275,7 +277,7 @@ Requests without an `id` are treated as notifications and do not receive a respo
 ### Manual smoke test
 
 ```bash
-printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bun run examples/nested.ts mcp
+printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bun run examples/nested.ts ai mcp
 ```
 
 You should get one JSON line on stdout with `result.capabilities` and `result.serverInfo`.
@@ -284,11 +286,11 @@ You should get one JSON line on stdout with `result.capabilities` and `result.se
 
 When MCP is enabled:
 
-- Do not declare a top-level command named **`mcp`** — it is reserved for the built-in subcommand.
+- Do not declare a top-level command named **`ai`** — it is reserved for the built-in AI integration group.
 - Do not declare a top-level command named **`completion`** — reserved for shell completions.
 - Do not declare an option named **`schema`** — reserved for `--schema`.
 
-Running `myapp mcp` without `mcpServer` on the root fails with an error (exit 1).
+Running `myapp ai mcp` without `mcpServer` on the root fails with an error (exit 1).
 
 ## Design notes
 

package/index.d.ts

@@ -105,7 +105,7 @@ export interface CliPositional {
 	argMax?: number;
 }
 /**
- * Root-only. Enables `myapp mcp` and MCP stdio server metadata.
+ * Root-only. Enables `myapp ai mcp` and MCP stdio server metadata.
  */
 export interface CliMcpServerConfig {
 	/** `initialize` serverInfo.name (default: root `key`). */
@@ -165,6 +165,15 @@ export interface CliMcpToolConfig {
 	 */
 	requiresEnv?: string[];
 }
+/**
+ * Root-only. Opt out of `ai skill` install commands with `{ enabled: false }`.
+ */
+export interface CliAiSkillConfig {
+	/** When `false`, disable `ai skill *` install commands (default: enabled). */
+	enabled?: boolean;
+	/** Skill directory name (default: sanitized root `key`). */
+	name?: string;
+}
 /**
  * Base properties shared by all command nodes.
  */
@@ -177,8 +186,10 @@ export interface CliCommandBase {
 	notes?: string;
 	/** Global or command-level flags/options. */
 	options?: CliOption[];
-	/** Root-only. When set, enables the `mcp` built-in subcommand. */
+	/** Root-only. When set, enables the `ai mcp` built-in subcommand. */
 	mcpServer?: CliMcpServerConfig;
+	/** Root-only. Opt out of `ai skill` install with `{ enabled: false }`. */
+	aiSkill?: CliAiSkillConfig;
 	/** Leaf-only. Per-tool MCP exposure and metadata. */
 	mcpTool?: CliMcpToolConfig;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "type": "module",
   "scripts": {
     "//just": "echo this app uses justfile for development tasks"

package/src/ai.ts

@@ -0,0 +1,7 @@
+/*
+This module re-exports AI agent integration entry points (skill install).
+MCP stdio serving remains in mcp.ts.
+*/
+
+export { cliSkillInstall, type SkillInstallOpts } from "./skill/install.ts";
+export { generateSkillBundle, type SkillBundle, type SkillTarget } from "./skill/generate.ts";

package/src/completion.ts

@@ -597,21 +597,62 @@ export function cliPresentationRoot(root: CliCommand): CliCommand {
   } as CliCommand;
 }
 
+/** Presence options for skill install leaves (`--global`, `--force`). */
+function skillInstallOptions(): CliOption[] {
+  return [
+    {
+      name: "global",
+      description: "Install to the user skills directory (~/.cursor/skills or ~/.claude/skills).",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "force",
+      description: "Overwrite an existing skill directory.",
+      kind: CliOptionKind.Presence,
+    },
+  ];
+}
+
 /** Built-in commands shown in help and merged for routing CLIs. */
 function presentationBuiltins(root: CliCommand): CliCommand[] {
-  const cmds: CliCommand[] = [cliBuiltinCompletionGroup(root.key)];
+  return [cliBuiltinCompletionGroup(root.key), cliBuiltinAiGroup(root)];
+}
+
+/** Builds the `ai` built-in command group (MCP + skill install). */
+export function cliBuiltinAiGroup(root: CliCommand): CliCommand {
+  const aiChildren: CliCommand[] = [
+    {
+      key: "skill",
+      description: "Install agent skill files for Cursor or Claude Code.",
+      commands: [
+        {
+          key: "cursor",
+          description: "Install Cursor skill (SKILL.md + reference.md).",
+          options: skillInstallOptions(),
+          handler: () => {},
+        },
+        {
+          key: "claude",
+          description: "Install Claude Code skill (SKILL.md + reference.md).",
+          options: skillInstallOptions(),
+          handler: () => {},
+        },
+      ],
+    },
+  ];
+
   if (root.mcpServer !== undefined) {
-    cmds.push(cliBuiltinMcpCommand());
+    aiChildren.unshift({
+      key: "mcp",
+      description: "Run as an MCP server over stdio (for AI agents).",
+      handler: () => {},
+    });
   }
-  return cmds;
-}
 
-/** Builds the static `mcp` leaf command (merged when `root.mcpServer` is set). */
-export function cliBuiltinMcpCommand(): CliCommand {
   return {
-    key: "mcp",
-    description: "Run as an MCP server over stdio (for AI agents).",
-    handler: () => {},
+    key: "ai",
+    description: "AI agent integration (MCP server and skill install).",
+    commands: aiChildren,
   };
 }
 

package/src/index.test.ts

@@ -19,12 +19,14 @@ import {
 } from "./mcp/tools.ts";
 import { applyShellEnv, loadEnvFile } from "./mcp/env.ts";
 import { buildToolCallSuccess } from "./mcp/result.ts";
+import { generateSkillBundle } from "./skill/generate.ts";
+import { cliSkillInstall } from "./skill/install.ts";
 import { ParseKind, parse, postParseValidate } from "./parse.ts";
 import { cliSchemaJson } from "./schema.ts";
 import { cliValidateRoot } from "./validate.ts";
 import { expect, test } from "bun:test";
 import { $ } from "bun";
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -727,7 +729,7 @@ async function mcpRequest(
   opts?: { script?: string; env?: Record<string, string> },
 ): Promise<Map<string | number, object>> {
   const script = opts?.script ?? "examples/nested.ts";
-  const proc = Bun.spawn(["bun", "run", script, "mcp"], {
+  const proc = Bun.spawn(["bun", "run", script, "ai", "mcp"], {
     stdin: "pipe",
     stdout: "pipe",
     stderr: "pipe",
@@ -775,7 +777,7 @@ test("collectMcpTools lists user leaf commands only", () => {
   expect(names).toContain("stat_owner_lookup");
   expect(names).toContain("read");
   expect(names).not.toContain("hidden");
-  expect(names).not.toContain("mcp");
+  expect(names).not.toContain("ai");
   expect(names).not.toContain("completion");
   const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
   expect(lookup.description).toBe("stat owner lookup — Resolve owner info.");
@@ -807,19 +809,34 @@ test("mcpToolCallToArgv expands varargs positionals", () => {
   expect(argv).toEqual(["read", "a", "b"]);
 });
 
-test("reserved command name mcp is rejected", () => {
+test("reserved command name ai is rejected", () => {
   const root: CliCommand = {
     key: "app",
     description: "",
     commands: [
       {
-        key: "mcp",
+        key: "ai",
         description: "bad",
         handler: () => {},
       },
     ],
   };
-  expect(() => cliValidateRoot(root)).toThrow(/Reserved command name: mcp/);
+  expect(() => cliValidateRoot(root)).toThrow(/Reserved command name: ai/);
+});
+
+test("top-level command name mcp is allowed", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "mcp",
+        description: "user command",
+        handler: () => {},
+      },
+    ],
+  };
+  expect(() => cliValidateRoot(root)).not.toThrow();
 });
 
 test("mcpServer on non-root node is rejected", () => {
@@ -997,10 +1014,10 @@ test("MCP ping returns empty result", async () => {
   expect(res.result).toEqual({});
 });
 
-test("minimal.ts mcp without opt-in fails", async () => {
-  const { stderr, exitCode } = await $`bun run examples/minimal.ts mcp`.nothrow().quiet();
+test("minimal.ts ai mcp without opt-in fails", async () => {
+  const { stderr, exitCode } = await $`bun run examples/minimal.ts ai mcp`.nothrow().quiet();
   expect(exitCode).toBe(1);
-  expect(stderr.toString()).toContain("mcp");
+  expect(stderr.toString()).toContain("MCP is not enabled");
 });
 
 test("ctx.invocation is cli via cliRun", async () => {
@@ -1634,4 +1651,129 @@ test("mcpToolCallToArgv empty string varargs appends nothing", () => {
   const read = tools.find((t) => t.name === "read")!;
   const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: "" });
   expect(argv).toEqual(["read"]);
+});
+
+// ── AI builtins and skills ────────────────────────────────────────────────────
+
+test("aiSkill on non-root node is rejected", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "x",
+        description: "",
+        aiSkill: { enabled: false },
+        handler: () => {},
+      },
+    ],
+  };
+  expect(() => cliValidateRoot(root)).toThrow(/aiSkill is only supported on the program root/);
+});
+
+test("generateSkillBundle includes frontmatter and command catalog", () => {
+  const bundle = generateSkillBundle(nestedMcpFixture, "cursor");
+  expect(bundle.dirName).toBe("nested_ts");
+  expect(bundle.skillMd).toMatch(/^---\nname: nested_ts\n/);
+  expect(bundle.skillMd).toContain("stat owner lookup");
+  expect(bundle.skillMd).toContain("ai mcp");
+  expect(bundle.referenceMd).toContain("```json");
+  expect(() => JSON.parse(bundle.referenceMd.match(/```json\n([\s\S]*?)\n```/)![1]!)).not.toThrow();
+});
+
+test("cliSkillInstall writes project Cursor skill files", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-"));
+  const prev = process.cwd();
+  process.chdir(cwd);
+  try {
+    const msg = cliSkillInstall(nestedMcpFixture, "cursor", { force: true });
+    expect(msg).toContain(".cursor/skills/nested_ts/");
+    const skillDir = join(cwd, ".cursor", "skills", "nested_ts");
+    expect(existsSync(join(skillDir, "SKILL.md"))).toBe(true);
+    expect(existsSync(join(skillDir, "reference.md"))).toBe(true);
+    expect(readFileSync(join(skillDir, "SKILL.md"), "utf8")).toContain("stat owner lookup");
+  } finally {
+    process.chdir(prev);
+    rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test("cliSkillInstall global uses HOME skills directory", () => {
+  const home = mkdtempSync(join(tmpdir(), "argsbarg-home-"));
+  const prevHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    const msg = cliSkillInstall(nestedMcpFixture, "cursor", { global: true, force: true });
+    expect(msg).toContain(join(home, ".cursor", "skills", "nested_ts"));
+    expect(existsSync(join(home, ".cursor", "skills", "nested_ts", "SKILL.md"))).toBe(true);
+  } finally {
+    if (prevHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = prevHome;
+    }
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("cliSkillInstall fails when directory exists without force", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-dup-"));
+  const prev = process.cwd();
+  process.chdir(cwd);
+  const prevExit = process.exit;
+  let exitCode = 0;
+  process.exit = ((code?: number) => {
+    exitCode = code ?? 0;
+    throw new Error("exit");
+  }) as typeof process.exit;
+  try {
+    cliSkillInstall(nestedMcpFixture, "cursor", { force: true });
+    try {
+      cliSkillInstall(nestedMcpFixture, "cursor", {});
+    } catch {
+      // expected exit throw
+    }
+    expect(exitCode).toBe(1);
+  } finally {
+    process.exit = prevExit;
+    process.chdir(prev);
+    rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test("cliSkillInstall claude target uses .claude/skills", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-claude-"));
+  const prev = process.cwd();
+  process.chdir(cwd);
+  try {
+    const msg = cliSkillInstall(nestedMcpFixture, "claude", { force: true });
+    expect(msg).toContain(".claude/skills/nested_ts/");
+    expect(readFileSync(join(cwd, ".claude", "skills", "nested_ts", "SKILL.md"), "utf8")).toContain(
+      "Claude Code",
+    );
+  } finally {
+    process.chdir(prev);
+    rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test("ai skill cursor fails when aiSkill disabled", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "argsbarg-skill-off-"));
+  const script = join(dir, "skill-off.ts");
+  writeFileSync(
+    script,
+    `import { cliRun, CliCommand } from ${JSON.stringify(join(import.meta.dir, "index.ts"))};
+const cli: CliCommand = {
+  key: "offapp",
+  description: "demo",
+  aiSkill: { enabled: false },
+  commands: [{ key: "x", description: "x", handler: () => {} }],
+};
+await cliRun(cli);
+`,
+    "utf8",
+  );
+  const { stderr, exitCode } = await $`bun run ${script} ai skill cursor`.nothrow().quiet();
+  expect(exitCode).toBe(1);
+  expect(stderr.toString()).toContain("AI skills are disabled");
 });

package/src/mcp/tools.ts

@@ -150,7 +150,7 @@ export function collectMcpTools(root: CliCommand): McpToolDef[] {
   /** Walks the command tree and appends leaf tools. */
   function walk(cmd: CliCommand, path: string[]): void {
     if ("handler" in cmd && cmd.handler) {
-      if (cmd.key === "completion" || cmd.key === "mcp") {
+      if (cmd.key === "completion" || cmd.key === "ai") {
         return;
       }
       if (cmd.mcpTool?.enabled === false) {

package/src/runtime.ts

@@ -7,9 +7,10 @@ It keeps execution flow out of the public barrel so the exported API stays small
 the runtime responsibilities remain easy to reason about.
 */
 
-import { cliBuiltinCompletionGroup, cliBuiltinMcpCommand, cliPresentationRoot, completionBashScript, completionZshScript } from "./completion.ts";
+import { cliBuiltinAiGroup, cliBuiltinCompletionGroup, cliPresentationRoot, completionBashScript, completionZshScript } from "./completion.ts";
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
+import { cliSkillInstall } from "./skill/install.ts";
 import { cliMcpServeStdio } from "./mcp.ts";
 import { parse, postParseValidate, ParseKind } from "./parse.ts";
 import { cliSchemaJson } from "./schema.ts";
@@ -44,29 +45,27 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     process.exit(1);
   }
 
-  let parseRoot = root;
-  let isLeafCompletionIntercept = false;
-
-  if (root.handler && argv.length >= 1 && argv[0] === "mcp" && !root.mcpServer) {
-    process.stderr.write("Unknown command: mcp\n");
+  if (argv.length >= 2 && argv[0] === "ai" && argv[1] === "mcp" && !root.mcpServer) {
+    process.stderr.write("MCP is not enabled. Set mcpServer on the program root.\n");
     process.exit(1);
   }
 
-  // Intercept completion for Leaf roots (since they can't natively have a completion subcommand)
-  // but wrap them in a dummy router so that the parser handles `-h` and errors correctly.
-  if (root.handler && argv.length >= 1 && argv[0] === "completion") {
-    isLeafCompletionIntercept = true;
+  let parseRoot = root;
+  let isLeafCompletionIntercept = false;
+
+  if (root.handler && argv.length >= 1 && argv[0] === "ai") {
     parseRoot = {
       key: root.key,
       description: root.description,
-      commands: [cliBuiltinCompletionGroup(root.key)],
-    } as any;
-  } else if (root.handler && argv.length >= 1 && argv[0] === "mcp" && root.mcpServer) {
+      commands: [cliBuiltinAiGroup(root)],
+    } as CliCommand;
+  } else if (root.handler && argv.length >= 1 && argv[0] === "completion") {
+    isLeafCompletionIntercept = true;
     parseRoot = {
       key: root.key,
       description: root.description,
-      commands: [cliBuiltinMcpCommand()],
-    } as CliCommand;
+      commands: [cliBuiltinCompletionGroup(root.key)],
+    } as any;
   } else {
     parseRoot = cliRootMergedWithBuiltins(root);
   }
@@ -109,16 +108,36 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     }
   }
 
-  if (pr.path[0] === "mcp") {
-    if (!root.mcpServer) {
-      process.stderr.write("Internal error: mcp not enabled.\n");
-      process.exit(1);
-    }
-    if (pr.path.length !== 1) {
-      process.stderr.write("Unknown subcommand: mcp " + pr.path.slice(1).join(" ") + "\n");
+  if (pr.path[0] === "ai") {
+    if (pr.path[1] === "mcp") {
+      if (!root.mcpServer) {
+        process.stderr.write("MCP is not enabled. Set mcpServer on the program root.\n");
+        process.exit(1);
+      }
+      if (pr.path.length !== 2) {
+        process.stderr.write("Unknown subcommand: ai " + pr.path.slice(1).join(" ") + "\n");
+        process.exit(1);
+      }
+      await cliMcpServeStdio(root);
+    } else if (pr.path[1] === "skill" && (pr.path[2] === "cursor" || pr.path[2] === "claude")) {
+      if (root.aiSkill?.enabled === false) {
+        process.stderr.write("AI skills are disabled. Remove aiSkill.enabled: false from the program root.\n");
+        process.exit(1);
+      }
+      if (pr.path.length !== 3) {
+        process.stderr.write("Unknown subcommand: ai " + pr.path.slice(1).join(" ") + "\n");
+        process.exit(1);
+      }
+      const msg = cliSkillInstall(root, pr.path[2], {
+        global: pr.opts.global === "1",
+        force: pr.opts.force === "1",
+      });
+      process.stderr.write(msg + "\n");
+      process.exit(0);
+    } else {
+      process.stderr.write("Unknown subcommand: ai " + pr.path.slice(1).join(" ") + "\n");
       process.exit(1);
     }
-    await cliMcpServeStdio(root);
   }
 
   let current = parseRoot;

package/src/skill/generate.ts

@@ -0,0 +1,183 @@
+/*
+This module generates Agent Skills content (SKILL.md + reference.md) from a CLI schema.
+*/
+
+import { collectOptionDefs } from "../parse.ts";
+import { cliSchemaJson } from "../schema.ts";
+import { collectMcpTools, sanitizeToolSegment } from "../mcp/tools.ts";
+import { CliCommand, CliOptionKind } from "../types.ts";
+
+export type SkillTarget = "cursor" | "claude";
+
+export interface SkillBundle {
+  dirName: string;
+  skillMd: string;
+  referenceMd: 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 third-person skill description for YAML frontmatter. */
+function skillDescription(root: CliCommand): 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 = `Operates the ${root.key} CLI (${sample}${more}). Use when the user mentions ${root.key}${paths.length > 0 ? `, ${paths.slice(0, 3).join(", ")}` : ""}, or related tasks.`;
+  return truncate(desc, 1024);
+}
+
+/** Formats one command line for the catalog section. */
+function formatCommandEntry(root: CliCommand, tool: ReturnType<typeof collectMcpTools>[number]): string {
+  const cliPath = tool.path.length > 0 ? `${root.key} ${tool.path.join(" ")}` : root.key;
+  let line = `- **\`${cliPath}\`** — ${tool.description}`;
+  const opts = collectOptionDefs(root, tool.path);
+  const flags = opts.filter((o) => o.kind === CliOptionKind.Presence).map((o) => `--${o.name}`);
+  if (flags.length > 0) {
+    line += ` (flags: ${flags.join(", ")})`;
+  }
+  const enums = opts.filter((o) => o.kind === CliOptionKind.Enum && o.choices?.length);
+  for (const e of enums) {
+    line += ` (\`--${e.name}\`: ${e.choices!.join(" | ")})`;
+  }
+  const varargs = (tool.leaf.positionals ?? []).filter((p) => (p.argMax ?? 1) === 0);
+  if (varargs.length > 0) {
+    line += ` (varargs: ${varargs.map((p) => p.name).join(", ")})`;
+  }
+  return line;
+}
+
+/** Builds SKILL.md body for the given target. */
+function buildSkillMd(root: CliCommand, target: SkillTarget, dirName: string): string {
+  const name = root.aiSkill?.name ?? sanitizeToolSegment(root.key);
+  const description = skillDescription(root);
+  const tools = collectMcpTools(root);
+
+  const lines: string[] = [
+    "---",
+    `name: ${name}`,
+    `description: ${description}`,
+    "---",
+    "",
+    `# ${root.key}`,
+    "",
+    root.description,
+    "",
+    "## When to use",
+    "",
+    `Use this skill when working with **${root.key}** — shell commands, automation, or agent tool calls for this application.`,
+    "",
+    "## Execution",
+    "",
+  ];
+
+  if (root.mcpServer !== undefined) {
+    lines.push(
+      "**Prefer MCP** when a host has the server connected:",
+      "",
+      "```bash",
+      `${root.key} ai mcp`,
+      "```",
+      "",
+      "Example Cursor `mcp.json` entry:",
+      "",
+      "```json",
+      JSON.stringify(
+        {
+          mcpServers: {
+            [root.mcpServer.name ?? root.key]: {
+              command: root.key,
+              args: ["ai", "mcp"],
+            },
+          },
+        },
+        null,
+        2,
+      ),
+      "```",
+      "",
+      "When MCP tools are available, use `tools/call` with flat JSON arguments. Read the schema resource for full shapes.",
+      "",
+      "Otherwise invoke via shell:",
+      "",
+    );
+  } else {
+    lines.push("Invoke via shell:", "");
+  }
+
+  lines.push("```bash", `${root.key} <subcommand> [options] [args]`, "```", "", "## Commands", "");
+
+  if (tools.length === 0) {
+    lines.push("(No leaf commands in schema.)", "");
+  } else {
+    for (const tool of tools) {
+      lines.push(formatCommandEntry(root, tool));
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "## Pitfalls",
+    "",
+    "- Use `--` before tokens that look like flags when they are positional arguments.",
+    "- Under MCP (`ctx.invocation === \"mcp\"`), child processes must not inherit stdout — use piped stdout.",
+    "- Required environment variables are listed per command in descriptions (`requires env`).",
+    "",
+    "## Reference",
+    "",
+    "See `reference.md` in this skill directory for the full `--schema` JSON export.",
+    "",
+  );
+
+  if (target === "cursor") {
+    lines.push(
+      "## Cursor install location",
+      "",
+      `- Project: \`.cursor/skills/${dirName}/\``,
+      `- Global: \`~/.cursor/skills/${dirName}/\``,
+      "",
+      "Do not install under `~/.cursor/skills-cursor/` (reserved for Cursor built-ins).",
+      "",
+    );
+  } else {
+    lines.push(
+      "## Claude Code",
+      "",
+      `- Invoke with \`/${dirName}\` or let Claude auto-match from the description.`,
+      `- Project skills: \`.claude/skills/${dirName}/\``,
+      `- Global skills: \`~/.claude/skills/${dirName}/\``,
+      `- Bundled files in this directory are available via \`\${CLAUDE_SKILL_DIR}\` when the skill runs.`,
+      "",
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/** Builds reference.md with pretty-printed schema JSON. */
+function buildReferenceMd(root: CliCommand): string {
+  return [
+    `# ${root.key} — CLI reference`,
+    "",
+    "Generated from the program `--schema` export. Handlers and runtime-only nodes are omitted.",
+    "",
+    "```json",
+    cliSchemaJson(root).trimEnd(),
+    "```",
+    "",
+  ].join("\n");
+}
+
+/** Generates SKILL.md and reference.md for Cursor or Claude Code. */
+export function generateSkillBundle(root: CliCommand, target: SkillTarget): SkillBundle {
+  const dirName = root.aiSkill?.name ?? sanitizeToolSegment(root.key);
+  return {
+    dirName,
+    skillMd: buildSkillMd(root, target, dirName),
+    referenceMd: buildReferenceMd(root),
+  };
+}

package/src/skill/install.ts

@@ -0,0 +1,45 @@
+/*
+This module installs generated Agent Skills to Cursor or Claude Code skill directories.
+*/
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CliCommand } from "../types.ts";
+import { generateSkillBundle, type SkillTarget } from "./generate.ts";
+
+export interface SkillInstallOpts {
+  global?: boolean;
+  force?: boolean;
+}
+
+/** Resolves the user home directory (`$HOME` when set). */
+function userHome(): string {
+  return process.env.HOME ?? homedir();
+}
+
+/** Resolves the install directory for a skill target. */
+function resolveSkillDir(target: SkillTarget, dirName: string, global: boolean): string {
+  const base = global
+    ? join(userHome(), target === "cursor" ? ".cursor" : ".claude", "skills")
+    : join(process.cwd(), target === "cursor" ? ".cursor" : ".claude", "skills");
+  return join(base, dirName);
+}
+
+/** Writes SKILL.md and reference.md to the target skills directory. */
+export function cliSkillInstall(root: CliCommand, target: SkillTarget, opts: SkillInstallOpts): string {
+  const bundle = generateSkillBundle(root, target);
+  const dir = resolveSkillDir(target, bundle.dirName, opts.global ?? false);
+
+  if (existsSync(dir) && !opts.force) {
+    process.stderr.write(`Skill directory already exists: ${dir}\nUse --force to overwrite.\n`);
+    process.exit(1);
+  }
+
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "SKILL.md"), bundle.skillMd, "utf8");
+  writeFileSync(join(dir, "reference.md"), bundle.referenceMd, "utf8");
+
+  const label = target === "cursor" ? "Cursor" : "Claude Code";
+  return `Installed ${label} skill to ${dir}/`;
+}

package/src/types.ts

@@ -90,7 +90,7 @@ export interface CliPositional {
 }
 
 /**
- * Root-only. Enables `myapp mcp` and MCP stdio server metadata.
+ * Root-only. Enables `myapp ai mcp` and MCP stdio server metadata.
  */
 export interface CliMcpServerConfig {
   /** `initialize` serverInfo.name (default: root `key`). */
@@ -153,6 +153,16 @@ export interface CliMcpToolConfig {
   requiresEnv?: string[];
 }
 
+/**
+ * Root-only. Opt out of `ai skill` install commands with `{ enabled: false }`.
+ */
+export interface CliAiSkillConfig {
+  /** When `false`, disable `ai skill *` install commands (default: enabled). */
+  enabled?: boolean;
+  /** Skill directory name (default: sanitized root `key`). */
+  name?: string;
+}
+
 /**
  * Base properties shared by all command nodes.
  */
@@ -165,8 +175,10 @@ export interface CliCommandBase {
   notes?: string;
   /** Global or command-level flags/options. */
   options?: CliOption[];
-  /** Root-only. When set, enables the `mcp` built-in subcommand. */
+  /** Root-only. When set, enables the `ai mcp` built-in subcommand. */
   mcpServer?: CliMcpServerConfig;
+  /** Root-only. Opt out of `ai skill` install with `{ enabled: false }`. */
+  aiSkill?: CliAiSkillConfig;
   /** Leaf-only. Per-tool MCP exposure and metadata. */
   mcpTool?: CliMcpToolConfig;
 }

package/src/validate.ts

@@ -14,7 +14,7 @@ import {
 } from "./types.ts";
 import { MCP_SCHEMA_URI_DEFAULT } from "./mcp/tools.ts";
 
-const reservedCommandNames = ["completion", "mcp"];
+const reservedCommandNames = ["completion", "ai"];
 
 /**
  * Validates the static CliCommand tree against ArgBarg rules.
@@ -41,6 +41,12 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     );
   }
 
+  if (!isRoot && cmd.aiSkill !== undefined) {
+    throw new CliSchemaValidationError(
+      "aiSkill is only supported on the program root (not on " + cmd.key + ")",
+    );
+  }
+
   const isLeaf = "handler" in cmd && !!cmd.handler;
   if (!isLeaf && cmd.mcpTool !== undefined) {
     throw new CliSchemaValidationError(