docs(skills): focus public authoring guidance

.changeset/focused-minimal-skill-guidance.md

@@ -0,0 +1,7 @@
+---
+"create-agent-bundle": patch
+---
+
+Rewrite the `create-agent-bundle` minimal template's `getting-started` Skill to
+inspect current plugin Skills, use discriminating descriptions, and load
+references only when needed. (#764)

examples/audiobook-curator/src/skills/curate-audiobooks/SKILL.md

@@ -1,21 +1,23 @@
 ---
 name: curate-audiobooks
-description: Inventories, matches, converts, repairs, and audits audiobooks with immutable sources, explicit mutation, Audible review, and optional acoustic or Whisper evidence.
+description: Inventory, match, convert, repair, or audit an audiobook library while preserving immutable sources and reviewed edition identity.
 ---
 # Curate audiobooks
 
-Use this Skill for complete audiobook-library curation: inventory and source
-selection, Audible edition matching, conversion, metadata/artwork and chapter
-repair, acoustic or transcript evidence, and final integrity audit.
+Use only the operations needed for the requested curation task. An inventory
+or audit does not require conversion, Audible matching, or transcript review.
 
 ## Safety boundary
 
 - Treat every source as immutable. Never rename, delete, overwrite, or use a
   selected source path as a conversion output.
-- Start with `inventory_sources` or `audit_library`, then use `select_sources`.
+- For source selection, start with `inventory_sources` or `audit_library`,
+  then use `select_sources`. A targeted audit can use its known file directly.
 - Treat `convert_audiobook`, `apply_audiobook_metadata`, and
   `apply_audiobook_chapters` as plans unless `apply: true` was explicitly
-  approved for the exact paths and evidence shown to the user.
+  approved for the exact paths and evidence shown to the user. Complete the
+  relevant plan and read-only evidence before requesting a missing approval;
+  reuse existing approval while those paths and evidence remain unchanged.
 - Convert into local scratch or another derived destination. Metadata/chapter
   repair is appropriate only for an explicitly selected derived file.
 - Audible ranking is evidence, never acceptance. Record the user's reviewed
@@ -26,7 +28,10 @@ repair, acoustic or transcript evidence, and final integrity audit.
 - Finish changed media with `audit_audiobook`; request full decode when complete
   decode evidence is wanted.
 
-## Workflow
+## Full curation workflow
+
+For complete curation, use the sequence below. For a focused request, perform
+only its relevant steps while preserving the safety boundary.
 
 1. Inventory the narrowest selected library root and retain probe failures.
 2. Audit gaps, duplicate candidates, and multipart groups; make no deletion

examples/host-test/README.md

@@ -13,6 +13,11 @@ From the repository root, launch the Workbench with:
 pnpm example:host-test
 ```
 
+For a log-only question, the Skill reads existing captures. A requested live probe
+generates only the relevant shell, file-edit, or MCP events; subagents are used
+when testing parent/child lineage. Missing records are reported as missing
+evidence, not proof that the host lacks a capability.
+
 ## What the probe records
 
 Every canonical event family the framework admits has a semantic event route

examples/host-test/src/skills/host-test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: host-test
-description: Probe what this host sends to plugin hooks and MCP servers. Use when asked to run the host-test probe, dump host lineage, or check which conversation, session, or subagent ids a hook or MCP call carries.
+description: Inspect host-test logs or probe hook, MCP, conversation, session, subagent, and lineage data.
 ---
 
 # Host test probe
@@ -9,24 +9,25 @@ This plugin records every hook event the host dispatches to it, plus every
 call to its own MCP servers, into one NDJSON log and a durable state summary.
 Nothing it records is sent anywhere; the log stays on this machine.
 
-## When to use
+## Inspect or probe
 
-- The user asks to "run the host-test probe", "dump the host log", or asks
-  which ids (conversation, session, subagent, tool call) this host exposes.
-- You are a subagent and were asked to prove what the host tells plugins
-  about your parent.
+For a log or identity question, call the `host-test` MCP server's `dump` tool
+and report the relevant observed ids and log path. Existing records may answer
+the question without a live probe. The `dump` call itself is recorded;
+distinguish absent evidence from an unsupported host capability.
 
-## Steps
+For a requested live probe, generate only the evidence needed:
 
-1. Run one shell command (for example `pwd`) so a tool hook fires.
-2. Edit or create a small scratch file so a file-edit hook fires.
-3. Call the `host-test` MCP server's `dump` tool with no arguments.
-4. If a `probe` tool from the `host-test-raw` server is available, call it once
-   with `note` set to your own role (`root` or `subagent`).
-5. If you can spawn a subagent, ask it to do steps 1, 3, and 4 with
-   `note: "subagent"` and to report the `log` path and the ids it saw.
-6. Report the log path and the ids the dump shows, verbatim, without editing
-   the log file.
+- Run a harmless shell command such as `pwd` for tool-hook evidence.
+- Create a small scratch file for file-edit-hook evidence.
+- If `host-test-raw` exposes `probe`, call it with your role (`root` or
+  `subagent`) as the note.
+- For parent/subagent lineage, ask a subagent to run the shell and available
+  probe calls, then dump the resulting records. A log-only request does not
+  require spawning an agent.
+
+Dump the resulting records and report the relevant ids verbatim, without
+editing the log. Do not include unrelated payloads in the response.
 
 Never delete or rewrite the log by hand; the `reset` tool is the only way to
 clear it, and only when the user asks for a fresh probe.

examples/mcp-app/src/skills/service-readiness/SKILL.md

@@ -1,14 +1,9 @@
 ---
 name: service-readiness
-description: Reviews service health evidence and records an auditable readiness decision.
+description: Assess service health evidence for a release, incident decision, or operational handoff.
 ---
 # Service readiness
 
-## When to use
-
-Use this Skill when a release, incident decision, or service handoff needs a
-clear health verdict backed by named checks and current evidence.
-
 ## Required resources
 
 - Apply [the service status policy](references/status-policy.md) before

examples/skills-starter/README.md

@@ -18,8 +18,8 @@ required. Both eval suites are deterministic and read only checked-in fixtures.
   [`docs/framework-mode.md`](../../docs/framework-mode.md).
 - `src/skills/incident-triage/SKILL.md` guides a production incident from first
   signal through containment, evidence collection, and a handoff-ready update.
-- `src/skills/dependency-upgrade/SKILL.md` plans dependency upgrades with API,
-  runtime, rollout, and rollback checks.
+- `src/skills/dependency-upgrade/SKILL.md` plans, implements, or reviews
+  dependency upgrades with API, runtime, rollout, and rollback checks.
 - `src/skills/release-review/SKILL.md` defines the evidence, severity, workflow,
   and final-report requirements for an explicit release review.
 - Each Skill links its own `references/` checklist or runbook and reusable

examples/skills-starter/src/skills/dependency-upgrade/SKILL.md

@@ -1,18 +1,17 @@
 ---
 name: dependency-upgrade
-description: Plans and verifies dependency upgrades with compatibility, rollout, and rollback evidence.
+description: Plan, implement, or review a dependency upgrade that may change APIs, runtime support, generated output, or operational behavior.
 ---
 # Dependency upgrade
 
-## When to use
+Match the user's scope: a plan or compatibility review does not authorize
+implementation, rollout, or publication. For implementation, complete the
+requested upgrade and relevant validation before reporting it done.
 
-Use this Skill for a library, runtime, toolchain, or platform upgrade that can
-change public APIs, generated output, operational behavior, or support policy.
-
-## Required resources
-
-- Apply [the compatibility checklist](references/compatibility-checklist.md).
-- Write the proposal with [the upgrade plan template](assets/upgrade-plan.md).
+Use [the compatibility checklist](references/compatibility-checklist.md) to
+select checks for affected surfaces. For a proposal or rollout handoff, use
+[the upgrade plan template](assets/upgrade-plan.md); mark unavailable evidence
+explicitly rather than inventing a result or owner.
 
 ## Workflow
 
@@ -22,12 +21,15 @@ change public APIs, generated output, operational behavior, or support policy.
    changes, peer requirements, and known regressions that intersect this repo.
 3. Map affected imports, configuration, generated artifacts, consumers, and
    CI/release surfaces before editing.
-4. Implement the smallest coherent increment and run focused contract tests,
-   type checks, production builds, and packed-consumer checks.
-5. Define rollout signals and a tested rollback path. Do not call the upgrade
-   complete until shipped output and a real consumer both pass.
+4. When implementation is requested, make the smallest coherent change and run
+   checks that exercise its affected behavior. Include builds or packed-consumer
+   checks when emitted or published output is affected.
+5. For release readiness, record rollout signals, rollback evidence, and real
+   consumer verification. A planning task can finish with a concrete plan and
+   clearly identified validation still needed before rollout.
 
 ## Final answer
 
 State the compatibility decision, changed surfaces, evidence run, remaining
-risk, rollout signal, and exact rollback trigger.
+risk, rollout signal, and exact rollback trigger. Mark any item not yet
+available for the requested scope.

examples/skills-starter/src/skills/dependency-upgrade/references/compatibility-checklist.md

@@ -1,9 +1,13 @@
 # Compatibility checklist
 
+Check the surfaces the upgrade affects. Reuse current evidence tied to the
+candidate; identify absent release evidence without blocking a planning task.
+
 - Runtime and package-manager support matrix is explicit.
 - Direct, peer, optional, and transitive dependency effects are understood.
 - Configuration defaults and removed/deprecated APIs are accounted for.
 - Generated files and package exports remain deterministic.
-- Type checks, focused tests, production builds, and packed consumers pass.
+- Relevant type checks and focused tests pass; verify builds and packed
+  consumers when the upgrade affects emitted or published output.
 - CI caches, lockfiles, SBOM, license, and provenance checks remain valid.
 - Rollout ownership, telemetry, and rollback conditions are documented.

examples/skills-starter/src/skills/incident-triage/SKILL.md

@@ -1,14 +1,9 @@
 ---
 name: incident-triage
-description: Triages production incidents with evidence-first containment and a clear operational handoff.
+description: Triage a suspected active production incident and prepare evidence-based containment and handoff.
 ---
 # Incident triage
 
-## When to use
-
-Use this Skill when an alert, customer report, or operator observation suggests
-an active production incident and the team needs a fast, auditable first pass.
-
 ## Required resources
 
 - Follow [the triage runbook](references/triage-runbook.md) for the first 30 minutes.

examples/skills-starter/src/skills/release-review/SKILL.md

@@ -1,14 +1,9 @@
 ---
 name: release-review
-description: Reviews release evidence and issues an auditable readiness verdict.
+description: Review a release candidate and issue an evidence-based go/no-go verdict.
 ---
 # Release review
 
-## When to use
-
-Use this Skill when a release candidate needs a go/no-go verdict supported by
-checked, reproducible evidence.
-
 ## Required resources
 
 - Read [the release checklist](references/checklist.md) to inspect the artifact.

packages/agent-bundle/tests/examples-contract.test.ts

@@ -57,7 +57,7 @@ it('builds the Skills Starter through public Agent Bundle APIs', async () => {
     await expect(readFile(join(output, 'skills', 'release-review', 'SKILL.md'), 'utf8'))
       .resolves.toContain('# Release review');
     await expect(readFile(join(output, 'skills', 'release-review', 'SKILL.md'), 'utf8'))
-      .resolves.toContain('## When to use');
+      .resolves.not.toContain('## When to use');
     await expect(readFile(join(
       output,
       'skills',

packages/create-agent-bundle/templates/minimal/README.md

@@ -22,9 +22,9 @@ npm run check      # validate + build + typecheck + test
 
 ## Tests
 
-`npm test` runs ordinary module tests — here, one test that keeps the
-Skill's frontmatter aligned with its directory — and `npm run check` runs them
-after validate, build, and typecheck.
+`npm test` runs ordinary module tests — here, one test that keeps the Skill's
+frontmatter and host-layout guidance aligned with the template — and
+`npm run check` runs them after validate, build, and typecheck.
 
 A skills-only project compiles no route modules, so the framework's consumer
 harness (`agent-bundle/rstest` + `agent-bundle/test`) has nothing to render:

packages/create-agent-bundle/templates/minimal/src/skills/getting-started/SKILL.md

@@ -1,32 +1,31 @@
 ---
 name: getting-started
-description: Explains what this plugin provides and how to extend it with new Skills.
+description: Explain this plugin’s current Skills or help add a new Skill to its source.
 ---
 # Getting started
 
-## When to use
-
-Use this Skill when someone asks what this plugin can do, or how to add a new
-capability to it.
-
-## What this plugin provides
-
-This plugin currently ships one Skill — this one. It was scaffolded from the
-`minimal` template of `create-agent-bundle`, which is the smallest complete
-agent-bundle project: one config, one Skill, and a delivery gate.
+Inspect the plugin's current Skills before describing it: use `src/skills/` in
+the source project, the installed `skills/` directory for Claude, Codex, Cursor,
+or portable, and `.amp/plugins/<plugin>/skills/` for Amp. Capabilities may have
+changed since scaffolding. The minimal template starts with this Skill, one
+config, and a delivery check.
 
 ## How to add a Skill
 
 1. Create `src/skills/<skill-id>/SKILL.md` with `name` and `description`
-   frontmatter. The `name` must match the directory name.
-2. Add supporting material under `references/` (read-only context) and
-   `assets/` (files the agent fills in or copies).
+   frontmatter. The `name` must match the directory name; describe the specific
+   task that should activate it, without attracting unrelated requests.
+2. Keep useful shared instructions in `SKILL.md`. Add substantial conditional
+   detail under `references/` only when needed, linking it with a clear read
+   condition. Use `assets/` for templates or files the agent fills in or copies
+   into its deliverable; a short Skill needs neither directory.
 3. Leave `agent-bundle.config.ts` unchanged unless overriding the conventional
    Skill layout.
-4. Run the project's `check` script: it validates the config, builds every
-   host artifact, and runs the tests.
-
-## Final report requirements
-
-When answering with this Skill, name the Skills the plugin currently ships
-and cite the exact files a new Skill needs.
+4. After adding or changing a Skill, run the project's `check` script: it
+   validates the config, builds every host artifact, type-checks, and runs the
+   tests.
+
+Keep the workflow within the request and preserve existing authorization.
+Avoid mandatory plans, audits, or approval pauses for simple informational
+questions. Report the current capabilities or completed edit and validation,
+including any concrete limitation.

packages/create-agent-bundle/templates/minimal/tests/skill.test.ts

@@ -4,11 +4,12 @@ import { expect, it } from '@rstest/core';
 
 const skillPath = new URL('../src/skills/getting-started/SKILL.md', import.meta.url);
 
-it('keeps the getting-started Skill frontmatter aligned with its directory', async () => {
+it('keeps the getting-started Skill aligned with template layouts', async () => {
   const contents = await readFile(skillPath, 'utf8');
   const frontmatter = /^---\n([\s\S]*?)\n---\n/u.exec(contents);
   expect(frontmatter).not.toBeNull();
   expect(frontmatter![1]).toContain('name: getting-started');
   expect(frontmatter![1]).toMatch(/description: \S/u);
   expect(contents).toContain('# Getting started');
+  expect(contents).toContain('.amp/plugins/<plugin>/skills/');
 });

website/docs/en/examples/audiobook-curator.mdx

@@ -143,3 +143,10 @@ audio suffixes and collisions with media or evidence inputs. Network bodies, pro
 traversal, and concurrency are bounded, and network work uses bounded attempts plus the caller's
 cancellation signal rather than hidden deadlines. Local media processes have no wall-clock
 deadline; caller cancellation and bounded stdout and stderr stay enforced.
+
+The curation Skill directs the agent to perform only the requested operations:
+inventory or audit alone does not require conversion or edition matching. For
+a mutation, it prepares the exact plan and evidence before seeking missing
+approval, and reuses approval only while those inputs remain unchanged. Every
+mutating tool call still requires `apply: true`; source immutability and
+human-reviewed edition selection remain intact.

website/docs/en/examples/skills-starter.mdx

@@ -35,7 +35,7 @@ content needs no MCP server, App route, state owner, or executable renderer.
 | Path | What it is |
 | --- | --- |
 | `src/skills/incident-triage/` | A production incident from first signal through containment, evidence collection, and a handoff-ready update. |
-| `src/skills/dependency-upgrade/` | Dependency upgrade planning with API, runtime, rollout, and rollback checks. |
+| `src/skills/dependency-upgrade/` | Dependency upgrade planning, implementation, or review with API, runtime, rollout, and rollback checks. |
 | `src/skills/release-review/` | The evidence, severity, workflow, and final-report requirements for an explicit release review. |
 | `src/commands/review-release.md` | A Cursor command that starts the release review. |
 | `src/rules/release-safety.mdc` | A Cursor rule that keeps release decisions evidence-based. |
@@ -46,6 +46,11 @@ Each Skill links its own `references/` checklist or runbook and a reusable `asse
 planning template, so the Skill body stays short and the long-form material is loaded only when
 it is needed.
 
+The dependency-upgrade Skill distinguishes planning, implementation, and release readiness. It
+selects verification for the affected surfaces instead of requiring every build or consumer
+check for a plan. Release readiness still needs current candidate evidence and the documented
+rollback and consumer checks; missing evidence is reported, not treated as success.
+
 ## Working in the Workbench
 
 1. **Application → Skills** lists `dependency-upgrade`, `incident-triage`, and `release-review`.