using-agent-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using Agent Skills

使用Agent Skills

Overview

概述

This repository is a skills library that implements the AI Development Framework V2. Each skill under

skills/

encodes one phase of the pipeline that turns a stakeholder request into a shipped pull request. This meta-skill is the dispatcher: it identifies which framework skill applies to the user's current intent, sequences them when a feature spans multiple phases, and enforces the operating behaviors every skill shares.

Read this skill first when:

The user describes a goal but does not name a skill.
Multiple skills could plausibly apply.
A feature needs to flow end-to-end (PRD → setup → plan → designs → execution).
You are unsure which phase of the framework you are in.

本仓库是一个实现了AI Development Framework V2的技能库。

skills/

下的每个技能都编码了将利益相关者的请求转化为已发布拉取请求的流程中的一个阶段。这个元技能是调度器：它识别哪个框架技能适用于用户当前的意图，当一个功能跨越多个阶段时对它们进行编排，并强制执行所有技能共享的操作行为。

在以下场景下，请首先阅读本技能：

用户描述了目标但未指定具体技能。
多个技能看似都适用。
某个功能需要端到端流转（PRD → 项目初始化 → 开发计划 → 设计 → 执行）。
你不确定自己处于框架的哪个阶段。

Skill Discovery

技能匹配

Map the user's intent to a single skill before doing any other work. Do not begin a phase before confirming the entry point with the user.

Task arrives
    │
    ├── Need to author / refine / audit a PRD for AI agents? ─→ ai-driven-prd
    │     (triggers: "write a PRD", "spec this feature",
    │                "audit my PRD", "is this AI-ready")
    │
    ├── Bootstrapping a repo for Claude Code? ─────────────── → init-claude-project
    │     (triggers: "init Claude here", "set up CLAUDE.md",
    │                "scaffold docs folder", "/init this project")
    │
    ├── Have a PRD requirement (FR-N), need an executable plan? → generate-dev-plan
    │     (triggers: "make a plan for FR-001",
    │                "break this PRD into tasks", "/plan FR-N")
    │
    ├── Have a UI requirement, need designs in docs/designs/? → declarative-design
    │     (triggers: "import designs for FR-001",
    │                "vibe design these screens", "/designs FR-N")
    │
    └── Have a plan at docs/plans/<FR-N>.md, need to ship it? → execute-plan
          (triggers: "execute the plan", "implement FR-001",
                     "ship FR-001", "/execute FR-N")

If no skill matches, the task is likely too small for the framework — bug fixes under ~50 LoC, exploratory questions, single-file refactors. Handle it directly without invoking a skill. The framework is for non-trivial features.

在开展任何工作之前，先将用户意图映射到单个技能。在与用户确认入口点之前，不要开始任何阶段的工作。

任务到来
    │
    ├── 需要为AI Agent编写/优化/审核PRD？ ─→ ai-driven-prd
    │     (触发词: "write a PRD", "spec this feature",
    │                "audit my PRD", "is this AI-ready")
    │
    ├── 为Claude Code初始化仓库？ ─────────────── → init-claude-project
    │     (触发词: "init Claude here", "set up CLAUDE.md",
    │                "scaffold docs folder", "/init this project")
    │
    ├── 已有PRD需求（FR-N），需要可执行计划？ → generate-dev-plan
    │     (触发词: "make a plan for FR-001",
    │                "break this PRD into tasks", "/plan FR-N")
    │
    ├── 已有UI需求，需要在docs/designs/中生成设计？ → declarative-design
    │     (触发词: "import designs for FR-001",
    │                "vibe design these screens", "/designs FR-N")
    │
    └── 已有docs/plans/<FR-N>.md中的计划，需要交付？ → execute-plan
          (触发词: "execute the plan", "implement FR-001",
                     "ship FR-001", "/execute FR-N")

如果没有匹配的技能，该任务可能对于本框架来说太小——比如代码量少于50行的bug修复、探索性问题、单文件重构。无需调用技能，直接处理即可。本框架适用于非 trivial 的功能开发。

Core Operating Behaviors

核心操作行为

These behaviors apply across all five skills. They are non-negotiable. RFC 2119 keywords (MUST / MUST NOT / SHOULD / MAY) carry their normal force.

