argsbarg 7.0.4 → 7.0.6

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [7.0.6] - 2026-09-15
+
+### Changed
+
+- **Repository skill convention (`skills/<app>/SKILL.md`)** — `docs skill --save` now writes to `./skills/<app>/SKILL.md` instead of `./docs/skill.md`, aligning with the open skill repository standard. Automatically removes legacy `./docs/skill.md` when saving. Updated `argsbarg create` to scaffold `skills/<app>/SKILL.md`.
+- **Intent-based agent skill router** — `skill.md` / `SKILL.md` is now an intent-based router directing agents to specific subcommands and guiding them to use `<subcommand> --help` for JIT option and positional discovery. Dropped `reference.md` generation and install, preventing agent context window bloat and outdated flag hallucinations. `cliSkillInstall` automatically cleans up legacy `reference.md` when refreshing.
+- **Consumer agent instructions** — updated `AGENTS.md` managed template to instruct coding agents to use `<cli> <subcommand> --help` instead of reading large API markdown documentation files.
+
+## [7.0.5] - 2026-09-15
+
+### Added
+
+- **Interleaved options between positionals** — options (presence flags and value options) can now be placed anywhere between bounded or optional positional arguments (e.g. `cmd file1 --force file2`), matching varargs tail behavior rather than requiring all options to precede or follow all bounded positionals.
+
 ## [7.0.4] - 2026-08-17
 
 ### Changed
