argsbarg 3.3.11 → 3.3.13

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.13] - 2026-06-21
+
+### Changed
+
+- **Agent skills** — `SKILL.md` is a compact command index; `reference.md` holds the full `docs api` guide. `docs skill` notes recommend `install --skill` for the optimized persisted bundle.
+
+## [3.3.12] - 2026-06-21
+
+### Changed
+
+- **Agent skills** — `SKILL.md` embeds the `docs api` command reference (body only) instead of a separate `## Commands` bullet catalog.
+
 ## [3.3.11] - 2026-06-21
 
 ### Added
@@ -317,7 +329,9 @@ 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/v3.3.11...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.3.13...HEAD
+[3.3.13]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.13
+[3.3.12]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.12
 [3.3.11]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.11
 [3.3.10]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.10
 [3.3.9]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.9

package/docs/ai-skills.md

@@ -31,8 +31,8 @@ For library use, call `cliSkillInstall(root, "cursor" | "claude", { global: true
 
 ## Generated content
 
-- **`SKILL.md`** — YAML frontmatter, when-to-use guidance, shell command catalog, pitfalls
-- **`reference.md`** — full `docs schema` JSON export
+- **`SKILL.md`** — YAML frontmatter, compact command index, pitfalls, and a pointer to `reference.md`
+- **`reference.md`** — full `docs api` markdown reference
 
 Installed files include an HTML comment hint (`Generated by myapp install --skill; do not edit.`) after SKILL.md frontmatter and at the top of `reference.md`.
 
@@ -43,10 +43,10 @@ Skills describe **shell invocation only** — no MCP setup, `mcp.json`, or `tool
 | Mechanism | Role |
 | --- | --- |
 | **`myapp mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
-| **`myapp install --skill`** | Static shell command catalog for agents |
+| **`myapp install --skill`** | Persists optimized skill bundle (`SKILL.md` index + `reference.md` full API) |
 | **`myapp docs`** (requires `docs`) | Bundled markdown on stdout (`docs mcp` when MCP enabled) |
 
-Command catalog lines reuse MCP tool descriptions. See [cli-program.md](cli-program.md).
+`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).
 
 See also:
 

package/docs/bundled-docs.md

@@ -68,7 +68,7 @@ When `docs.enabled` is `true`:
 
 - **`docs schema`** — same JSON as the former root `--schema` flag (handlers omitted; built-in subtrees included for leaf roots).
 - **`docs api`** — markdown rendering of the same command tree (options, positionals, subcommands, fallback routing).
-- **`docs skill`** — prints generated Cursor `SKILL.md` content (same prose as `install --skill`, without writing files).
+- **`docs skill`** — prints the compact `SKILL.md` index. Prefer `install --skill --yes` for agents (persists index + full API in `reference.md`).
 
 ## MCP guide (`docs mcp`)
 
@@ -84,7 +84,7 @@ All `docs` subcommands are hidden from MCP `tools/list` (`mcpTool: { enabled: fa
 
 | Channel | Role |
 | --- | --- |
-| `install --skill` | Writes shell command catalog + `reference.md` to disk |
+| `install --skill` | Writes compact `SKILL.md` + full-API `reference.md` to disk |
 | `docs skill` | Print generated `SKILL.md` to stdout |
 | `docs api` | Print command tree markdown to stdout |
 | `docs schema` | Print command tree JSON to stdout |

package/package.json

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

package/src/docs/api-guide.test.ts

@@ -1,7 +1,7 @@
 import { expect, test } from "bun:test";
 import type { CliProgram } from "../types.ts";
 import { CliOptionKind } from "../types.ts";
-import { generateApiGuide } from "./api-guide.ts";
+import { generateApiGuide, generateApiGuideBody } from "./api-guide.ts";
 import { cliSchemaExport } from "../schema.ts";
 
 const nestedFixture: CliProgram = {
@@ -45,6 +45,14 @@ const nestedFixture: CliProgram = {
   ],
 };
 
+test("generateApiGuideBody matches command section of full API guide", () => {
+  const body = generateApiGuideBody(nestedFixture);
+  const full = generateApiGuide(nestedFixture);
+  expect(full).toContain(body.trimEnd());
+  expect(body).toContain("## `nested.ts stat`");
+  expect(body).not.toContain("CLI API reference");
+});
+
 test("generateApiGuide covers the same command keys as cliSchemaExport", () => {
   const md = generateApiGuide(nestedFixture);
   const schema = cliSchemaExport(nestedFixture);

package/src/docs/api-guide.ts

@@ -117,6 +117,14 @@ function renderCommandNode(
   }
 }
 
+/** Command-tree markdown shared by `docs api` and generated agent skills (no API doc header). */
+export function generateApiGuideBody(program: CliProgram): string {
+  const schema = cliSchemaExport(program);
+  const lines: string[] = [];
+  renderCommandNode(program.key, [], schema, lines);
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
 /** Generates markdown API reference from the same export as `docs schema`. */
 export function generateApiGuide(program: CliProgram): string {
   const schema = cliSchemaExport(program);
@@ -133,6 +141,6 @@ export function generateApiGuide(program: CliProgram): string {
     lines.push(formatNotesBlockquote(schema.notes, program.key), "");
   }
 
-  renderCommandNode(program.key, [], schema, lines);
+  lines.push(generateApiGuideBody(program).trimEnd(), "");
   return `${lines.join("\n").trimEnd()}\n`;
 }

package/src/docs/builtin.ts

@@ -55,7 +55,20 @@ export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
   leaves.push(
     docsLeaf(program, "schema", "Print the full command tree as JSON."),
     docsLeaf(program, "api", "Print the command tree as markdown."),
-    docsLeaf(program, "skill", "Print generated Cursor SKILL.md content."),
+    {
+      key: "skill",
+      description: "Print generated SKILL.md (compact command index).",
+      notes: [
+        "Prefer `{argsbarg:program} install --skill --yes` for agents: it persists an optimized skill bundle",
+        "(`SKILL.md` index + `reference.md` full API) to your skill directory.",
+        "`docs skill` prints the index only; use `docs api` or installed `reference.md` for full detail.",
+      ].join(" "),
+      options: [DOCS_SAVE_OPTION],
+      mcpTool: { enabled: false },
+      handler: (ctx) => {
+        runDocsTopic(program, "skill", ctx);
+      },
+    },
   );
 
   return {

package/src/docs/docs.test.ts

@@ -153,9 +153,23 @@ test("docs skill prints Cursor SKILL.md", async () => {
   expect(result.stdout).toContain("---");
   expect(result.stdout).toContain("name: myapp");
   expect(result.stdout).toContain("## Commands");
+  expect(result.stdout).toContain("read `reference.md`");
+  expect(result.stdout).not.toContain("#### Options");
   expect(result.stdout).not.toContain("mcp.json");
 });
 
+test("docs skill help recommends install --skill", async () => {
+  const presentation = cliPresentationRoot(docsFixture());
+  const docsNode = presentation.commands.find((c) => c.key === "docs");
+  expect(docsNode && "commands" in docsNode).toBe(true);
+  if (docsNode && "commands" in docsNode) {
+    const skill = docsNode.commands.find((c) => c.key === "skill");
+    expect(skill?.description).toContain("compact command index");
+    expect(skill?.notes).toContain("install --skill --yes");
+    expect(skill?.notes).toContain("reference.md");
+  }
+});
+
 test("presentation includes docs schema and skill", () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");

package/src/index.test.ts

@@ -1808,19 +1808,24 @@ test("install config on non-root node is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/install is only supported on the program root/);
 });
 
-test("generateSkillBundle includes frontmatter and command catalog", () => {
+test("generateSkillBundle includes frontmatter and compact command index", () => {
   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("## Commands");
+  expect(bundle.skillMd).toContain("`nested.ts stat owner lookup <path>`");
   expect(bundle.skillMd).toContain("Invoke via shell:");
+  expect(bundle.skillMd).toContain("read `reference.md`");
+  expect(bundle.skillMd).not.toContain("#### Options");
+  expect(bundle.skillMd).not.toContain("CLI API reference");
   expect(bundle.skillMd).not.toContain("mcp.json");
   expect(bundle.skillMd).not.toContain("Prefer MCP");
   expect(bundle.skillMd).not.toContain("tools/call");
   expect(bundle.skillMd).not.toContain("Generated by");
-  expect(bundle.referenceMd).toContain("```json");
+  expect(bundle.referenceMd).toContain("CLI API reference");
+  expect(bundle.referenceMd).toContain("#### Options");
   expect(bundle.referenceMd).not.toContain("Generated by");
-  expect(() => JSON.parse(bundle.referenceMd.match(/```json\n([\s\S]*?)\n```/)![1]!)).not.toThrow();
+  expect(bundle.referenceMd).not.toContain("```json");
 });
 
 test("cliSkillInstall writes project Cursor skill files", () => {
@@ -1833,7 +1838,8 @@ test("cliSkillInstall writes project Cursor skill files", () => {
     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");
+    expect(readFileSync(join(skillDir, "SKILL.md"), "utf8")).toContain("## Commands");
+    expect(readFileSync(join(skillDir, "reference.md"), "utf8")).toContain("CLI API reference");
     const skillText = readFileSync(join(skillDir, "SKILL.md"), "utf8");
     expect(skillText.startsWith("---\n")).toBe(true);
     const hint = "<!-- Generated by nested.ts install --skill; do not edit. -->";

package/src/skill/generate.ts

@@ -2,9 +2,9 @@
 This module generates Agent Skills content (SKILL.md + reference.md) from a CLI schema.
 */
 
+import { generateApiGuide } from "../docs/api-guide.ts";
 import { collectOptionDefs } from "../parse.ts";
-import { cliSchemaJson } from "../schema.ts";
-import { collectMcpTools, sanitizeToolSegment } from "../mcp/tools.ts";
+import { collectMcpTools, sanitizeToolSegment, type McpToolDef } from "../mcp/tools.ts";
 import { CliProgram, CliOptionKind } from "../types.ts";
 
 export type SkillTarget = "cursor" | "claude";
@@ -31,10 +31,22 @@ function skillDescription(root: CliProgram): string {
   return truncate(desc, 1024);
 }
 
-/** Formats one command line for the catalog section. */
-function formatCommandEntry(root: CliProgram, tool: ReturnType<typeof collectMcpTools>[number]): string {
-  const cliPath = tool.path.length > 0 ? `${root.key} ${tool.path.join(" ")}` : root.key;
-  let line = `- **\`${cliPath}\`** — ${tool.description}`;
+/** CLI path with required single-slot positionals for the compact catalog. */
+function commandCatalogPath(root: CliProgram, tool: McpToolDef): string {
+  const base = tool.path.length > 0 ? `${root.key} ${tool.path.join(" ")}` : root.key;
+  const slots = (tool.leaf.positionals ?? [])
+    .filter((p) => (p.argMin ?? 1) > 0 && (p.argMax ?? 1) === 1)
+    .map((p) => `<${p.name}>`);
+  if (slots.length === 0) {
+    return base;
+  }
+  return `${base} ${slots.join(" ")}`;
+}
+
+/** Formats one command line for the SKILL.md index (details live in reference.md). */
+function formatCommandEntry(root: CliProgram, tool: McpToolDef): string {
+  const cliPath = commandCatalogPath(root, tool);
+  let line = `- **\`${cliPath}\`** — ${tool.leaf.description}`;
   const opts = collectOptionDefs(root, tool.path);
   const flags = opts.filter((o) => o.kind === CliOptionKind.Presence).map((o) => `--${o.name}`);
   if (flags.length > 0) {
@@ -48,6 +60,10 @@ function formatCommandEntry(root: CliProgram, tool: ReturnType<typeof collectMcp
   if (varargs.length > 0) {
     line += ` (varargs: ${varargs.map((p) => p.name).join(", ")})`;
   }
+  const env = tool.leaf.mcpTool?.requiresEnv;
+  if (env && env.length > 0) {
+    line += ` [requires env: ${env.join(", ")}]`;
+  }
   return line;
 }
 
@@ -67,18 +83,18 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     "",
     root.description,
     "",
-    "## When to use",
-    "",
-    `Use this skill when working with **${root.key}** — shell commands and automation for this application.`,
-    "",
     "## Execution",
     "",
     "Invoke via shell:",
     "",
+    "```bash",
+    `${root.key} <subcommand> [options] [args]`,
+    "```",
+    "",
+    "## Commands",
+    "",
   ];
 
-  lines.push("```bash", `${root.key} <subcommand> [options] [args]`, "```", "", "## Commands", "");
-
   if (tools.length === 0) {
     lines.push("(No leaf commands in schema.)", "");
   } else {
@@ -92,11 +108,13 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     "## Pitfalls",
     "",
     "- Use `--` before tokens that look like flags when they are positional arguments.",
-    "- Required environment variables are listed per command in descriptions (`requires env`).",
+    "- Required environment variables are listed per command above (`requires env`) and in `reference.md`.",
     "",
     "## Reference",
     "",
-    "See `reference.md` in this skill directory for the full `docs schema` JSON export.",
+    "This file is a command index. For full option tables, positionals, notes, and built-ins,",
+    `read \`reference.md\` in this skill directory (same content as \`${root.key} docs api\`).`,
+    "Search for the command path you need before invoking.",
     "",
   );
 
@@ -125,18 +143,9 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
   return lines.join("\n");
 }
 
-/** Builds reference.md with pretty-printed schema JSON. */
+/** Builds reference.md with the full `docs api` markdown guide. */
 function buildReferenceMd(root: CliProgram): string {
-  return [
-    `# ${root.key} — CLI reference`,
-    "",
-    "Generated from the program `docs schema` export. Handlers and runtime-only nodes are omitted.",
-    "",
-    "```json",
-    cliSchemaJson(root).trimEnd(),
-    "```",
-    "",
-  ].join("\n");
+  return generateApiGuide(root);
 }
 
 /** Generates SKILL.md and reference.md for Cursor or Claude Code. */