这些行为适用于所有五个技能，是必须遵守的规则。RFC 2119中的关键词（MUST / MUST NOT / SHOULD / MAY）保持其标准含义。

COB-1 — Ambiguity → ASK

COB-1 — 模糊性 → 询问

Every skill in this library MUST stop and ask the user when an input is ambiguous. Never invent a value to keep moving. The marker

⚠️ NEEDS INPUT: <specific question>

is reserved for unfilled sections in artifacts.

Bad: silently picking one interpretation of a vague requirement and writing 200 lines around it.
Good: "FR-003 says 'fast search' — do you mean p95 < 200ms, or another threshold?"

Omission is read as permission; vague adjectives become hallucinations. Surface uncertainty early.

本库中的每个技能在输入模糊时必须停止并询问用户。绝不能为了推进流程而自行编造内容。标记

⚠️ NEEDS INPUT: <具体问题>

专门用于标记工件中未填充的部分。

错误示例：默默选择模糊需求的一种解释，并基于此编写200行内容。
正确示例："FR-003提到‘快速搜索’——你指的是p95延迟<200ms，还是其他阈值？"

遗漏会被视为默认许可；模糊形容词会导致幻觉内容。尽早暴露不确定性。

COB-2 — No Fuzzy Adjectives

COB-2 — 禁止模糊形容词

The words fast, easy, intuitive, robust, modern, seamless, scalable, clean, optimized MUST trigger an immediate rewrite to a quantified, testable threshold. This applies to PRDs, plans, commit messages, and code comments.

Bad: "Make the dashboard fast."
Good: "FR-007: dashboard initial render p95 ≤ 800ms on a 1000-row dataset."

If the user provides a fuzzy adjective in a request, the skill MUST ask for the threshold before drafting.

fast、easy、intuitive、robust、modern、seamless、scalable、clean、optimized这些词必须触发立即重写，替换为可量化、可测试的阈值。这适用于PRD、计划、提交信息和代码注释。

错误示例："让仪表盘变快。"
正确示例："FR-007：在1000行数据集下，仪表盘初始渲染p95延迟≤800ms。"

如果用户在请求中使用了模糊形容词，技能必须在起草前询问具体阈值。

COB-3 — Number and Cross-Reference Everything

COB-3 — 所有内容编号并交叉引用

Every functional requirement, acceptance criterion, plan task, and test MUST have an ID. The cross-reference chain is canonical: FR-N ↔ AC-N ↔ test name ↔ commit body. A skill that produces an artifact without IDs MUST be rejected and rerun.

Sub-IDs follow the pattern

FR-N.M