@@ -959,7 +973,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/v7.0.4...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.0.6...HEAD
+[7.0.6]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.6
+[7.0.5]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.5
 [7.0.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.4
 [7.0.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.3
 [7.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.2

package/README.md

@@ -385,7 +385,7 @@ This refreshes the argsbarg-managed section in `AGENTS.md` while preserving your
 
 ### 3. Generated Skills & Workspace Configuration
 
-Running `myapp configure install` installs a compact `SKILL.md` index and full-reference `reference.md` to `~/.agents/skills/<key>/` when `program.skill: { enabled: true }`.
+Running `myapp configure install` installs an intent-based `SKILL.md` router to `~/.agents/skills/<key>/` when `program.skill: { enabled: true }`, directing agents to run `<subcommand> --help` for just-in-time option and argument discovery.
 
 See **[docs/configure.md](docs/configure.md)** and **[docs/ai-skills.md](docs/ai-skills.md)** for developer setup and automated Homebrew pipeline integration.
 

package/docs/ai-skills.md

@@ -2,7 +2,7 @@
 
 > This feature is experimental.
 
-ArgsBarg can generate agent skill directories (`skill.md` + `reference.md`) from your CLI schema and install them to `~/.agents/skills/<key>/` per the open standard at https://dotagentsprotocol.com/.
+ArgsBarg can generate agent skill directories (`skill.md` + `SKILL.md`) from your CLI schema and install them to `~/.agents/skills/<key>/` per the open standard at https://dotagentsprotocol.com/.
 
 ## Enable on the program root
 
@@ -36,11 +36,10 @@ import { cliSkillInstall } from "argsbarg/skill/install"; // internal module
 
 ## Generated content
 
-- **`skill.md`** — https://dotagentsprotocol.com frontmatter (`id`, `name`, `description`, `enabled`), compact command index, pitfalls, client setup, and a pointer to `reference.md`
+- **`skill.md`** — https://dotagentsprotocol.com frontmatter (`id`, `name`, `description`, `enabled`), execution guidance, options & help discovery protocol (`--help`), compact command router, workflow & pitfalls, and client setup
 - **`SKILL.md`** — compatibility copy of `skill.md` for tools that expect uppercase filenames
-- **`reference.md`** — full `docs cli` markdown reference
 
-Installed files include an HTML comment hint (`Generated by myapp configure; do not edit.`) after skill frontmatter and at the top of `reference.md`.
+Installed files include an HTML comment hint (`Generated by myapp configure; do not edit.`) after skill frontmatter.
 
 ## Client setup
 
@@ -61,10 +60,14 @@ Skills describe **shell invocation only** — no MCP setup or `tools/call` guida
 | Mechanism | Role |
 | --- | --- |
 | **`myapp mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
-| **`program.skill.enabled`** + **`configure install`** | Persists optimized skill bundle at `~/.agents/skills/<key>/` |
+| **`program.skill.enabled`** + **`configure install`** | Persists optimized intent-based skill router at `~/.agents/skills/<key>/` |
 | **`myapp docs`** (requires `docs`) | Bundled markdown on stdout (`docs mcp` when MCP enabled) |
 
-`skill.md` is the routing index; `reference.md` matches `docs cli`. Prefer `configure install` over `docs skill` for installed agents. See [cli-program.md](cli-program.md).
+`skill.md` is an intent-based router that directs agents to specific subcommands and guides them to use `<subcommand> --help` for JIT option discovery. Prefer `configure install` over `docs skill` for installed agents. See [cli-program.md](cli-program.md).
+
+## Repository skill (`skills/<app>/SKILL.md`)
+
+Running `myapp docs skill --save` writes `skills/<app>/SKILL.md` directly into the consumer repository. Committing this file adheres to the repository skill convention (`skills/<name>/SKILL.md`), allowing agents, tools, and skill managers to discover and install your CLI's skill directly from the source repository.
 
 **Claude Code plugin** (`mcpServer.claudePlugin: true` → `mcp bundle` writes `dist/claude-plugin/<name>.zip`) ships a separate MCP pointer skill (`SKILL.md` only) that routes agents to the bundled MCP server. This is a **dist artifact**, not installed via `configure`.
 

package/docs/bundled-docs.md

@@ -63,6 +63,7 @@ myapp docs openapi      # OpenAPI 3.1 JSON when httpServer.enabled
 myapp docs readme --save   # write ./docs/readme.md
 myapp docs cli-schema --save   # write ./docs/cli-schema.json
 myapp docs openapi --save  # write ./docs/openapi.json
+myapp docs skill --save    # write ./skills/myapp/SKILL.md
 ```
 
 Top-level `myapp --help` points agents at `myapp docs skill`. The `docs skill` subcommand description recommends `configure` for a persisted bundle.
@@ -97,7 +98,7 @@ By default (unless `docs.enabled: false`):
 
 - **`docs cli-schema`** — same JSON as the former root `--schema` flag (handlers omitted; built-in subtrees included for leaf roots).
 - **`docs cli`** — markdown rendering of the same command tree (options, positionals, subcommands, fallback routing).
-- **`docs skill`** — prints the compact `SKILL.md` index. Prefer `configure install` for agents (persists index + full API in `reference.md`).
+- **`docs skill`** — prints the compact `SKILL.md` router. Prefer `configure install` for agents (persists `skill.md` + `SKILL.md` to `~/.agents/skills/<key>/`).
 
 ## MCP guide (`docs mcp`)
 
@@ -123,7 +124,7 @@ All `docs` subcommands are hidden from MCP `tools/list` (`mcpTool: { enabled: fa
 
 | Channel | Role |
 | --- | --- |
-| `configure` (skill targets) | Writes compact `SKILL.md` + full-API `reference.md` to disk |
+| `configure` (skill targets) | Writes intent-based `skill.md` + `SKILL.md` router to disk |
 | `docs skill` | Print generated `SKILL.md` to stdout |
 | `docs cli` | Print command tree markdown to stdout |
 | `docs cli-schema` | Print command tree JSON to stdout |
@@ -135,21 +136,20 @@ Do not declare a top-level command named **`docs`** unless `docs.enabled: false`
 
 ## Agent artifact contract
 
-Load one primary artifact per task — avoid pulling `reference.md`, `cli-schema.json`, and `openapi.json` together unless you need all three.
+Load one primary artifact per task — avoid pulling full CLI markdown trees or JSON schemas unless you need exact shapes. Agents should rely on `<subcommand> --help` for on-demand option and positional discovery.
 
 | Goal | Load |
 | --- | --- |
 | Route to the right command | `SKILL.md` (via `configure` or `docs skill`) |
-| Full command tree + option prose | `reference.md` or `docs cli` |
+| Inspect options and positional slots | `<subcommand> --help` |
+| Full command tree + option prose | `docs cli` |
 | Machine-readable CLI tree + schemas | `docs cli-schema` |
 | HTTP request/response shapes | `docs openapi` or `GET /openapi.json` |
 | MCP tool list + env config | `docs mcp` |
 
-Skill `reference.md` is **compact** (no embedded `outputSchema` JSON blocks). Fetch `cli-schema` or OpenAPI when you need exact shapes.
-
 ## Save to disk (`--save`)
 
-Pass **`--save`** on `docs` or any docs subcommand to write files under **`./docs/`** (relative to the current working directory). Each saved path is printed on stdout.
+Pass **`--save`** on `docs` or any docs subcommand to write files under **`./docs/`** (or **`./skills/<app>/`** for skills) (relative to the current working directory). Each saved path is printed on stdout.
 
 | Command | Output |
 | --- | --- |
@@ -157,6 +157,6 @@ Pass **`--save`** on `docs` or any docs subcommand to write files under **`./doc
 | `docs cli-schema --save` | `./docs/cli-schema.json` |
 | `docs openapi --save` | `./docs/openapi.json` |
 | `docs cli --save` | `./docs/cli.md` |
-| `docs skill --save` | `./docs/skill.md` |
+| `docs skill --save` | `./skills/<app>/SKILL.md` |
 
 Argsbarg-generated markdown (`mcp`, `http`, `skill`) includes a `Generated by … docs … --save` HTML comment (`skill` places it after YAML frontmatter so parsers still work). `cli-schema.json`, `openapi.json`, and argsbarg-generated markdown resolve `{argsbarg:program}` in `notes` to the program key. Consumer-authored topic files are written as-is.

package/docs/cli-program.md

@@ -112,7 +112,7 @@ Descriptions and schemas are copied into MCP tools, HTTP OpenAPI, and generated
 - Keep **`description`** strings short and action-oriented; put examples in **`notes`**, not duplicated in every option.
 - Use **`hidden: true`** or **`mcpTool.enabled: false`** for debug/internal commands.
 - For shape discovery: HTTP agents load **`docs openapi`** or `GET /openapi.json`; MCP agents use **`docs cli-schema`**; load full **`docs cli`** only when prose is needed.
-- Skill **`reference.md`** uses a compact CLI guide (no inline `outputSchema` JSON) — see [bundled-docs.md](bundled-docs.md#agent-artifact-contract).
+- Generated **`SKILL.md`** acts as an intent-based router that directs agents to `<subcommand> --help` — see [bundled-docs.md](bundled-docs.md#agent-artifact-contract).
 
 Validation: [json-schema-subset.md](json-schema-subset.md) (Draft-07 default; 2019-09 / 2020-12 when `$schema` is set — including Zod-generated schemas).
 
@@ -160,7 +160,7 @@ On **leaf commands**, set `outputSchema` to a JSON Schema describing stdout when
 }
 ```
 
-Exported in `docs cli-schema`, `docs cli`, skill `reference.md`, and MCP `tools/list`. Not validated at runtime yet. Pair with `notes` for prose examples; do not duplicate the full schema in `notes`.
+Exported in `docs cli-schema`, `docs cli`, and MCP `tools/list`. Not validated at runtime yet. Pair with `notes` for prose examples; do not duplicate the full schema in `notes`.
 
 For a **outputSchema codegen guidelines** (TypeScript types → JSON Schema → `outputSchema` constants), see [output-schema.md](output-schema.md).
 

package/docs/output-schema.md

@@ -21,7 +21,7 @@ export const status = {
 | --- | --- |
 | `myapp docs cli-schema` | Full command tree JSON export |
 | `myapp docs cli` | Markdown per-command **Output** section |
-| `myapp docs skill` | `reference.md` for agent skills |
+| `myapp docs skill` | Intent-based SKILL.md router for agent skills |
 | MCP `tools/list` | Optional `outputSchema` on each tool |
 | HTTP `GET /openapi.json` | Response schema per tool |
 

package/examples/full-example/AGENTS.md

@@ -8,7 +8,7 @@
 
 - `README.md` — user-facing install/commands
 - `docs/architecture.md` — maintainer internals (create if missing)
-- Generated: `just docgen` → `docs/cli.md`, `docs/cli-schema.json`, `docs/skill.md`
+- Generated: `just docgen` → `docs/cli.md`, `docs/cli-schema.json`, `skills/full-example/SKILL.md`
 
 <!-- argsbarg:managed -->
 
@@ -67,6 +67,8 @@ When adding commands: `src/commands/<name>/command.ts`; register in `program.ts`
 
 - **CLI:** `bun ./src/index.ts …` or `just run …`
 - **Tests:** `just test` (after `just check`)
+- **Agent discovery via `--help`:** Prefer running `<cli> <subcommand> --help` to inspect flags, defaults, and positionals on-the-fly. Avoid reading long API documentation files (`docs/cli.md`) into context.
+- **Agent skill:** `skills/<key>/SKILL.md` is an intent-based router. Run `configure install` to persist it to `~/.agents/skills/<key>/`.
 
 <!-- /argsbarg:managed -->
 

package/examples/full-example/docs/README.md

@@ -11,7 +11,7 @@ Reference template for argsbarg consumer docgen. Every builtin is enabled in `sr
 | **Full command tree (markdown)** | [cli.md](cli.md) — generated |
 | **Full command tree (JSON)** | [cli-schema.json](cli-schema.json) — generated |
 | **OpenAPI 3.1** | [openapi.json](openapi.json) — generated |
-| **Agent skill index** | [skill.md](skill.md) — generated |
+| **Agent skill router** | [../skills/full-example/SKILL.md](../skills/full-example/SKILL.md) — generated |
 
 ## Framework docs vs this directory
 

package/examples/full-example/docs/http.md

@@ -60,7 +60,7 @@ See the argsbarg [logging guide](https://github.com/bdombro/bun-argsbarg/blob/ma
 ## REST routes
 
 - `POST /echo` (CLI: `full-example echo`) — Echo a message (MCP-friendly leaf).
-- `POST /status` (CLI: `full-example status`) — Show app version. (flags: --json)
+- `POST /status` (CLI: `full-example status`) — Show app version.
 
 ## Request bodies
 

package/examples/full-example/docs/mcp.md

@@ -92,7 +92,7 @@ full-example mcp
 ## Exposed tools
 
 - `full-example echo` — echo — Echo a message (MCP-friendly leaf).
-- `full-example status` — status — Show app version. (flags: --json)
+- `full-example status` — status — Show app version.
 
 ## Tool arguments
 

package/examples/full-example/docs/openapi.json

@@ -450,12 +450,7 @@
             "application/json; charset=utf-8": {
               "schema": {
                 "type": "object",
-                "properties": {
-                  "json": {
-                    "type": "string",
-                    "description": "Emit JSON."
-                  }
-                }
+                "properties": {}
               }
             }
           }

package/examples/full-example/{docs/skill.md → skills/full-example/SKILL.md}

@@ -19,18 +19,22 @@ Invoke via shell:
 full-example <subcommand> [options] [args]
 ```
 
+## Options & Help Discovery
+
+- Run `full-example <subcommand> --help` to inspect flags, choices, and positional arguments before running unfamiliar subcommands.
+- Run `full-example --help` at the root for top-level options and command routing.
+
 ## Commands
 
 - **`full-example echo`** — Echo a message (MCP-friendly leaf).
-- **`full-example status`** — Show app version. (flags: --json)
+- **`full-example status`** — Show app version.
 
-## Pitfalls
+## Workflow & Pitfalls
 
+- Always run `full-example <subcommand> --help` instead of guessing options or reading large doc files.
 - Pass `--` before arguments that look like flags.
-
-## Reference
-
-For full detail, open `reference.md` in this skill directory (same as `full-example docs cli`).
+- Pass `--yes` for non-interactive execution when confirmation is required.
+- Pass `--json` when machine-readable structured output is supported.
 
 ## Install location
 

package/examples/full-example-json/AGENTS.md

@@ -8,7 +8,7 @@
 
 - `README.md` — user-facing install/commands
 - `docs/architecture.md` — maintainer internals (create if missing)
-- Generated: `just docgen` → `docs/cli.md`, `docs/cli-schema.json`, `docs/skill.md`
+- Generated: `just docgen` → `docs/cli.md`, `docs/cli-schema.json`, `skills/full-example-json/SKILL.md`
 
 <!-- argsbarg:managed -->
 
@@ -72,6 +72,8 @@ When adding commands: `src/commands/<name>/command.ts` + `types.ts` when schemas
 - **Runtime:** Bun (`just test`, `just dev`).
 - **Tests:** colocate `*.test.ts` next to the module.
 - **Schemagen:** after changing `/** @sg */` types in `src/`, run `just schemagen` (`__generated__/` is gitignored).
+- **Agent discovery via `--help`:** Prefer running `<cli> <subcommand> --help` to inspect flags, defaults, and positionals on-the-fly. Avoid reading long API documentation files (`docs/cli.md`) into context.
+- **Agent skill:** `skills/<key>/SKILL.md` is an intent-based router. Run `configure install` to persist it to `~/.agents/skills/<key>/`.
 
 ### Abstractions
 

package/examples/full-example-json/docs/README.md

@@ -11,7 +11,7 @@ Reference template for argsbarg consumer docgen. Every builtin is enabled in `sr
 | **Full command tree (markdown)** | [cli.md](cli.md) — generated |
 | **Full command tree (JSON)** | [cli-schema.json](cli-schema.json) — generated |
 | **OpenAPI 3.1** | [openapi.json](openapi.json) — generated |
-| **Agent skill index** | [skill.md](skill.md) — generated |
+| **Agent skill router** | [../skills/full-example-json/SKILL.md](../skills/full-example-json/SKILL.md) — generated |
 
 ## Framework docs vs this directory
 

package/examples/full-example-json/docs/http.md

@@ -61,7 +61,7 @@ See the argsbarg [logging guide](https://github.com/bdombro/bun-argsbarg/blob/ma
 
 - `POST /echo` (CLI: `full-example-json echo`) — Echo a message (MCP-friendly leaf).
 - `POST /render-json` (CLI: `full-example-json render-json`) — Echo a JSON message (schema-first JSON leaf demo).
-- `POST /status` (CLI: `full-example-json status`) — Show app version. (flags: --json)
+- `POST /status` (CLI: `full-example-json status`) — Show app version.
 - `GET /workspaces` (CLI: `full-example-json workspaces get`) — List workspaces.
 - `POST /workspaces` (CLI: `full-example-json workspaces post`) — Create a workspace.
 - `GET /workspaces/{id}` (CLI: `full-example-json workspaces :id get`) — Get one workspace.

package/examples/full-example-json/docs/mcp.md

@@ -93,13 +93,13 @@ full-example-json mcp
 
 - `full-example-json echo` — echo — Echo a message (MCP-friendly leaf).
 - `full-example-json render-json` — render-json — Echo a JSON message (schema-first JSON leaf demo).
-- `full-example-json status` — status — Show app version. (flags: --json)
-- `full-example-json workspaces get` — workspaces get — List workspaces.
-- `full-example-json workspaces post` — workspaces post — Create a workspace.
+- `full-example-json status` — status — Show app version.
+- `full-example-json workspaces :id delete` — workspaces :id delete — Delete a workspace.
 - `full-example-json workspaces :id get` — workspaces :id get — Get one workspace.
-- `full-example-json workspaces :id put` — workspaces :id put — Replace a workspace.
 - `full-example-json workspaces :id patch` — workspaces :id patch — Patch a workspace name.
-- `full-example-json workspaces :id delete` — workspaces :id delete — Delete a workspace.
+- `full-example-json workspaces :id put` — workspaces :id put — Replace a workspace.
+- `full-example-json workspaces get` — workspaces get — List workspaces.
+- `full-example-json workspaces post` — workspaces post — Create a workspace.
 
 ## Tool arguments
 

package/examples/full-example-json/docs/openapi.json

@@ -583,12 +583,7 @@
             "application/json; charset=utf-8": {
               "schema": {
                 "type": "object",
-                "properties": {
-                  "json": {
-                    "type": "string",
-                    "description": "Emit JSON."
-                  }
-                }
+                "properties": {}
               }
             }
           }

package/examples/full-example-json/{docs/skill.md → skills/full-example-json/SKILL.md}

@@ -1,7 +1,7 @@
 ---
 id: full-example-json
 name: full-example-json
-description: Operates the full-example-json CLI (echo, render-json, status, workspaces get, workspaces post, and 4 more). Use when the user mentions full-example-json, echo, render-json, status, or related tasks.
+description: Operates the full-example-json CLI (echo, render-json, status, workspaces :id delete, workspaces :id get, and 4 more). Use when the user mentions full-example-json, echo, render-json, status, or related tasks.
 enabled: true
 ---
 <!-- Generated by full-example-json docs skill --save; do not edit. -->
@@ -19,25 +19,29 @@ Invoke via shell:
 full-example-json <subcommand> [options] [args]
 ```
 
+## Options & Help Discovery
+
+- Run `full-example-json <subcommand> --help` to inspect flags, choices, and positional arguments before running unfamiliar subcommands.
+- Run `full-example-json --help` at the root for top-level options and command routing.
+
 ## Commands
 
 - **`full-example-json echo`** — Echo a message (MCP-friendly leaf).
 - **`full-example-json render-json`** — Echo a JSON message (schema-first JSON leaf demo).
-- **`full-example-json status`** — Show app version. (flags: --json)
-- **`full-example-json workspaces get`** — List workspaces.
-- **`full-example-json workspaces post`** — Create a workspace.
+- **`full-example-json status`** — Show app version.
+- **`full-example-json workspaces :id delete`** — Delete a workspace.
 - **`full-example-json workspaces :id get`** — Get one workspace.
-- **`full-example-json workspaces :id put`** — Replace a workspace.
 - **`full-example-json workspaces :id patch`** — Patch a workspace name.
-- **`full-example-json workspaces :id delete`** — Delete a workspace.
+- **`full-example-json workspaces :id put`** — Replace a workspace.
+- **`full-example-json workspaces get`** — List workspaces.
+- **`full-example-json workspaces post`** — Create a workspace.
 
-## Pitfalls
+## Workflow & Pitfalls
 
+- Always run `full-example-json <subcommand> --help` instead of guessing options or reading large doc files.
 - Pass `--` before arguments that look like flags.
-
-## Reference
-
-For full detail, open `reference.md` in this skill directory (same as `full-example-json docs cli`).
+- Pass `--yes` for non-interactive execution when confirmation is required.
+- Pass `--json` when machine-readable structured output is supported.
 
 ## Install location
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "7.0.4",
+  "version": "7.0.6",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

package/src/cli-tool/create.test.ts

@@ -83,6 +83,7 @@ describe("argsbarg create", () => {
     const tree = renderCreateTree(baseOpts({ key: "testapp" }));
     expect(tree.has("justfile")).toBe(true);
     expect(tree.has("scripts/create-identity.ts")).toBe(true);
+    expect(tree.has("skills/testapp/SKILL.md")).toBe(true);
     const identity = tree.get("scripts/create-identity.ts");
     expect(identity).toContain('key: "testapp"');
     expect(identity).toContain('template: "cli"');

package/src/cli-tool/create.ts

@@ -330,6 +330,7 @@ function listTemplateFiles(templateId: CreateTemplateId): string[] {
 }
 
 export function renderCreateTree(opts: CreateOptions): Map<string, string> {
+  const tmpl = templateIdentity(opts.templateId);
   const files = new Map<string, string>();
   for (const rel of listTemplateFiles(opts.templateId)) {
     if (rel === CREATE_IDENTITY_REL) {
@@ -338,7 +339,10 @@ export function renderCreateTree(opts: CreateOptions): Map<string, string> {
     }
     const src = join(templateDirFor(opts.templateId), rel);
     const raw = readFileSync(src, "utf8");
-    files.set(rel, substituteTemplateContent(raw, opts));
+    const targetRel = rel.startsWith(`skills/${tmpl.key}/`)
+      ? rel.replace(`skills/${tmpl.key}/`, `skills/${opts.key}/`)
+      : rel;
+    files.set(targetRel, substituteTemplateContent(raw, opts));
   }
   return files;
 }

package/src/core/parse.test.ts

@@ -3,7 +3,7 @@ Domain-specific regression tests (split from index.test.ts).
 */
 
 import { expect, test } from "bun:test";
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { $ } from "bun";
@@ -370,6 +370,184 @@ test("trailing options after bounded positionals", () => {
   expect(pr.opts.verbose).toBe("1");
 });
 
+/** Tests that options can be interleaved between bounded positionals. */
+test("options interleaved between bounded positionals", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "copy",
+        description: "copy",
+        options: [
+          {
+            name: "force",
+            description: "",
+            kind: CliOptionKind.Presence,
+            shortName: "f",
+          },
+          {
+            name: "mode",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+        ],
+        positionals: [
+          {
+            name: "src",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+          {
+            name: "dest",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  });
+  cliValidateProgram(root);
+
+  // Presence flag interleaved between positionals
+  const prPresence = postParseValidate(root, parse(root, ["copy", "file1", "--force", "file2"]));
+  expect(prPresence.kind).toBe(ParseKind.Ok);
+  expect(prPresence.args).toEqual(["file1", "file2"]);
+  expect(prPresence.opts.force).toBe("1");
+
+  // String option with value interleaved between positionals
+  const prString = postParseValidate(root, parse(root, ["copy", "file1", "--mode", "fast", "file2"]));
+  expect(prString.kind).toBe(ParseKind.Ok);
+  expect(prString.args).toEqual(["file1", "file2"]);
+  expect(prString.opts.mode).toBe("fast");
+
+  // Multiple flags interleaved between positionals
+  const prMulti = postParseValidate(root, parse(root, ["copy", "file1", "--mode", "fast", "-f", "file2"]));
+  expect(prMulti.kind).toBe(ParseKind.Ok);
+  expect(prMulti.args).toEqual(["file1", "file2"]);
+  expect(prMulti.opts.mode).toBe("fast");
+  expect(prMulti.opts.force).toBe("1");
+
+  // Unknown option interleaved between positionals returns error
+  const prUnknown = postParseValidate(root, parse(root, ["copy", "file1", "--unknown", "file2"]));
+  expect(prUnknown.kind).toBe(ParseKind.Error);
+  expect(prUnknown.errorMsg).toContain("Unknown option: --unknown");
+
+  // Interleaved help request triggers contextual help
+  const prHelp = parse(root, ["copy", "file1", "-h"]);
+  expect(prHelp.kind).toBe(ParseKind.Help);
+  expect(prHelp.helpPath).toEqual(["copy"]);
+
+  // Double dash between positionals disables option consumption
+  const prDoubleDash = postParseValidate(root, parse(root, ["copy", "file1", "--", "--force"]));
+  expect(prDoubleDash.kind).toBe(ParseKind.Ok);
+  expect(prDoubleDash.args).toEqual(["file1", "--force"]);
+  expect(prDoubleDash.opts.force).toBeUndefined();
+});
+
+/** Tests that options can be interleaved with optional positionals. */
+test("options interleaved with optional positionals", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "deploy",
+        description: "deploy",
+        options: [
+          {
+            name: "force",
+            description: "",
+            kind: CliOptionKind.Presence,
+          },
+        ],
+        positionals: [
+          {
+            name: "env",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 0,
+            argMax: 1,
+          },
+          {
+            name: "target",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 0,
+            argMax: 1,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  });
+  cliValidateProgram(root);
+
+  // Interleaved between two optional positionals
+  const prBoth = postParseValidate(root, parse(root, ["deploy", "prod", "--force", "us-east"]));
+  expect(prBoth.kind).toBe(ParseKind.Ok);
+  expect(prBoth.args).toEqual(["prod", "us-east"]);
+  expect(prBoth.opts.force).toBe("1");
+
+  // Option after first optional positional when second is omitted
+  const prOne = postParseValidate(root, parse(root, ["deploy", "prod", "--force"]));
+  expect(prOne.kind).toBe(ParseKind.Ok);
+  expect(prOne.args).toEqual(["prod"]);
+  expect(prOne.opts.force).toBe("1");
+
+  // Option before optional positionals when all are omitted
+  const prNone = postParseValidate(root, parse(root, ["deploy", "--force"]));
+  expect(prNone.kind).toBe(ParseKind.Ok);
+  expect(prNone.args).toEqual([]);
+  expect(prNone.opts.force).toBe("1");
+});
+
+/** Tests that options can be interleaved between bounded positional and varargs tail. */
+test("options interleaved between bounded positional and varargs tail", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "upload",
+        description: "upload",
+        options: [
+          {
+            name: "json",
+            description: "",
+            kind: CliOptionKind.Presence,
+          },
+        ],
+        positionals: [
+          {
+            name: "target",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 1,
+            argMax: 1,
+          },
+          {
+            name: "files",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 1,
+            argMax: 0,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  });
+  cliValidateProgram(root);
+
+  // Flag between target and files does not get captured as first file
+  const pr = postParseValidate(root, parse(root, ["upload", "s3", "--json", "a.txt", "b.txt"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.args).toEqual(["s3", "a.txt", "b.txt"]);
+  expect(pr.opts.json).toBe("1");
+});
+
 /** Tests that options on routing groups are rejected at schema validation. */
 test("rejects options on routing groups", () => {
   const root = testProgram({
@@ -1174,29 +1352,29 @@ test("configure.prefix is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/configure\.prefix removed/);
 });
 
-/** Tests that generateSkillBundle includes frontmatter and compact command index. */
-test("generateSkillBundle includes frontmatter and compact command index", () => {
+/** Tests that generateSkillBundle includes frontmatter and intent-based router. */
+test("generateSkillBundle includes frontmatter and intent-based router", () => {
   const bundle = generateSkillBundle(nestedMcpFixture);
   expect(bundle.dirName).toBe("nested.ts");
   expect(bundle.skillMd).toMatch(/^---\nid: nested\.ts\nname: nested\.ts\n/);
   expect(bundle.skillMd).toContain("enabled: true");
   expect(bundle.skillMd).toContain("dotagentsprotocol.com");
   expect(bundle.skillMd).toContain("~/.claude/skills/nested.ts");
+  expect(bundle.skillMd).toContain("Options & Help Discovery");
+  expect(bundle.skillMd).toContain("Run `nested.ts <subcommand> --help`");
   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("For full detail, open `reference.md`");
+  expect(bundle.skillMd).toContain("Workflow & Pitfalls");
   expect(bundle.skillMd).toContain("~/.agents/skills/nested.ts/");
+  expect(bundle.skillMd).not.toContain("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("CLI API reference");
-  expect(bundle.referenceMd).toContain("#### Options");
-  expect(bundle.referenceMd).not.toContain("Generated by");
-  expect(bundle.referenceMd).not.toContain("```json");
+  expect((bundle as unknown as Record<string, unknown>).referenceMd).toBeUndefined();
 });
 
 /** Tests that generatePluginSkillBundle is MCP routing stub without shell catalog. */
@@ -1224,15 +1402,34 @@ test("cliSkillInstall writes project agent skill files", () => {
     expect(files.some((f) => f.includes(".agents/skills/nested.ts/"))).toBe(true);
     const skillDir = join(cwd, ".agents", "skills", "nested.ts");
     expect(existsSync(join(skillDir, "SKILL.md"))).toBe(true);
-    expect(existsSync(join(skillDir, "reference.md"))).toBe(true);
+    expect(existsSync(join(skillDir, "skill.md"))).toBe(true);
+    expect(existsSync(join(skillDir, "reference.md"))).toBe(false);
     expect(readFileSync(join(skillDir, "SKILL.md"), "utf8")).toContain("## Commands");
-    expect(readFileSync(join(skillDir, "reference.md"), "utf8")).toContain("CLI API reference");
+    expect(readFileSync(join(skillDir, "SKILL.md"), "utf8")).toContain("Options & Help Discovery");
     const skillText = readFileSync(join(skillDir, "SKILL.md"), "utf8");
     expect(skillText.startsWith("---\n")).toBe(true);
     const hint = "<!-- Generated by nested.ts configure; do not edit. -->";
     expect(skillText.indexOf(hint)).toBeGreaterThan(skillText.indexOf("---\n", 4));
-    const refText = readFileSync(join(skillDir, "reference.md"), "utf8");
-    expect(refText.startsWith(hint)).toBe(true);
+  } finally {
+    process.chdir(prev);
+    rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+/** CliSkillInstall removes legacy reference.md if present. */
+test("cliSkillInstall removes legacy reference.md if present", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-legacy-"));
+  const prev = process.cwd();
+  process.chdir(cwd);
+  try {
+    const skillDir = join(cwd, ".agents", "skills", "nested.ts");
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(join(skillDir, "reference.md"), "legacy reference content", "utf8");
+    expect(existsSync(join(skillDir, "reference.md"))).toBe(true);
+
+    cliSkillInstall(nestedMcpFixture, { global: false, rimraf: false });
+    expect(existsSync(join(skillDir, "SKILL.md"))).toBe(true);
+    expect(existsSync(join(skillDir, "reference.md"))).toBe(false);
   } finally {
     process.chdir(prev);
     rmSync(cwd, { recursive: true, force: true });

package/src/core/parse.ts

@@ -351,9 +351,47 @@ function finishLeaf(
   const args: string[] = [];
   let forcePositionals = forcePositionalsIn;
 
+  /**
+   * Consumes any pending options, `--`, or help flags at the current argv index.
+   * Sets `forcePositionals = true` when `--` is encountered.
+   * Returns a help or error ParseResult if parsing halts, or null to continue positional consumption.
+   */
+  function consumePendingOptions(): ParseResult | null {
+    while (!forcePositionals && idx < argv.length) {
+      const tok = argv[idx];
+      if (tok === "--") {
+        forcePositionals = true;
+        idx += 1;
+        break;
+      }
+      if (isHelpTok(tok)) {
+        return helpResult(path, true, pathParams);
+      }
+      if (tok.startsWith("-")) {
+        const rep = consumeOptions(optionDefs, false, argv, idx, opts);
+        if (rep.report.err) {
+          return errorResult(rep.report.err, path, [], pathParams);
+        }
+        if (rep.report.sawDoubleDash) {
+          forcePositionals = true;
+        }
+        if (rep.nextIndex > idx) {
+          idx = rep.nextIndex;
+          continue;
+        }
+        return errorResult(`Unexpected option token: ${tok}`, path, [], pathParams);
+      }
+      break;
+    }
+    return null;
+  }
+
   for (const p of node.positionals ?? []) {
     const { argMin = 1, argMax = 1 } = p;
     if (argMax === 1) {
+      const pendingErr = consumePendingOptions();
+      if (pendingErr) return pendingErr;
+
       if (argMin >= 1) {
         if (idx >= argv.length) {
           return errorResult(`Missing positional argument: ${p.name}`, path, [], pathParams);
@@ -361,13 +399,8 @@ function finishLeaf(
         args.push(argv[idx]);
         idx += 1;
       } else if (idx < argv.length) {
-        const tok = argv[idx];
-        if (argMin < 1 && tok.startsWith("-")) {
-          // Optional slot: leave `-` tokens for trailing option parsing.
-        } else {
-          args.push(tok);
-          idx += 1;
-        }
+        args.push(argv[idx]);
+        idx += 1;
       }
       continue;
     }
@@ -375,40 +408,20 @@ function finishLeaf(
     let count = 0;
     if (argMax === 0) {
       while (idx < argv.length) {
-        const tok = argv[idx];
-
-        if (!forcePositionals && tok === "--") {
-          forcePositionals = true;
-          idx++;
-          continue;
-        }
+        const pendingErr = consumePendingOptions();
+        if (pendingErr) return pendingErr;
+        if (idx >= argv.length) break;
 
-        if (!forcePositionals && isHelpTok(tok)) {
-          return helpResult(path, true, pathParams);
-        }
-
-        if (!forcePositionals && tok.startsWith("-")) {
-          // MUST be false — lenient mode swallows unknown flags as positionals silently
-          const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
-          if (tailRep.report.err) {
-            return errorResult(tailRep.report.err, path, [], pathParams);
-          }
-          if (tailRep.report.sawDoubleDash) {
-            forcePositionals = true;
-          }
-          if (tailRep.nextIndex > idx) {
-            idx = tailRep.nextIndex;
-            continue;
-          }
-          return errorResult(`Unexpected option token: ${tok}`, path, [], pathParams);
-        }
-
-        args.push(tok);
-        idx++;
-        count++;
+        args.push(argv[idx]);
+        idx += 1;
+        count += 1;
       }
     } else {
       while (count < argMax && idx < argv.length) {
+        const pendingErr = consumePendingOptions();
+        if (pendingErr) return pendingErr;
+        if (idx >= argv.length) break;
+
         args.push(argv[idx]);
         idx += 1;
         count += 1;
@@ -419,24 +432,11 @@ function finishLeaf(
     }
   }
 
-  if (idx < argv.length) {
-    if (forcePositionals) {
-      return errorResult("Unexpected extra arguments", path, [], pathParams);
-    }
-
-    if (isHelpTok(argv[idx])) {
-      return helpResult(path, true, pathParams);
-    }
+  const trailingErr = consumePendingOptions();
+  if (trailingErr) return trailingErr;
 
-    const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
-    if (tailRep.report.err) {
-      return errorResult(tailRep.report.err, path, [], pathParams);
-    }
-    idx = tailRep.nextIndex;
-
-    if (idx < argv.length) {
-      return errorResult("Unexpected extra arguments", path, [], pathParams);
-    }
+  if (idx < argv.length) {
+    return errorResult("Unexpected extra arguments", path, [], pathParams);
   }
 
   return {

package/src/docs/docs.test.ts

@@ -259,7 +259,8 @@ 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("For full detail, open `reference.md`");
+  expect(result.stdout).toContain("--help");
+  expect(result.stdout).not.toContain("reference.md");
   expect(result.stdout).not.toContain("#### Options");
   expect(result.stdout).not.toContain("mcp.json");
 });
@@ -329,10 +330,11 @@ test("docs cli --save prepends generated hint", async () => {
   expect(text).toContain("CLI API reference");
 });
 
-test("docs skill --save keeps frontmatter first", async () => {
+test("docs skill --save writes skills/<app>/SKILL.md and keeps frontmatter first", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "skill", "--save"]);
   expect(result.exitCode).toBe(0);
-  const text = readFileSync(join(workDir, "docs/skill.md"), "utf8");
+  expect(result.stdout.trim()).toBe("skills/myapp/SKILL.md");
+  const text = readFileSync(join(workDir, "skills/myapp/SKILL.md"), "utf8");
   expect(text.startsWith("---\n")).toBe(true);
   expect(text).toContain("name: myapp");
   const hint = "<!-- Generated by myapp docs skill --save; do not edit. -->";

package/src/docs/save.ts

@@ -1,7 +1,13 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+/*
+This module persists bundled documentation topics to disk when `--save` is passed.
+It writes documentation under `./docs/` and agent skills under `./skills/<app-name>/SKILL.md`.
+*/
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import type { CliProgram } from "../core/types.ts";
 import { generatedFileHtmlComment, insertGeneratedHint } from "../skill/hint.ts";
+import { skillDirName } from "../skill/naming.ts";
 import { docsTopicContent } from "./resolve.ts";
 
 /** Relative output directory for `docs --save`. */
@@ -11,17 +17,32 @@ export const DOCS_SAVE_DIR = "docs";
 export const DOCS_GENERATED_SAVE_TOPICS = ["mcp", "cli", "skill", "http"] as const;
 
 /** Whether `--save` should prepend a generated-file hint (argsbarg writers only). */
-export function docsTopicIsGeneratedByArgsbarg(topic: string): boolean {
+export function docsTopicIsGeneratedByArgsbarg(
+  /** Topic name. */
+  topic: string,
+): boolean {
   return (DOCS_GENERATED_SAVE_TOPICS as readonly string[]).includes(topic);
 }
 
 /** HTML comment for generated markdown saved with `--save`. */
-export function docsSaveGeneratedHint(program: CliProgram, topic: string): string {
+export function docsSaveGeneratedHint(
+  /** Program definition. */
+  program: CliProgram,
+  /** Topic name. */
+  topic: string,
+): string {
   return generatedFileHtmlComment(`${program.key} docs ${topic} --save`);
 }
 
 /** Inserts save hint without breaking YAML frontmatter (`docs skill`). */
-export function applySaveGeneratedHint(program: CliProgram, topic: string, content: string): string {
+export function applySaveGeneratedHint(
+  /** Program definition. */
+  program: CliProgram,
+  /** Topic name. */
+  topic: string,
+  /** Markdown text. */
+  content: string,
+): string {
   if (!docsTopicIsGeneratedByArgsbarg(topic)) {
     return content;
   }
@@ -30,12 +51,20 @@ export function applySaveGeneratedHint(program: CliProgram, topic: string, conte
 }
 
 /** File body for `--save` (hint on argsbarg-generated markdown only). */
-export function docsTopicContentForSave(program: CliProgram, topic: string): string {
+export function docsTopicContentForSave(
+  /** Program definition. */
+  program: CliProgram,
+  /** Topic name. */
+  topic: string,
+): string {
   return applySaveGeneratedHint(program, topic, docsTopicContent(program, topic));
 }
 
 /** Filename for a saved docs topic. */
-export function docsSaveFilename(topic: string): string {
+export function docsSaveFilename(
+  /** Topic name. */
+  topic: string,
+): string {
   if (topic === "cli-schema") {
     return "cli-schema.json";
   }
@@ -45,18 +74,37 @@ export function docsSaveFilename(topic: string): string {
   return `${topic}.md`;
 }
 
-/** Relative path under cwd for a saved docs topic. */
-export function docsSaveRelativePath(topic: string): string {
+/** Relative path under cwd for a saved docs topic (or skills/<key>/SKILL.md for skill). */
+export function docsSaveRelativePath(
+  /** Topic identifier. */
+  topic: string,
+  /** Program root for resolving app-specific paths like skill directories. */
+  program?: CliProgram,
+): string {
+  if (topic === "skill" && program) {
+    return join("skills", skillDirName(program.key), "SKILL.md");
+  }
   return join(DOCS_SAVE_DIR, docsSaveFilename(topic));
 }
 
-/** Writes one docs topic under `./docs/`; returns relative path written. */
-export function saveDocsTopic(program: CliProgram, topic: string): string {
-  const dir = join(process.cwd(), DOCS_SAVE_DIR);
-  mkdirSync(dir, { recursive: true });
-
-  const rel = docsSaveRelativePath(topic);
+/** Writes one docs topic under `./docs/` or `./skills/<key>/`; returns relative path written. */
+export function saveDocsTopic(
+  /** Program definition root. */
+  program: CliProgram,
+  /** Topic identifier to save. */
+  topic: string,
+): string {
+  const rel = docsSaveRelativePath(topic, program);
   const abs = join(process.cwd(), rel);
+  mkdirSync(dirname(abs), { recursive: true });
+
+  if (topic === "skill") {
+    const legacyDoc = join(process.cwd(), DOCS_SAVE_DIR, "skill.md");
+    if (existsSync(legacyDoc)) {
+      rmSync(legacyDoc, { force: true });
+    }
+  }
+
   writeFileSync(abs, docsTopicContentForSave(program, topic), "utf8");
   return rel;
 }

package/src/skill/generate.ts

@@ -1,10 +1,11 @@
 /*
-This module generates Agent Skills content (SKILL.md + reference.md) from a CLI schema.
+This module generates Agent Skills content (SKILL.md) from a CLI schema.
+It creates an intent-based router that directs agents to specific subcommands
+and guides them to use `--help` for option and flag discovery.
 */
 
 import { defaultConfigEntryTitle } from "../config/entry.ts";
 import { CliOptionKind, type CliProgram } from "../core/types.ts";
-import { generateCliGuide } from "../docs/cli-guide.ts";
 import {
   collectMcpTools,
   leafWireOptions,
@@ -15,15 +16,19 @@ import {
 } from "../mcp/tools.ts";
 import { skillDirName } from "./naming.ts";
 
+/** Agent skill bundle containing the target directory name and SKILL.md router content. */
 export interface SkillBundle {
+  /** Target directory name under `~/.agents/skills/`. */
   dirName: string;
+  /** Generated SKILL.md router content. */
   skillMd: string;
-  referenceMd: string;
 }
 
 /** MCP routing skill for Claude Code plugin zips (SKILL.md only). */
 export interface PluginSkillBundle {
+  /** Target directory name under `skills/`. */
   dirName: string;
+  /** Generated plugin SKILL.md content. */
   skillMd: string;
 }
 
@@ -65,7 +70,7 @@ function commandCatalogPath(root: CliProgram, tool: McpToolDef): string {
   return `${base} ${slots.join(" ")}`;
 }
 
-/** Formats one command line for the SKILL.md index (details live in reference.md). */
+/** Formats one command line for the SKILL.md router. */
 function formatCommandEntry(root: CliProgram, tool: McpToolDef): string {
   const cliPath = commandCatalogPath(root, tool);
   let line = `- **\`${cliPath}\`** — ${tool.leaf.description}`;
@@ -85,6 +90,7 @@ function formatCommandEntry(root: CliProgram, tool: McpToolDef): string {
   return line;
 }
 
+/** Builds configuration section for SKILL.md when appConfig entries exist. */
 function buildConfigurationSection(root: CliProgram): string[] {
   const schema = root.appConfig?.entries;
   if (!schema || Object.keys(schema).length === 0) {
@@ -100,7 +106,7 @@ function buildConfigurationSection(root: CliProgram): string[] {
   return lines;
 }
 
-/** Builds SKILL.md body for the agent skill bundle. */
+/** Builds SKILL.md body for the agent skill bundle as an intent-based router. */
 function buildSkillMd(root: CliProgram, dirName: string): string {
   const name = dirName;
   const description = skillDescription(root);
@@ -126,6 +132,11 @@ function buildSkillMd(root: CliProgram, dirName: string): string {
     `${root.key} <subcommand> [options] [args]`,
     "```",
     "",
+    "## Options & Help Discovery",
+    "",
+    `- Run \`${root.key} <subcommand> --help\` to inspect flags, choices, and positional arguments before running unfamiliar subcommands.`,
+    `- Run \`${root.key} --help\` at the root for top-level options and command routing.`,
+    "",
     "## Commands",
     "",
   ];
@@ -142,13 +153,12 @@ function buildSkillMd(root: CliProgram, dirName: string): string {
   lines.push(...buildConfigurationSection(root));
 
   lines.push(
-    "## Pitfalls",
+    "## Workflow & Pitfalls",
     "",
+    `- Always run \`${root.key} <subcommand> --help\` instead of guessing options or reading large doc files.`,
     "- Pass `--` before arguments that look like flags.",
-    "",
-    "## Reference",
-    "",
-    `For full detail, open \`reference.md\` in this skill directory (same as \`${root.key} docs cli\`).`,
+    "- Pass `--yes` for non-interactive execution when confirmation is required.",
+    "- Pass `--json` when machine-readable structured output is supported.",
     "",
     "## Install location",
     "",
@@ -171,11 +181,6 @@ function buildSkillMd(root: CliProgram, dirName: string): string {
   return lines.join("\n");
 }
 
-/** Builds reference.md with the compact `docs cli` markdown guide. */
-function buildReferenceMd(root: CliProgram): string {
-  return generateCliGuide(root, { compact: true });
-}
-
 /** Builds MCP routing SKILL.md for Claude Code plugin zips. */
 function buildPluginSkillMd(root: CliProgram, dirName: string): string {
   const name = sanitizeToolSegment(root.key);
@@ -224,12 +229,11 @@ export function generatePluginSkillBundle(root: CliProgram): PluginSkillBundle {
   };
 }
 
-/** Generates SKILL.md and reference.md for agent skill install. */
+/** Generates SKILL.md router content for agent skill install. */
 export function generateSkillBundle(root: CliProgram): SkillBundle {
   const dirName = skillDirName(root.key);
   return {
     dirName,
     skillMd: buildSkillMd(root, dirName),
-    referenceMd: buildReferenceMd(root),
   };
 }

package/src/skill/hint.ts

@@ -1,3 +1,8 @@
+/*
+This module provides HTML comment hints embedded in generated documentation
+and agent skill artifacts to mark them as machine-generated.
+*/
+
 import type { CliProgram } from "../core/types.ts";
 
 /** YAML frontmatter block at the start of SKILL.md. */
@@ -24,16 +29,11 @@ export function skillInstallHint(program: CliProgram): string {
   return generatedFileHtmlComment(`${program.key} configure`);
 }
 
-/** Applies install hints to SKILL.md (after frontmatter) and reference.md. */
-export function applySkillInstallHints(
-  program: CliProgram,
-  skillMd: string,
-  referenceMd: string,
-): { skillMd: string; referenceMd: string } {
+/** Applies install hint to SKILL.md (after frontmatter). */
+export function applySkillInstallHints(program: CliProgram, skillMd: string): { skillMd: string } {
   const hint = skillInstallHint(program);
   return {
     skillMd: insertGeneratedHint(skillMd, hint, { afterFrontmatter: true }),
-    referenceMd: insertGeneratedHint(referenceMd, hint),
   };
 }
 
@@ -42,19 +42,6 @@ export function skillBundleHint(program: CliProgram): string {
   return generatedFileHtmlComment(`${program.key} mcp bundle`);
 }
 
-/** Applies bundle hints to SKILL.md (after frontmatter) and reference.md. */
-export function applySkillBundleHints(
-  program: CliProgram,
-  skillMd: string,
-  referenceMd: string,
-): { skillMd: string; referenceMd: string } {
-  const hint = skillBundleHint(program);
-  return {
-    skillMd: insertGeneratedHint(skillMd, hint, { afterFrontmatter: true }),
-    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/skill/install.ts

@@ -1,3 +1,8 @@
+/*
+This module installs agent skills to ~/.agents/skills/<key>/ per the dotagents protocol.
+It writes skill.md and SKILL.md (compatibility copy) as an intent-based router.
+*/
+
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { CliProgram } from "../core/types.ts";
@@ -8,9 +13,13 @@ import { skillDirName } from "./naming.ts";
 
 export { skillDirName } from "./naming.ts";
 
+/** Options for agent skill installation. */
 export interface SkillInstallOpts {
+  /** When true, installs to user home ~/.agents/skills/<key>/; otherwise project .agents/skills/<key>/. */
   global?: boolean;
+  /** When true, removes existing directory before installing. */
   rimraf?: boolean;
+  /** When true, computes file paths without writing to disk. */
   dry?: boolean;
 }
 
@@ -20,10 +29,10 @@ export function resolveAgentsSkillDir(root: CliProgram, global = true): string {
   return join(base, ".agents", "skills", skillDirName(root.key));
 }
 
-/** Writes skill.md, SKILL.md (compatibility copy), and reference.md; returns changed file paths. */
+/** Writes skill.md and SKILL.md (compatibility copy); returns changed file paths. */
 export function cliSkillInstall(root: CliProgram, opts: SkillInstallOpts): string[] {
   const bundle = generateSkillBundle(root);
-  const { skillMd, referenceMd } = applySkillInstallHints(root, bundle.skillMd, bundle.referenceMd);
+  const { skillMd } = applySkillInstallHints(root, bundle.skillMd);
   const dir = resolveAgentsSkillDir(root, opts.global ?? true);
   const changed: string[] = [];
 
@@ -33,17 +42,19 @@ export function cliSkillInstall(root: CliProgram, opts: SkillInstallOpts): strin
 
   const skillPath = join(dir, "skill.md");
   const skillCompatPath = join(dir, "SKILL.md");
-  const refPath = join(dir, "reference.md");
 
   if (!opts.dry) {
     mkdirSync(dir, { recursive: true });
+    const legacyRef = join(dir, "reference.md");
+    if (existsSync(legacyRef)) {
+      rmSync(legacyRef, { force: true });
+    }
     writeFileSync(skillPath, skillMd, "utf8");
     writeFileSync(skillCompatPath, skillMd, "utf8");
-    writeFileSync(refPath, referenceMd, "utf8");
     process.stdout.write(`Installed skill to ${displayHomePath(dir)}/\n`);
   }
 
-  changed.push(skillPath, skillCompatPath, refPath);
+  changed.push(skillPath, skillCompatPath);
   return changed;
 }