diff --git a/.changeset/focused-minimal-skill-guidance.md b/.changeset/focused-minimal-skill-guidance.md new file mode 100644 index 000000000..a9373ff56 --- /dev/null +++ b/.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) diff --git a/examples/audiobook-curator/src/skills/curate-audiobooks/SKILL.md b/examples/audiobook-curator/src/skills/curate-audiobooks/SKILL.md index d857a0e44..fa98f3817 100644 --- a/examples/audiobook-curator/src/skills/curate-audiobooks/SKILL.md +++ b/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 diff --git a/examples/host-test/README.md b/examples/host-test/README.md index 0aa9c1a1b..d27c163c0 100644 --- a/examples/host-test/README.md +++ b/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 diff --git a/examples/host-test/src/skills/host-test/SKILL.md b/examples/host-test/src/skills/host-test/SKILL.md index 35cde9592..ed677c34d 100644 --- a/examples/host-test/src/skills/host-test/SKILL.md +++ b/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. diff --git a/examples/mcp-app/src/skills/service-readiness/SKILL.md b/examples/mcp-app/src/skills/service-readiness/SKILL.md index 8f91a79d7..642112910 100644 --- a/examples/mcp-app/src/skills/service-readiness/SKILL.md +++ b/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 diff --git a/examples/skills-starter/README.md b/examples/skills-starter/README.md index 5463107f5..ca7a105aa 100644 --- a/examples/skills-starter/README.md +++ b/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 diff --git a/examples/skills-starter/src/skills/dependency-upgrade/SKILL.md b/examples/skills-starter/src/skills/dependency-upgrade/SKILL.md index 5f91ab96e..9ac2f9a3b 100644 --- a/examples/skills-starter/src/skills/dependency-upgrade/SKILL.md +++ b/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. diff --git a/examples/skills-starter/src/skills/dependency-upgrade/references/compatibility-checklist.md b/examples/skills-starter/src/skills/dependency-upgrade/references/compatibility-checklist.md index 51ac5226a..01f7f1e09 100644 --- a/examples/skills-starter/src/skills/dependency-upgrade/references/compatibility-checklist.md +++ b/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. diff --git a/examples/skills-starter/src/skills/incident-triage/SKILL.md b/examples/skills-starter/src/skills/incident-triage/SKILL.md index e91f53773..2975111ff 100644 --- a/examples/skills-starter/src/skills/incident-triage/SKILL.md +++ b/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. diff --git a/examples/skills-starter/src/skills/release-review/SKILL.md b/examples/skills-starter/src/skills/release-review/SKILL.md index 085376189..d7d54b0cc 100644 --- a/examples/skills-starter/src/skills/release-review/SKILL.md +++ b/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. diff --git a/packages/agent-bundle/tests/examples-contract.test.ts b/packages/agent-bundle/tests/examples-contract.test.ts index 74de3eec5..6416e0cd5 100644 --- a/packages/agent-bundle/tests/examples-contract.test.ts +++ b/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', diff --git a/packages/create-agent-bundle/templates/minimal/README.md b/packages/create-agent-bundle/templates/minimal/README.md index fd8a67918..ebaccb3a9 100644 --- a/packages/create-agent-bundle/templates/minimal/README.md +++ b/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: diff --git a/packages/create-agent-bundle/templates/minimal/src/skills/getting-started/SKILL.md b/packages/create-agent-bundle/templates/minimal/src/skills/getting-started/SKILL.md index a4ff516ba..bb1cef423 100644 --- a/packages/create-agent-bundle/templates/minimal/src/skills/getting-started/SKILL.md +++ b/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//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.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. diff --git a/packages/create-agent-bundle/templates/minimal/tests/skill.test.ts b/packages/create-agent-bundle/templates/minimal/tests/skill.test.ts index 0e2dc2301..0f09bb709 100644 --- a/packages/create-agent-bundle/templates/minimal/tests/skill.test.ts +++ b/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//skills/'); }); diff --git a/website/docs/en/examples/audiobook-curator.mdx b/website/docs/en/examples/audiobook-curator.mdx index 461295064..e3d0c1fc4 100644 --- a/website/docs/en/examples/audiobook-curator.mdx +++ b/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. diff --git a/website/docs/en/examples/skills-starter.mdx b/website/docs/en/examples/skills-starter.mdx index d60ff8b7c..a8dc9b669 100644 --- a/website/docs/en/examples/skills-starter.mdx +++ b/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`. diff --git a/website/docs/en/guide/authoring/skills.mdx b/website/docs/en/guide/authoring/skills.mdx index 2aeaee840..e58eb3932 100644 --- a/website/docs/en/guide/authoring/skills.mdx +++ b/website/docs/en/guide/authoring/skills.mdx @@ -30,15 +30,10 @@ Skill, copied into the artifact with its relative path preserved. ```md --- 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. @@ -52,6 +47,32 @@ so write it as the condition under which the Skill should be used, not as a titl Links to sibling files are how a Skill points at its own resources. They stay relative in the emitted document, so they resolve inside whichever artifact the host installed. +## Keep instructions focused + +Put a concise capability and a discriminating trigger in `description`; put +only useful shared instructions and real safety or authorization constraints +in the body. A repeated “When to use” section is unnecessary when the +description already gives the boundary. + +Link substantial mode-specific procedures from `references/` and say when to +read them. Do not load every reference at entry or create resource folders for +a short, self-contained Skill. `assets/` holds files used in the output, not +instructions that must always enter context. + +Write the body so the agent matches the user's scope. A plan or review should +not silently become implementation or release. Reuse existing authorization +and current evidence. Complete the relevant preparation before a necessary +approval, and finish with the requested result and its validation or +limitations. Avoid mandatory broad audits, repeated checks, and fixed report +rituals unless the workflow's actual contract requires them. A release-readiness +verdict still requires current candidate checks; a planning task can identify +those checks as remaining work. + +The `create-agent-bundle` minimal template follows this pattern. It inspects +the current Skill tree instead of assuming the scaffold's original +capabilities are unchanged. Apply the same principles to rendered Skills: +review the emitted Markdown, not just the component source. + ## Selecting Skills explicitly Conventional discovery covers `src/skills/*/SKILL.{md,ts,tsx}`. Declare `skills` when you need a @@ -138,7 +159,7 @@ import { Skill } from 'agent-bundle'; export const frontmatter = { 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.', }; export default () => ( @@ -174,7 +195,7 @@ function, or does not export a `frontmatter` record, reports `AB3004`. import { defineSkill } from 'agent-bundle'; export const skill = defineSkill({ - description: 'Reviews release evidence and issues an auditable readiness verdict.', + description: 'Review a release candidate and issue an evidence-based go/no-go verdict.', name: 'release-review', }); ``` diff --git a/website/docs/zh/examples/audiobook-curator.mdx b/website/docs/zh/examples/audiobook-curator.mdx index af7475545..1fad7b39d 100644 --- a/website/docs/zh/examples/audiobook-curator.mdx +++ b/website/docs/zh/examples/audiobook-curator.mdx @@ -119,3 +119,7 @@ pnpm exec agent-bundle mcp run --server curator --target claude 先写入同目录的暂存文件，校验暂存结果，然后原子重命名。JSON 收据拒绝音频后缀，也拒绝与媒体或证据输入 发生冲突。网络响应体、进程输出、目录遍历与并发都是有界的，网络工作使用有界重试加调用方的取消信号， 而不是隐藏的超时。本地媒体进程没有挂钟期限；调用方取消与有界的 stdout、stderr 依旧强制生效。 + +整理 Skill 指示代理只执行请求范围内的操作：单纯盘点或审计不需要转换或版本匹配。需要修改时，先准备 +准确的计划和证据，再请求缺少的批准；只有在输入未变时才复用已有批准。每次修改工具调用仍必须传入 +`apply: true`，同时保留源文件不可变和人工审核版本选择的边界。 diff --git a/website/docs/zh/examples/skills-starter.mdx b/website/docs/zh/examples/skills-starter.mdx index b4559c406..b81af06b3 100644 --- a/website/docs/zh/examples/skills-starter.mdx +++ b/website/docs/zh/examples/skills-starter.mdx @@ -32,7 +32,7 @@ description: 'Skills 起步项目示例：三个按约定发现的工程运维 S | 路径 | 是什么 | | --- | --- | | `src/skills/incident-triage/` | 一次生产事故，从最初信号到止损、证据收集，直到可直接交接的进展更新。 | -| `src/skills/dependency-upgrade/` | 依赖升级规划，包含 API、运行时、灰度与回滚检查。 | +| `src/skills/dependency-upgrade/` | 依赖升级计划、实施或审查，包含 API、运行时、灰度与回滚检查。 | | `src/skills/release-review/` | 一次显式发布评审所需的证据、严重级别、流程与最终报告要求。 | | `src/commands/review-release.md` | 启动发布评审的 Cursor 命令。 | | `src/rules/release-safety.mdc` | 让发布决策保持证据导向的 Cursor 规则。 | @@ -42,6 +42,10 @@ description: 'Skills 起步项目示例：三个按约定发现的工程运维 S 每个 Skill 都链接自己的 `references/` 清单或运行手册，以及一份可复用的 `assets/` 交接或规划模板， 因此 Skill 正文保持简短，长篇材料只在需要时才被加载。 +dependency-upgrade Skill 区分计划、实施与发布就绪，按受影响的范围选择验证，而不是要求计划任务 +运行全部构建或消费者检查。发布就绪仍需当前候选版本的证据，以及规定的回滚和消费者检查；缺少证据 +必须明确报告，不能当作成功。 + ## 在 Workbench 中操作 1. **Application → Skills** 列出 `dependency-upgrade`、`incident-triage` 与 `release-review`。 diff --git a/website/docs/zh/guide/authoring/skills.mdx b/website/docs/zh/guide/authoring/skills.mdx index f8b7ee642..bf68a9c6f 100644 --- a/website/docs/zh/guide/authoring/skills.mdx +++ b/website/docs/zh/guide/authoring/skills.mdx @@ -28,15 +28,10 @@ src/skills/release-review/ ```md --- 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. @@ -50,6 +45,23 @@ frontmatter 是必需的。缺少 frontmatter 的文档报告 `AB3001`；YAML 指向同级文件的链接是 Skill 引用自身资源的方式。它们在输出文档中保持相对形式，因此在宿主安装的任何 产物中都能正确解析。 +## 让指令保持聚焦 + +在 `description` 中简洁说明能力与明确的触发条件；正文只保留有用的共通指引和真实的安全或授权约束。 +如果描述已经说明适用边界，就无需重复一个 “When to use” 小节。 + +把较长的特定模式操作流程放入 `references/`，通过链接说明何时阅读。不要在入口加载所有参考文件， +也不要为简短且自包含的 Skill 创建无用的资源目录。`assets/` 保存用于输出的文件，而不是必须始终 +加载到上下文中的指令。 + +正文应让代理保持用户请求的范围：计划或审查不能悄悄变成实施或发布。复用已有授权与当前有效的证据， +在确需批准前完成相关准备，最后交付所请求的结果及其验证或限制。除非真实工作契约要求，否则不要强制 +进行广泛审计、重复检查或固定的报告仪式。发布就绪判定仍需当前候选版本的检查证据；计划任务可以明确 +列出待完成的检查。 + +`create-agent-bundle` 的 minimal 模板遵循这一模式：它检查当前 Skill 目录，而不是假定脚手架最初的 +能力始终不变。渲染式 Skill 也应遵循相同原则：审查输出的 Markdown，而不仅是组件源码。 + ## 显式选择 Skill 约定发现覆盖 `src/skills/*/SKILL.{md,ts,tsx}`。当你需要不同位置、只取子集，或需要一份字面清单时， @@ -128,7 +140,7 @@ import { Skill } from 'agent-bundle'; export const frontmatter = { 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.', }; export default () => ( @@ -160,7 +172,7 @@ Markdown 链接（`[path](path)`），不是 token。宿主语法在降级阶段 import { defineSkill } from 'agent-bundle'; export const skill = defineSkill({ - description: 'Reviews release evidence and issues an auditable readiness verdict.', + description: 'Review a release candidate and issue an evidence-based go/no-go verdict.', name: 'release-review', }); ```