for plan tasks (e.g.

FR-001.2

每个功能需求、验收标准、计划任务和测试都必须有ID。交叉引用链是标准化的：FR-N ↔ AC-N ↔ 测试名称 ↔ 提交内容。生成的工件如果没有ID，必须被拒绝并重新执行。

子ID遵循

FR-N.M

格式，用于计划任务（例如

FR-001.2

）。

COB-4 — Stop at Every Phase Boundary

COB-4 — 在每个阶段边界停止

Each skill is divided into numbered phases. Each phase has an INPUT, an OUTPUT artifact, and a HUMAN GATE. The skill MUST present the artifact and ask: approved / refine
<section>
/ restart phase. Phases MUST NOT be chained without explicit approval, even when the user appears to be in a hurry.

The gate is the contract. Skipping it is the most expensive failure mode in this framework.

每个技能都被划分为多个编号阶段。每个阶段都有输入、输出工件和人工审核节点。技能必须展示工件并询问：批准 / 优化
<section>
/ 重启阶段。即使用户看起来很着急，也必须获得明确批准才能进入下一阶段，不能直接链式执行。

审核节点是契约。跳过它是本框架中代价最高的失败模式。

COB-5 — Each Phase Ends Runnable + Tested

COB-5 — 每个阶段结束时必须可运行且已测试

For implementation-side skills (

generate-dev-plan

execute-plan

): every task MUST leave the codebase green — passing tests, passing typecheck, passing lint. Plumbing-only sequences ("add types now, add logic later") are forbidden. If a task cannot end runnable + tested, it MUST be split or merged.

对于实现类技能（

generate-dev-plan

、

execute-plan

）：每个任务完成后，代码库必须保持正常状态——测试通过、类型检查通过、代码规范检查通过。禁止仅做基础准备的序列（"先添加类型，之后再添加逻辑"）。如果一个任务无法在结束时达到可运行且已测试的状态，必须拆分或合并。

COB-6 — DO NOT Lists Are Concrete

COB-6 — 禁止列表必须具体

Every skill in this library has hard rules and anti-patterns. They are concrete forbidden actions, not vibes. When you find yourself wanting to do something the skill forbids, the correct move is to stop and surface the conflict to the user, not to rationalize an exception.

本库中的每个技能都有明确的规则和反模式。它们是具体的禁止行为，而非模糊的感觉。当你发现自己想要做技能禁止的事情时，正确的做法是停止并向用户说明冲突，而非试图合理化例外情况。

COB-7 — Push Back When Warranted

COB-7 — 必要时提出反对

When the user's request collides with a skill's hard rules, name the conflict directly and propose the rule-compliant alternative. Sycophancy is a failure mode. "Of course!" followed by a 200-line plan that batches three requirements is worse than "This skill produces one plan per requirement — splitting FR-001 and FR-002 keeps traceability. OK to split?"

当用户的请求与技能的硬性规则冲突时，直接指出冲突并提出符合规则的替代方案。谄媚是一种失败模式。回答*"当然可以！"然后生成一个包含三个需求的200行计划，不如回答"本技能每个需求生成一个计划——拆分FR-001和FR-002可以保持可追溯性。是否可以拆分？"*

COB-8 — Verify, Don't Assume

COB-8 — 验证，而非假设

A phase is complete only when its checklist (in

references/checklist.md

) passes. "Seems right" is never sufficient. The thresholds are explicit per skill: AI-readiness ≥13/15 (

ai-driven-prd

), init checklist 5/5, dev-plan 7/7, designs 6/6, execution 8/8.

只有当阶段的检查清单（位于

references/checklist.md

）通过时，阶段才算完成。*"看起来没问题"*永远不够。每个技能都有明确的通过阈值：AI就绪度≥13/15（

ai-driven-prd

）、初始化检查清单5/5、开发计划7/7、设计6/6、执行8/8。

Failure Modes to Avoid

需要避免的失败模式

These are the subtle failures that look like productivity but break the framework. Numbered for cross-reference.

ID	Failure mode	Where it bites
FM-1	Inventing a value instead of marking `⚠️ NEEDS INPUT`	All skills
FM-2	Chaining phases without the human gate	All skills
FM-3	Writing fuzzy adjectives into requirements or tasks	`ai-driven-prd` , `generate-dev-plan`
FM-4	Missing or broken FR-N ↔ AC-N ↔ test cross-reference	`ai-driven-prd` , `generate-dev-plan` , `execute-plan`
FM-5	Bundling multiple requirements into one plan or one design file	`generate-dev-plan` , `declarative-design`
FM-6	Plumbing-only tasks that don't end runnable + tested	`generate-dev-plan` , `execute-plan`
FM-7	Marking `[x]` with failing tests or in a separate commit	`execute-plan`
FM-8	Bloated CLAUDE.md (>100 lines, aspirational rules, invented commands)	`init-claude-project`
FM-9	Silent scope creep — fixing adjacent code inside a plan's commits	`execute-plan`
FM-10	Stale designs reused after a PRD change	`declarative-design`
FM-11	Auto-opening a PR instead of producing a description for the user	`execute-plan`
FM-12	Treating a user's "go ahead" on phase N as approval for phase N+1	All skills

这些是看似高效但会破坏框架的隐性失败模式，编号用于交叉引用。

ID	失败模式	影响范围
FM-1	自行编造内容而非标记 `⚠️ NEEDS INPUT`	所有技能
FM-2	未经过人工审核节点就链式执行阶段	所有技能
FM-3	在需求或任务中使用模糊形容词	`ai-driven-prd` , `generate-dev-plan`
FM-4	FR-N ↔ AC-N ↔ 测试的交叉引用缺失或断裂	`ai-driven-prd` , `generate-dev-plan` , `execute-plan`
FM-5	将多个需求打包到一个计划或一个设计文件中	`generate-dev-plan` , `declarative-design`
FM-6	仅做基础准备的任务，结束时无法运行且未测试	`generate-dev-plan` , `execute-plan`
FM-7	测试失败或在单独提交中标记 `[x]`	`execute-plan`
FM-8	CLAUDE.md过于臃肿（超过100行、包含理想化规则、自行发明命令）	`init-claude-project`
FM-9	隐性范围蔓延——在计划的提交中修复无关代码	`execute-plan`
FM-10	PRD变更后仍复用过时的设计	`declarative-design`
FM-11	自动创建PR而非为用户生成描述	`execute-plan`
FM-12	将用户对第N阶段的"继续"视为对第N+1阶段的批准	所有技能

Skill Rules

技能规则

Check the framework before starting non-trivial work. If the task spans more than a single file or could surface ambiguity, identify the entry skill first via the Skill Discovery tree.
Skills are workflows, not suggestions. Follow the phase order in each
```
SKILL.md
```
. Do not skip the human gate, the checklist, or the artifact filename convention.
Multiple skills compose. A full feature flows through
```
ai-driven-prd
```
→ (
```
init-claude-project
```
if first time in this repo) →
```
generate-dev-plan
```
→
```
declarative-design
```
(if UI) →
```
execute-plan
```
. Each skill hands off a named artifact at a known path.
One skill at a time. Do not run
```
generate-dev-plan
```
and
```
execute-plan
```
interleaved. Finish the upstream artifact and clear its gate before invoking the next skill.
When in doubt, start with the PRD. If the task is non-trivial and there is no PRD or an unclear one, begin with
```
ai-driven-prd
```
.

开展非trivial工作前先检查框架。如果任务涉及多个文件或可能存在模糊性，先通过技能匹配树确定入口技能。
技能是工作流，而非建议。遵循每个
```
SKILL.md
```
中的阶段顺序。不要跳过人工审核节点、检查清单或工件命名规范。
多个技能可以组合使用。完整功能的流转路径为
```
ai-driven-prd
```
→（如果是首次在该仓库工作则执行
```
init-claude-project
```
）→
```
generate-dev-plan
```
→
```
declarative-design
```
（如果涉及UI）→
```
execute-plan
```
。每个技能在指定路径交付命名工件。
一次使用一个技能。不要交替运行
```
generate-dev-plan
```
和
```
execute-plan
```
。完成上游工件并通过审核节点后，再调用下一个技能。
不确定时从PRD开始。如果任务是非trivial的，且没有PRD或PRD不清晰，从
```
ai-driven-prd
```
开始。

Lifecycle Sequence

生命周期序列

For a complete feature, the canonical sequence is:

1. ai-driven-prd          → docs/prd/prd-<slug>.md       (FRs, ACs, tasks, ≥13/15)
2. init-claude-project    → CLAUDE.md + docs/ skeleton    (one-time per repo)
3. generate-dev-plan      → docs/plans/<FR-N>.md          (one per requirement)
4. declarative-design     → docs/designs/<FR-N>-<slug>.{html,png}  (UI only)
5. execute-plan           → commits + PR description       (loops one task at a time)

Not every task needs every skill:

Backend-only feature — skip step 4.
Greenfield repo — start at step 2 (init), then 1.
Existing PRD, no plan yet — skip steps 1 and 2; start at step 3.
Plan exists, ready to ship — start at step 5.
Bug fix < 50 LoC — skip the framework; just fix it.

The artifact paths are canonical because the downstream skills rely on them. Do not relocate

docs/prd/

docs/plans/

, or

docs/designs/

without updating every skill that points there.

对于完整功能，标准序列为：

1. ai-driven-prd          → docs/prd/prd-<slug>.md       (功能需求、验收标准、任务，≥13/15)
2. init-claude-project    → CLAUDE.md + docs/ 骨架结构    (每个仓库仅执行一次)
3. generate-dev-plan      → docs/plans/<FR-N>.md          (每个需求对应一个计划)
4. declarative-design     → docs/designs/<FR-N>-<slug>.{html,png}  (仅UI功能)
5. execute-plan           → 提交记录 + PR描述       (逐个任务循环执行)

并非所有任务都需要所有技能：

仅后端功能 — 跳过步骤4。
全新仓库 — 从步骤2（初始化）开始，然后执行步骤1。
已有PRD但无计划 — 跳过步骤1和2；从步骤3开始。
已有计划，准备交付 — 从步骤5开始。
代码量<50行的bug修复 — 跳过框架；直接修复。

工件路径是标准化的，因为下游技能依赖这些路径。不要移动

docs/prd/

、

docs/plans/

或

docs/designs/

，除非更新所有指向这些路径的技能。

Quick Reference

快速参考

Phase	Skill	One-line summary	Output artifact	Pass threshold
1	ai-driven-prd	Stakeholder request → AI-readable PRD with ACs and tasks	`docs/prd/prd-<slug>.md`	≥ 13/15
2	init-claude-project	Bootstrap CLAUDE.md and `docs/` from the actual stack	`CLAUDE.md` , `docs/README.md`	5/5
3	generate-dev-plan	One PRD requirement → checkbox plan of vertical slices	`docs/plans/<FR-N>.md`	7/7
4	declarative-design	UI requirement → HTML + PNG pairs traceable to ACs	`docs/designs/<FR-N>-<slug>.{html,png}`	6/6
5	execute-plan	Plan + designs → one-task-per-commit implementation + PR	Commits + PR description	8/8

阶段	技能	一句话总结	输出工件	通过阈值
1	ai-driven-prd	利益相关者请求 → 包含验收标准和任务的AI可读PRD	`docs/prd/prd-<slug>.md`	≥ 13/15
2	init-claude-project	根据实际技术栈初始化CLAUDE.md和 `docs/`	`CLAUDE.md` , `docs/README.md`	5/5
3	generate-dev-plan	单个PRD需求 → 包含垂直切片的复选框式计划	`docs/plans/<FR-N>.md`	7/7
4	declarative-design	UI需求 → 可追溯到验收标准的HTML + PNG文件对	`docs/designs/<FR-N>-<slug>.{html,png}`	6/6
5	execute-plan	计划 + 设计 → 逐个任务提交的实现 + PR描述	提交记录 + PR描述	8/8

What NOT to do

禁止操作

DO NOT invoke a skill without confirming the entry phase. The user's wording often implies a different phase than what they actually have. Ask which artifacts already exist.
DO NOT chain skills automatically. Each skill ends at a human gate; the next skill begins only when the user opens it.
DO NOT translate this skill's rules into a different framework. If the user wants a different process (Superpowers, GSD, plain TDD), say so and stop — do not silently graft this framework onto another.
DO NOT invent a sixth skill on the fly. If the task does not fit any of the five, surface that to the user.
DO NOT bypass
⚠️ NEEDS INPUT
. It exists so the user sees exactly which decision is theirs.

不要在未确认入口阶段的情况下调用技能。用户的表述往往暗示的阶段与实际所处阶段不符。询问用户已有的工件。
不要自动链式调用技能。每个技能在人工审核节点结束；只有当用户确认后，才能开始下一个技能。
不要将本技能的规则转换到其他框架中。如果用户想要不同的流程（Superpowers、GSD、纯TDD），直接说明并停止——不要将本框架悄悄嫁接到其他流程上。
不要临时创建第六个技能。如果任务不适合五个技能中的任何一个，向用户说明这一点。
不要绕过
⚠️ NEEDS INPUT
标记。它的存在是为了让用户明确知道哪些决策需要他们做出。

References

参考资料

Source framework: ../../docs/framework.md
Authoring conventions for this library: ../../CLAUDE.md
Skill SKILL.md files: ai-driven-prd, init-claude-project, generate-dev-plan, declarative-design, execute-plan
Anthropic agent-skills overview: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

源框架: ../../docs/framework.md
本库的编写规范: ../../CLAUDE.md
技能SKILL.md文件: ai-driven-prd, init-claude-project, generate-dev-plan, declarative-design, execute-plan
Anthropic agent-skills概述: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview