argsbarg 7.0.6 → 7.0.8

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [7.0.8] - 2026-09-15
+
+### Added
+
+- **Non-TTY in-band schema discovery in `--help`** — when `--help` is invoked in non-TTY environments (such as pipes, scripts, and AI agent subprocesses), argsbarg automatically outputs full, untruncated YAML `Output Schema` (and `Input Schema` on `kind: "json"` commands) below command options and arguments. Enables zero-drift contract discovery for AI agents in a single turn without reading external documentation.
+- **Unboxed plain-text help in non-TTY** — strips Unicode box borders, vertical bars, and trailing whitespace padding when output is not a TTY, outputting clean, indented plain text that optimizes token usage and prevents parsing artifacts in automated tooling. TTY sessions retain compact, rounded UTF-8 boxes without schema bloat by default.
+- **`schemaToYamlLines` helper** — exported utility converting JSON Schema definitions (with `$ref` resolution, property JSDoc comments, optional `?` markers, and enums) into clean, human- and agent-readable YAML representation.
+
+## [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
@@ -973,7 +992,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.6...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.0.8...HEAD
+[7.0.8]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.8
+[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

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.
 
@@ -148,7 +148,7 @@ ArgsBarg automatically integrates several core features into your application. T
 
 ### Core Capabilities (Stable)
 
-- `-h` / `--help` — Highly-formatted, terminal-width scoped help at any routing depth.
+- `-h` / `--help` — Highly-formatted, terminal-width scoped help at any routing depth. Rounded UTF-8 boxes in TTY; unboxed plain text with in-band YAML input and output schemas in non-TTY for zero-drift agent discovery.
 - `version` — Print the program's version (e.g., `myapp version`).
 - `http` — Launch the high-performance HTTP REST server (injected when `httpServer.enabled` is `true`).
 - `completion bash` / `zsh` / `fish` — Generate shell completion scripts to stdout for deployment and packaging.
@@ -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 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.
+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,78 +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` + `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
-
-```typescript
-export const program = {
-  key: "myapp",
-  skill: { enabled: true },
-  ...
-} satisfies CliProgram;
-```
-
-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.
-
-The skill directory name is the program `key` with `/`, `\`, and spaces replaced by `_` (e.g. `sqsp-qa`, `full-example`).
-
-## Install via `configure install`
-
-```bash
-myapp configure install
-```
-
-Skills are installed via `configure install` and removed via `configure uninstall` (run `just install-local` / `just uninstall` in dev).
-
-## 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`), 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
-
-Installed files include an HTML comment hint (`Generated by myapp configure; do not edit.`) after skill frontmatter.
-
-## 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>/` |
+## Repository skill (`skills/<app>/SKILL.md`)
 
-```bash
-mkdir -p ~/.claude/skills
-ln -sf ~/.agents/skills/<key> ~/.claude/skills/<key>
-```
+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.
 
-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.
+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.
 
-## MCP vs skills vs docs
+### Structure of `skills/<app>/SKILL.md`
 
-| Mechanism | Role |
-| --- | --- |
-| **`myapp mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
-| **`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) |
+- **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`)
 
-`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).
+## Claude Code plugin
 
-## Repository skill (`skills/<app>/SKILL.md`)
+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`.
 
-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.
+## Uninstalling legacy skills
 
-**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,18 +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 skill --save    # write ./skills/myapp/SKILL.md
+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 |
@@ -76,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).").
 
@@ -92,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` router. Prefer `configure install` for agents (persists `skill.md` + `SKILL.md` to `~/.agents/skills/<key>/`).
 
 ## MCP guide (`docs mcp`)
 
@@ -124,8 +120,7 @@ All `docs` subcommands are hidden from MCP `tools/list` (`mcpTool: { enabled: fa
 
 | Channel | Role |
 | --- | --- |
-| `configure` (skill targets) | Writes intent-based `skill.md` + `SKILL.md` router 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 |
@@ -140,7 +135,7 @@ Load one primary artifact per task — avoid pulling full CLI markdown trees or
 
 | Goal | Load |
 | --- | --- |
-| Route to the right command | `SKILL.md` (via `configure` or `docs skill`) |
+| 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` |
@@ -149,7 +144,7 @@ Load one primary artifact per task — avoid pulling full CLI markdown trees or
 
 ## Save to disk (`--save`)
 
-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.
+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.
 
 | Command | Output |
 | --- | --- |
@@ -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` | `./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.
+> **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.
-- 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).
+- 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)
 
@@ -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,9 +21,9 @@ export const status = {
 | --- | --- |
 | `myapp docs cli-schema` | Full command tree JSON export |
 | `myapp docs cli` | Markdown per-command **Output** section |
-| `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 |
+| CLI `--help` (non-TTY) | YAML output schema for zero-drift in-band agent discovery |
 
 **Not validated at runtime** — argsbarg does not parse or reject handler stdout against the schema today. The schema is documentation and MCP/HTTP metadata.
 

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`, `skills/full-example/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,8 +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`)
-- **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>/`.
+- **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 router** | [../skills/full-example/SKILL.md](../skills/full-example/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/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/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
 

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`, `skills/full-example-json/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,8 +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).
-- **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>/`.
+- **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 router** | [../skills/full-example-json/SKILL.md](../skills/full-example-json/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/justfile

@@ -58,7 +58,6 @@ dev *ARGS:
 docgen: schemagen
     @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-json/skills/full-example-json/SKILL.md

@@ -4,8 +4,6 @@ name: full-example-json
 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. -->
-
 
 # full-example-json
 

package/examples/full-example-json/src/program.ts

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

package/index.d.ts

@@ -533,9 +533,11 @@ export interface CliCompletionConfig {
 	/** When `false`, hide/disable `completion` (default: enabled). */
 	enabled?: boolean;
 }
-/** Opt-in agent skill install to `~/.agents/skills/<key>/` (default: disabled). */
+/**
+ * @deprecated Skill generation was removed; skills are authored directly in repositories under `skills/<app>/SKILL.md`.
+ */
 export interface CliSkillConfig {
-	/** When `true`, install the agent skill via `configure install`. Default false when omitted. */
+	/** @deprecated Skill generation was removed; this property has no effect. */
 	enabled?: boolean;
 }
 /** Context for {@link CliConfigureConfig} lifecycle hooks. */
@@ -807,7 +809,7 @@ export type CliProgram = CliNode & {
 	mcpServer?: CliMcpServerConfig;
 	/** Optional readiness probe for HTTP/MCP `GET /health/readiness` only. */
 	readiness?: (ctx: ReadinessContext) => boolean | Promise<boolean>;
-	/** Opt-in agent skill (`~/.agents/skills/<key>/`). Default disabled when omitted. */
+	/** @deprecated Skill generation was removed; skills are authored directly in repositories under `skills/<app>/SKILL.md`. */
 	skill?: CliSkillConfig;
 	/** Program version (printed by the `version` built-in and MCP serverInfo). */
 	version: string;

package/package.json

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