argsbarg 7.0.5 → 7.0.7

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [7.0.7] - 2026-09-15
+
+### Removed
+
+- **Removed all skill generation features** — completely removed the `docs skill` (and `docs skill --save`) built-in subcommands from the CLI runtime. Skill files are no longer generated from code or schemas. Skills are purely authored starter templates located at `skills/<app>/SKILL.md` (conforming to the open https://dotagentsprotocol.com standard), included with examples and scaffolded via `argsbarg create`. Removed skill bundle generation from `configure install` (uninstall continues to clean up legacy `~/.agents/skills/<key>/` directories). Deprecated `program.skill`.
+
+### Changed
+
+- **Consumer AGENTS.md scoped to app authors** — adjusted instructions in `AGENTS.md` copy templates and consumer checkouts. Removed consumer-facing discovery instructions (`--help` discovery belongs in `SKILL.md` for end-user agents) and added guidance for authoring agents to maintain `skills/<key>/SKILL.md` when adding or modifying commands.
+- **Omit skill from consumer docgen** — in consumer copy templates, `just docgen` omits skill generation so author customizations in `skills/<app>/SKILL.md` are not overwritten. Skills are included with examples and scaffolded via `argsbarg create`.
+
+## [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
@@ -965,7 +984,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.5...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.0.7...HEAD
+[7.0.7]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.7
+[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

package/README.md

@@ -11,7 +11,7 @@ Why ArgsBarg?
 
 *Schema-first & Auto-validated* — Define your entire command structure, options, description, and inputs once. ArgsBarg compiles this into type-safe option accessors, command-line routing, and validation schemas, keeping your code and interfaces perfectly aligned.
 
-*Automated Schemagen & Docgen* — Maintain single-source truth by decorating standard TypeScript types (`/** @sg */ interface...`) to automatically compile them into runtime validation schemas (`argsbarg schemagen`). Easily export standard-compliant API documentation, full CLI reference markdown, OpenAPI 3.1 definitions, and agent skill sheets directly from your code (`docs --save` command) using introspection.
+*Automated Schemagen & Docgen* — Maintain single-source truth by decorating standard TypeScript types (`/** @sg */ interface...`) to automatically compile them into runtime validation schemas (`argsbarg schemagen`). Easily export standard-compliant API documentation, full CLI reference markdown, and OpenAPI 3.1 definitions directly from your code (`docs --save` command) using introspection.
 
 *Production REST Server* — Instantly expose your commands as HTTP REST endpoints (`POST /v1/some-command`) with built-in Kubernetes-compliant `/health/liveness` and `/health/readiness` probes, ECS structured JSON logging to `stderr`, and auto-generated OpenAPI 3.1 specs with an interactive Swagger UI.
 
@@ -383,9 +383,9 @@ bun scripts/merge-agents-md.ts .
 
 This refreshes the argsbarg-managed section in `AGENTS.md` while preserving your app-specific prefix and `**<app> conventions:**` footer. See **Agent instructions** in [docs/cli-program.md](docs/cli-program.md).
 
-### 3. Generated Skills & Workspace Configuration
+### 3. Agent 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 }`.
+ArgsBarg CLIs adopt the open repository skill convention (`skills/<app>/SKILL.md`) per the standard at https://dotagentsprotocol.com/. Scaffolding via `argsbarg create` copies an initial `SKILL.md` template directing agents to run `<subcommand> --help` for just-in-time option discovery. Running `myapp configure install` registers your MCP server in `~/.agents/mcp.json` and bootstraps app configuration.
 
 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/README.md

@@ -15,7 +15,7 @@ Start here to pick the right guide.
 | **Shipping configure / agent artifacts** | [configure.md](configure.md) — Homebrew + `myapp configure install` |
 | **Homebrew tap-from-repo distribution** | [distribution-homebrew.md](distribution-homebrew.md) — formula pattern, `argsbarg create` |
 | **Bundling `myapp docs` topics** | [bundled-docs.md](bundled-docs.md) — consumer docgen vs framework docs |
-| **Agent skills** | [ai-skills.md](ai-skills.md) — `configure`, `docs skill` |
+| **Agent skills** | [ai-skills.md](ai-skills.md) — repository skills (`skills/<app>/SKILL.md`) |
 | **Maintaining the argsbarg repo** | [developing.md](developing.md) — release, consumers, npm `files` |
 | **IDE agents in a consumer app** | `bunx argsbarg create` (includes `AGENTS.md`) or `bun scripts/merge-agents-md.ts .` from argsbarg checkout |
 | **Runnable examples** (shipped in npm) | [examples/](examples/) — see table below |

package/docs/ai-skills.md

@@ -1,75 +1,30 @@
 # Agent skills
 
-> This feature is experimental.
+ArgsBarg CLIs adopt the open repository skill convention (`skills/<app>/SKILL.md`) per the standard at https://dotagentsprotocol.com/.
 
-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/.
+## Repository skill (`skills/<app>/SKILL.md`)
 
-## Enable on the program root
+ArgsBarg CLI templates and `argsbarg create` scaffold an initial `skills/<app>/SKILL.md` directly in the consumer repository. Committing this file allows agents, tools, and skill managers (such as `npx skills add`) to discover and install your CLI's skill directly from the source repository.
 
-```typescript
-export const program = {
-  key: "myapp",
-  skill: { enabled: true },
-  ...
-} satisfies CliProgram;
-```
+Because developers customize `skills/<app>/SKILL.md` with domain workflows, execution tips, and specific examples, skills are **authored artifacts**, not dynamically generated from code. Consumer `just docgen` refreshes only API and schema docs under `./docs/` and never overwrites repository skills.
 
-When `skill.enabled` is `true`, run `configure install` after `brew install` or `brew upgrade` to install and refresh the skill. When omitted or `enabled` is not `true`, no skill is installed.
+### Structure of `skills/<app>/SKILL.md`
 
-The skill directory name is the program `key` with `/`, `\`, and spaces replaced by `_` (e.g. `sqsp-qa`, `full-example`).
+- **YAML frontmatter** — `id`, `name`, `description`, `enabled` per https://dotagentsprotocol.com
+- **Options & Help Discovery** — guides agents to discover arguments and flags just-in-time via `<command> --help`
+- **Commands catalog** — compact intent-based router directing agents to the right subcommands
+- **Workflow & Pitfalls** — guidelines for automated execution (e.g. using non-interactive flags like `--yes`)
 
-## Install via `configure install`
+## Claude Code plugin
 
-```bash
-myapp configure install
-```
+When `mcpServer.claudePlugin: true` is configured, running `myapp mcp bundle` packages `dist/claude-plugin/<name>.zip` containing an MCP pointer skill (`SKILL.md` only) that routes Claude Code to the bundled MCP server. This is a dist packaging artifact, not installed via `configure`.
 
-Skills are installed via `configure install` and removed via `configure uninstall` (run `just install-local` / `just uninstall` in dev).
+## Uninstalling legacy skills
 
-## Programmatic install
-
-```typescript
-import { cliSkillInstall } from "argsbarg/skill/install"; // internal module
-```
-
-`cliSkillInstall(root, { global: true, rimraf: true })` returns changed file paths.
-
-## 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`** — 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`.
-
-## Client setup
-
-| Client | Skill path |
-| --- | --- |
-| Cursor, Codex, Copilot, most agents | `~/.agents/skills/<key>/` (auto via `configure install`) |
-| Claude Code | Manual symlink to `~/.claude/skills/<key>/` |
-
-```bash
-mkdir -p ~/.claude/skills
-ln -sf ~/.agents/skills/<key> ~/.claude/skills/<key>
-```
-
-Skills describe **shell invocation only** — no MCP setup or `tools/call` guidance. Use **`myapp docs mcp`** (when `docs` and `mcpServer` are enabled) or connect the MCP server for agent execution.
-
-## MCP vs skills vs docs
-
-| Mechanism | Role |
-| --- | --- |
-| **`myapp mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
-| **`program.skill.enabled`** + **`configure install`** | Persists optimized skill bundle 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).
-
-**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`.
+If an earlier version of an app installed a skill to `~/.agents/skills/<key>/`, running `myapp configure uninstall` cleans up that directory.
 
 See also:
 
 - [Bundled docs](bundled-docs.md) — `docs` config and compile-time imports
 - [MCP server](mcp.md) — `mcpServer` config and `mcp` protocol
-- [Configure](configure.md) — app, completions, skills, and MCP config
+- [Configure](configure.md) — app config and MCP registration

package/docs/bundled-docs.md

@@ -56,17 +56,15 @@ myapp docs readme
 myapp docs architecture
 myapp docs cli-schema       # full command tree as JSON
 myapp docs cli          # command tree as markdown
-myapp docs skill        # generated Cursor SKILL.md
 myapp docs mcp          # auto-generated when mcpServer.enabled
 myapp docs http         # auto-generated when httpServer.enabled
 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 cli --save      # write ./docs/cli.md
 ```
 
-Top-level `myapp --help` points agents at `myapp docs skill`. The `docs skill` subcommand description recommends `configure` for a persisted bundle.
-
 ## Configuration
 
 | Field | Default | Purpose |
@@ -75,7 +73,7 @@ Top-level `myapp --help` points agents at `myapp docs skill`. The `docs skill` s
 | `description` | `"Print bundled CLI documentation."` | Router help for `myapp docs` |
 | `topics` | *(none)* | Optional topic key → `{ text, description? }` |
 
-Reserved topic keys in `topics`: **`http`**, **`mcp`**, **`all`**, **`schema`**, **`cli`**, **`skill`**, **`openapi`** (reserved — use the matching `docs <name>` subcommand instead).
+Reserved topic keys in `topics`: **`http`**, **`mcp`**, **`all`**, **`schema`**, **`cli`**, **`openapi`** (reserved — use the matching `docs <name>` subcommand instead).
 
 When `description` is omitted on a topic, ArgsBarg generates leaf help (`readme` → "Print README (user guide).").
 
@@ -91,13 +89,12 @@ Bun embeds the file when you `bun build --compile`. ArgsBarg does not read the f
 
 Inline topics in your program root when the set is small; use a separate module only if the import map grows enough to clutter `index.tsx`.
 
-## CLI schema, API, and skill (`docs cli-schema`, `docs cli`, `docs skill`)
+## CLI schema and API (`docs cli-schema`, `docs cli`)
 
 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`).
 
 ## MCP guide (`docs mcp`)
 
@@ -123,8 +120,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 |
-| `docs skill` | Print generated `SKILL.md` to stdout |
+| `skills/<app>/SKILL.md` | Authored repository skill router |
 | `docs cli` | Print command tree markdown to stdout |
 | `docs cli-schema` | Print command tree JSON to stdout |
 | `docs` | Bundled markdown topics on stdout |
@@ -135,18 +131,17 @@ 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` |
+| Route to the right command | `skills/<app>/SKILL.md` (repository skill) |
+| 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.
@@ -157,6 +152,7 @@ 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` |
 
-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.
+> **Repository skill convention:** Scaffolding (`argsbarg create`) includes `./skills/<app>/SKILL.md` from the project template as an editable intent-based router. In consumer projects, `just docgen` intentionally refreshes only API/CLI reference docs under `./docs/` (`cli.md`, `cli-schema.json`, `mcp.md`, etc.), leaving `skills/<app>/SKILL.md` for hand-crafted agent instructions and domain workflows.
+
+Argsbarg-generated markdown (`mcp`, `http`) includes a `Generated by … docs … --save` HTML comment. `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

@@ -1,6 +1,6 @@
 # Writing `CliProgram` and leaf commands
 
-ArgsBarg turns your schema into help, shell completions, MCP tools, and agent skills. **The same `description` fields you write for humans are the agent contract** for basic apps.
+ArgsBarg turns your schema into help, shell completions, and MCP tools. **The same `description` fields you write for humans are the agent contract** for basic apps.
 
 **Documentation map:** [docs/README.md](README.md) — which guide to read for MCP, configure, consumer docgen, and Cursor setup.
 
@@ -90,7 +90,7 @@ export const reserveCommand = {
 
 Use a **parameterized factory** only when the schema truly depends on inputs (e.g. `createUpsertCommand(deps)` for tests or injected config). A `reserveCommand()` that returns a static literal adds indirection without benefit.
 
-**`satisfies CliProgram`** on the root (or **`satisfies CliLeaf`** / router type on extracted modules) preserves type-checking whether inline or not. Keep **program-root fields in alphabetical order** (`appConfig`, `commands`, `description`, `docs`, `hooks`, `httpServer`, `key`, `mcpServer`, `readiness`, `skill`, `version`, …).
+**`satisfies CliProgram`** on the root (or **`satisfies CliLeaf`** / router type on extracted modules) preserves type-checking whether inline or not. Keep **program-root fields in alphabetical order** (`appConfig`, `commands`, `description`, `docs`, `hooks`, `httpServer`, `key`, `mcpServer`, `readiness`, `version`, …).
 
 ## Descriptions
 
@@ -99,26 +99,26 @@ Write for **what the command does**, not how the UI works:
 - **Good:** `Reserve a QA environment.`
 - **Weak:** `Opens the reservation wizard.`
 
-Option and positional `description` strings appear in `-h`, MCP `inputSchema`, and generated skills — keep them concrete (`Environment name (e.g. qa2).`).
+Option and positional `description` strings appear in `-h` and MCP `inputSchema` — keep them concrete (`Environment name (e.g. qa2).`).
 
 Use root **`notes`** for cross-cutting hints shown in help (install commands, docs topics, VPN requirements).
 
 ## Agent-friendly schema
 
-Descriptions and schemas are copied into MCP tools, HTTP OpenAPI, and generated skills — optimize for smaller, clearer agent payloads:
+Descriptions and schemas are copied into MCP tools and HTTP OpenAPI — optimize for smaller, clearer agent payloads:
 
-- **Declare options on the leaf command** that uses them — routing groups cannot declare options (program root may). Wire schemas (MCP, OpenAPI, skills) expose leaf-local options only.
+- **Declare options on the leaf command** that uses them — routing groups cannot declare options (program root may). Wire schemas (MCP, OpenAPI) expose leaf-local options only.
 - Prefer **`kind: "json"`** leaves with schemagen `inputSchema` for complex tool bodies (one nested object beats many flat flags).
 - 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).
+- Repository **`skills/<app>/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).
 
 ## Well-known option names
 
-Prefer **`yes`**, **`dry-run`**, and **`json`** when semantics match. They appear in `-h`, MCP `inputSchema`, and generated skills — write clear option `description` strings (e.g. "Skip confirmation; use for non-interactive runs.").
+Prefer **`yes`**, **`dry-run`**, and **`json`** when semantics match. They appear in `-h` and MCP `inputSchema` — write clear option `description` strings (e.g. "Skip confirmation; use for non-interactive runs.").
 
 ## When to use `mcpTool` (escape hatches only)
 
@@ -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).
 
@@ -542,8 +542,7 @@ await cli.run();
 - **Strict:** unknown keys rejected on load.
 - **CLI:** missing required config exits 1 before the leaf handler (TTY prompt when interactive). Built-in `docs` and `configure get`/`set` skip this exit.
 - **MCP:** server stays up; missing config returns `isError: true` at `tools/call`.
-- **Configure:** interactive `configure` runs the app config wizard; **`configure install`** refreshes agent artifacts to `~/.agents/` (see https://dotagentsprotocol.com). Optional `configure.afterInstall` / `configure.beforeUninstall` for app-specific agent setup; see [configure.md](configure.md).
-- **Agent skill:** `program.skill: { enabled: true }` installs to `~/.agents/skills/<key>/` on `configure install`; see [configure.md](configure.md) and [ai-skills.md](ai-skills.md).
+- **Configure:** interactive `configure` runs the app config wizard; **`configure install`** registers MCP in `~/.agents/mcp.json` (see https://dotagentsprotocol.com). Optional `configure.afterInstall` / `configure.beforeUninstall` for app-specific agent setup; see [configure.md](configure.md).
 - **MCP install:** `mcpServer: { enabled: true }` merges into `~/.agents/mcp.json` on `configure install`; manual Cursor/Claude setup in [mcp.md](mcp.md).
 
 See [config-schema.md](config-schema.md) for codegen, [configure.md](configure.md) (`configure.targets`), and [mcp.md](mcp.md).
@@ -583,7 +582,7 @@ If you maintain argsbarg from a sibling checkout, `just consumers-dev` / `just c
 
 3. **Optional:** add consumer-specific sections above the `<!-- argsbarg:managed -->` marker in `AGENTS.md` (project context, Ink patterns, domain notes).
 
-- **Not this file:** `myapp configure install` writes the **app** skill (`SKILL.md` under `~/.agents/skills/<key>/`) from your command schema — how to *invoke* the CLI. `AGENTS.md` is for *authoring* argsbarg schema.
+- **Not this file:** `skills/<app>/SKILL.md` in your repository is the **app** skill — how to *invoke* the CLI. `AGENTS.md` is for *authoring* argsbarg schema.
 
 ## See also
 
@@ -591,5 +590,5 @@ If you maintain argsbarg from a sibling checkout, `just consumers-dev` / `just c
 - [Output schemas](output-schema.md) — codegen pipeline for leaf `outputSchema`
 - [Developing argsbarg](developing.md) — release, consumer sync, npm `files`
 - [MCP server](mcp.md) — tools, schema resource, env bootstrapping
-- [Agent skills](ai-skills.md) — `configure`
+- [Agent skills](ai-skills.md) — repository skills
 - [Bundled docs](bundled-docs.md) — `docs` topics, consumer docgen vs framework docs

package/docs/configure.md

@@ -2,7 +2,7 @@
 
 > This feature is experimental.
 
-The `configure` built-in manages **agent artifacts** (skills, MCP config, app config). The **binary and shell completions** ship via Homebrew — see [distribution-homebrew.md](distribution-homebrew.md).
+The `configure` built-in manages **agent artifacts** (MCP config, app config). The **binary and shell completions** ship via Homebrew — see [distribution-homebrew.md](distribution-homebrew.md).
 
 Opt out with `configure: { enabled: false }` on the program root.
 
@@ -13,7 +13,7 @@ Private GitHub release downloads require [GitHub CLI](https://cli.github.com/) a
 ```bash
 brew tap <org>/<repo> git@github.com:<org>/<repo>.git
 brew install <tap>/<key>
-<key> configure install   # skills, MCP, config bootstrap; required-config wizard on TTY
+<key> configure install   # MCP, config bootstrap; required-config wizard on TTY
 ```
 
 Upgrade with `brew upgrade <key>`, then run `<key> configure install` again. Shell completions are installed by Homebrew during `brew install`. Users must configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
@@ -34,18 +34,18 @@ just build
 just install-local    # uninstall, build, brew install, configure install (`just install` is an alias)
 ```
 
-`just install-local` runs `configure uninstall` (via `just uninstall`), installs via Homebrew, then `configure install`. Use `just reinstall-local` to swap the binary into Cellar during tight edit cycles; run `just refresh` afterward for skills/MCP.
+`just install-local` runs `configure uninstall` (via `just uninstall`), installs via Homebrew, then `configure install`. Use `just reinstall-local` to swap the binary into Cellar during tight edit cycles; run `just refresh` afterward for MCP.
 
 ## Quick reference
 
 ```bash
-# Install skills/MCP after install or upgrade (required — not run by Homebrew)
+# Install MCP config after install or upgrade (required — not run by Homebrew)
 <key> configure install
 
 # See what is installed
 <key> configure status [--json]
 
-# Remove all agent artifacts and app config (run before brew uninstall)
+# Remove agent artifacts and app config (run before brew uninstall)
 <key> configure uninstall [--yes]
 
 # Read or write app config (when program.appConfig is set)
@@ -61,7 +61,6 @@ Bare `<key> configure` (no subcommand) shows help. Use subcommands above.
 | --- | --- | --- |
 | Binary | skipped (read-only) | Homebrew formula `bin.install` |
 | Shell completions | skipped | Homebrew `generate_completions_from_executable` |
-| Agent skill | automatic | `~/.agents/skills/<key>/` when `program.skill.enabled` |
 | MCP config | automatic | `~/.agents/mcp.json` when `mcpServer.enabled` (see https://dotagentsprotocol.com) |
 | App config | bootstrap + wizard | Creates `~/.local/lib/<key>/config.json` as `{}` when missing; TTY wizard when required keys are missing |
 
@@ -70,7 +69,7 @@ Bare `<key> configure` (no subcommand) shows help. Use subcommands above.
 When **`PATH`** resolves the program key to the **running executable** (e.g. after `brew install`):
 
 - **`configure status`** shows `app: system (PATH)`
-- **`configure install`** refreshes the agent skill (when `program.skill.enabled`) and registers MCP in `~/.agents/mcp.json` (when `mcpServer.enabled`); bootstraps `config.json` when missing
+- **`configure install`** registers MCP in `~/.agents/mcp.json` (when `mcpServer.enabled`); bootstraps `config.json` when missing
 
 MCP config uses the command name on **`PATH`**, not a Cellar path. For Cursor, Claude Code, and Claude Desktop, copy the `mcpServers` entry manually — see [mcp.md](mcp.md) and `docs mcp`.
 
@@ -88,7 +87,6 @@ Optional keys are set via `configure set` or environment variables.
 Optional gates for app binary status:
 
 ```typescript
-skill: { enabled: true },
 mcpServer: { enabled: true },
 configure: {
   targets: {
@@ -142,8 +140,8 @@ Export helpers from `argsbarg`: `resolveAppConfigPath`, `displayAppConfigPath`.
 
 | Subcommand | Description |
 | --- | --- |
-| `install` | Install agent artifacts; bootstrap config; required-config wizard on TTY |
-| `uninstall` | Remove skill, MCP entry, and app config (`--yes` skips TTY confirm) |
+| `install` | Install agent artifacts (MCP); bootstrap config; required-config wizard on TTY |
+| `uninstall` | Remove legacy skill, MCP entry, and app config (`--yes` skips TTY confirm) |
 | `status` | Read-only inventory (`--json` for machine output) |
 | `get` / `set` | Read or write `program.appConfig` keys (when configured) |
 
@@ -159,7 +157,7 @@ If an existing entry matches, install is a no-op. If an existing entry differs,
 
 ## Formula `caveats`
 
-Generated formulae document the two-step install when the app has skills, MCP, or `appConfig` entries. Homebrew prints `caveats` after `brew install` and in `brew info`:
+Generated formulae document the two-step install when the app has MCP or `appConfig` entries. Homebrew prints `caveats` after `brew install` and in `brew info`:
 
 ```ruby
 def caveats

package/docs/output-schema.md

@@ -21,7 +21,6 @@ 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 |
 | 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,8 @@
 
 - `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` — agent skill router (scaffolded from template; customize as needed)
 
 <!-- argsbarg:managed -->
 
@@ -67,6 +68,7 @@ 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`)
+- **Repository skill:** When adding, renaming, or removing commands, update `skills/<key>/SKILL.md` so the intent-based router remains accurate for end-user agents. (`just docgen` updates `./docs/` only and never overwrites `skills/`).
 
 <!-- /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) — scaffolded from template |
 
 ## 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/justfile

@@ -48,7 +48,6 @@ dev *ARGS:
 docgen:
     @just run docs cli-schema --save
     @just run docs cli --save
-    @just run docs skill --save
     @just run docs mcp --save
     @just run docs http --save
     @just run docs openapi --save

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

@@ -4,8 +4,6 @@ name: full-example
 description: Operates the full-example CLI (echo, status). Use when the user mentions full-example, echo, status, or related tasks.
 enabled: true
 ---
-<!-- Generated by full-example docs skill --save; do not edit. -->
-
 
 # full-example
 
@@ -19,18 +17,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/src/program.ts

@@ -21,6 +21,5 @@ export const program = {
   key: createIdentity.key,
   mcpServer: { enabled: true },
   httpServer: { enabled: true },
-  skill: { enabled: true },
   version: "1.0.0",
 } satisfies CliProgram;

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

@@ -8,7 +8,8 @@
 
 - `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` — agent skill router (scaffolded from template; customize as needed)
 
 <!-- argsbarg:managed -->
 
@@ -72,6 +73,7 @@ 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).
+- **Repository skill:** When adding, renaming, or removing commands, update `skills/<key>/SKILL.md` so the intent-based router remains accurate for end-user agents. (`just docgen` updates `./docs/` only and never overwrites `skills/`).
 
 ### 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) — scaffolded from template |
 
 ## 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": {}
               }
             }
           }