1. 应该放在哪一步
- 实现前：工单还存在歧义时。
- PR 前：AI 生成代码需要证据时。
- API 发布前：消费者需要清晰契约时。
- 事故后：团队需要定位规格缺口时。
Spec-First AI 工作流
Agent Skills 与 Spec-First 工作流
一个 skill 就是一个装着 SKILL.md 的文件夹，机制仅此而已。它对规格工作的价值在于加载时机：手工粘贴的规格模板是一个要靠人记住的习惯，而 skill 是 agent 在任务匹配时自己拉进来的指令。本页讲清楚文件里写什么、同名时哪个位置生效，以及在 CLAUDE.md、斜杠命令和子 agent 之间，规格到底该放哪。
使用场景：先结构化，再实现
SKILL.md 里到底写什么
两部分：--- 之间的 YAML frontmatter，以及 skill 激活后 agent 要遵循的 Markdown 指令。有一条规则常被踩到——开头的 --- 必须是文件第一行。上面只要多出任何内容，整个文件（含分隔符）都会被当成正文。
.claude/skills/spec-packet/SKILL.md
---
name: spec-packet
description: 在写任何代码前，把工单变成可评审的规格。当请求提到功能、缺陷或 API 变更，但范围、失败路径或验收证据尚未确定时使用。
allowed-tools: Read Grep Glob
---
先写规格。这一轮不要提出实现方案。
## 必需章节
目标 / 非目标 / 角色 / 行为 / 失败路径 /
验收标准（AC-1..n）/ 每条标准的证据 / 回滚
## 规则
- 空字段一律保留 `{待填写}`，绝不虚构需求。
- 假设写进「待确认问题」，不要当成事实写进正文。
- 验收标准描述行为，永远不写文件名。
填好的退款示例见 [reference.md](reference.md)。
做规格工作时值得知道的字段：
| 字段 | 作用 | 对规格 skill 的意义 |
|---|---|---|
description | 告诉 agent 这个 skill 做什么、什么时候用。自动调用就是据此判断的。 | 整个文件里杠杆最大的一行。写触发条件，不要写功能概述——「当范围或失败路径未定时使用」会被触发，「帮助编写规格」不会。 |
name | 列表里的显示名。个人和项目级 skill 的命令名来自目录名，不是这个字段。 | 改目录名会改命令名，改这个字段不会。 |
when_to_use | 补充的调用上下文，会附加在 description 之后。 | 用来写反面情形：工单已经写清楚了就跳过。 |
allowed-tools | 调用这一轮预先放行的工具，下一条用户消息后失效。 | 草拟型 skill 需要读仓库，不需要写。通常 Read、Grep、Glob 就是全部。 |
disable-model-invocation | 设为 true 后只有人能按名字调用，description 完全不进上下文。 | 任何有副作用的操作都该这么设——会提交、会部署、会建工单的 skill，不应该由模型自行判断时机。 |
paths | 用 glob 限定自动激活的文件范围。 | 把 API 契约 skill 限定在 openapi/**，无关工作时它就不会插话。 |
其中六个字段是可迁移的：name、description、license、compatibility、metadata 和 allowed-tools 属于开放的 Agent Skills 规范，其余是 Claude Code 的扩展。如果这个 skill 要在多个工具之间共享，只用这六个。
skill 放在哪，同名时谁生效
四个位置，覆盖顺序是固定的。第一次遇到「个人 skill 悄悄盖掉了团队约定的项目 skill」时，这张表就有用了。
| 位置 | 路径 | 作用范围 | 优先级 |
|---|---|---|---|
| 企业级 | 受管设置目录 | 组织内所有用户 | 最高 |
| 个人级 | ~/.claude/skills/<name>/SKILL.md | 你的所有项目 | 盖过项目级 |
| 项目级 | .claude/skills/<name>/SKILL.md | 当前仓库 | 盖过插件级 |
| 插件级 | <plugin>/skills/<name>/SKILL.md | 启用该插件的地方 | 最低，命名空间 plugin:skill |
还有两条有实际后果的规则。子项目里的 .claude/skills/ 会以带路径的限定名加载（/apps/web:review），所以 monorepo 可以每个包一份规格 skill 而不冲突。另外 SKILL.md 建议控制在 500 行以内，细节放进同目录的其他文件、由它链接过去，agent 需要时才读。这一条正是 skill 在「参考资料」这件事上胜过长 CLAUDE.md 的原因：那份填好的示例在没人问起之前不占任何上下文。
skill、CLAUDE.md、斜杠命令还是子 agent？
四者都能装规格指令，区别只在于内容什么时候加载、代价是多少——而这恰好是决定规格该放哪的唯一问题。
| 机制 | 加载时机 | 适合放什么 |
|---|---|---|
CLAUDE.md | 每个会话、每一轮 | 对整个仓库都成立的事实：技术栈、提交规范、测试命令。不适合放流程。 |
| Skill | 按需——按名字调用，或 description 匹配时自动加载 | 规格模板、评审清单、工单转规格的流程。所有你本来要粘贴的东西。 |
| 斜杠命令 | 只有人主动敲才加载 | 没有附属材料的单文件短提示。同名时 skill 优先。 |
| 子 agent | 在自己的 fork 上下文里 | 中间产物不想污染主线程的工作，比如大范围评审。skill 也可以用 context: fork 这样跑。 |
由此得到的经验法则：同一段指令你粘贴过两次，它就该是个 skill；如果它是事实而不是流程，那它属于 CLAUDE.md。规模上有一个提醒——skill 列表的预算大约是上下文窗口的百分之一，description 超出后会从最少使用的开始丢弃。三十个随手建的 skill 会拖累你真正依赖的那几个。
实例：让规格模板不再靠复制粘贴
本站的 Claude Code 规格模板是为「开跑前先粘贴」设计的。这套做法有效，直到有人忘了粘。把同样的内容搬进 skill，失效模式就变了：agent 加载它是因为请求匹配，而不是因为有人记得。
.claude/skills/spec-packet/ ├── SKILL.md 流程和规则（保持简短） ├── reference.md 填好的退款示例，按需加载 └── criteria.md 验收标准的写法模式 提交进仓库，于是每个评审者拿到同一套流程， 对流程的修改也会出现在 PR 里。
这样做有三件事要做对。description 要写成触发条件——这个字符串是 skill 和「从来没被用过」之间唯一的屏障。allowed-tools 只给读权限，草拟型 skill 不该动它正在描述的那个仓库。以及把冗长的填充示例放进同目录的独立文件，而不是塞进 SKILL.md：那部分你希望它随时可取，但不希望它整天占着上下文。
不变的是：skill 负责草拟，人负责批准。下面那些边界，无论流程是粘贴进来的还是 frontmatter 带进来的，都同样适用。
它和 Superpowers、SDD 工具的关系
规格 skill 借鉴的是 Superpowers 这类工具里最有价值的纪律：先澄清规格，再计划，再把任务拆成可测试、可评审的工作，并且把人工批准和 AI 输出分开。如果你想比较 OpenSpec、Superpowers 和 GitHub Spec Kit，可以先看 SDD 模式对比，再决定团队真正需要哪些 artifact。
2. 应该给它哪些输入
- 原始工单或 PRD 片段。
- 输出必须遵守的模板字段。
- 已知非目标、依赖方和责任人。
- 涉及契约时，补充 API 或 schema 片段。
3. 哪些输出值得保留
- 带明确待确认问题的规格草稿。
- Given/When/Then 格式的验收标准。
- 包含责任人、影响、缓解措施的风险登记。
- 与发布证据绑定的评审清单。
4. 人工复核边界
- 规格 skill 可以起草，但不能批准范围。
- 它可以提出风险，但责任人仍需接受或驳回。
- 它可以总结契约差异，兼容性仍由工程判断。
- 它可以提出测试思路，失败证据仍应阻断发布。
5. 什么时候不该用
- 产品责任人还没确定时。
- 输入包含密钥、生产令牌或敏感数据时。
- 团队想跳过评审直接批准时。
- 任务足够小，用短清单即可解决时。
6. 采用前测试
连续两周观察三个信号：澄清评论是否减少，验收测试是否更早成形，PR 评审是否少出现意外问题。如果没有改善，先收窄工作流，不要扩大自动化范围。
从工单到可评审规格
好的规格 skill 工作流从一个边界清楚的产物开始，以可被评论的规格结束。输出不应该是一篇漂亮文章，而应该是包含决策、假设、缺失输入和测试点的草稿。
输入： - 工单：“为 workspace 管理员增加批量禁用用户” - 模板：feature-spec.md - 必填章节：目标、非目标、角色、API 行为、审计日志、回滚、验收标准 期望输出： - 标出未决问题的规格草稿 - 8-12 条 Given/When/Then 验收标准 - 权限误用、部分失败、审计缺口的风险登记 - 产品、后端、QA、支持四类评审清单
编辑说明：上面的字段说明依据 Claude Code skills 文档与开放的 Agent Skills 规范，两者都列在「参考资料」中。工作流部分是 Spec Coding 会如何把规格 skill 放进 Spec-First 交付流程——正式采用前，请根据你的团队流程改写。
1. Prompt 边界
- 明确规格 skill 可以使用哪些来源材料。
- 禁止编造需求和隐藏实现选择。
- 要求所有假设进入“待确认问题”。
- 输出必须遵守团队已有评审模板。
2. 可评审输出
- 规格：目标、非目标、决策、API/数据影响。
- 验收标准：主流程、失败流程、边界流程。
- 风险登记：责任人、缓解措施、证据、回滚触发器。
- 问题清单：实现前必须回答的阻塞项。
3. 团队控制点
- 把批准过的 prompt 存到仓库。
- 规格保留 Markdown，避免被工具锁死。
- AI 生成代码必须附 PR 证据。
- 记录每份草稿来自哪个 prompt 版本。
4. 采用判断
只有当规格 skill 改善了评审真正需要的产物时，才值得纳入流程。如果团队只是得到更多文字，而不是更清楚的决策，说明工作流太宽了。先缩小到一个可重复交接点，再衡量评审意见是否变得更具体。
有用的问题不是草稿听起来好不好，而是另一个工程师能不能少问几轮澄清就开始实现。
采用前检查清单
先选一个工作流：工单转规格、API diff 转评审意见、事故转复盘草稿，或验收标准重写。不要第一天就自动化整个交付流程。
两周后应该衡量什么
看规格是否少了澄清评论，QA 是否更早写出测试，AI 生成 PR 是否带证据，评审者是否能在实现前发现遗漏风险。
什么时候应该暂停
当输出开始编造需求、隐藏未决问题、绕过产品或安全评审，或无法追溯到 prompt 与源材料时，应暂停采用。
来源门禁
运行工作流前，先列出 规格 skill 可以使用的来源材料：工单链接、产品说明、现有规格、API schema、错误表或事故时间线。任何不在来源材料里的要求，都应该被标成假设，而不是写成已批准范围。
输出门禁
接受草稿前，检查每个章节是否对应一个评审动作。产品能否批准范围，工程能否检查 API 或数据行为，QA 能否直接写测试，支持团队能否看懂用户可见失败状态。
发布门禁
AI 生成代码上线前，必须把证据接回规格：测试通过、API diff 已评审、迁移回滚已说明、功能开关状态明确，并且有能证明上线后健康的指标或告警。
规格 skill 能替代技术规格吗？
不能。它可以起草和批注规格，但被批准的产物仍需要人工责任人、版本历史和测试证据。
第一个工作流应该选什么？
建议从工单转规格开始。输入清楚、输出可见、评审问题明确，团队能很快判断质量是否真的提升。
怎样避免输出变成通用套话？
要求引用源材料、列出假设、给出具体例子，并对“快速”“稳健”“简单”“顺滑”这类词做二次驳回。
什么时候不应该继续扩大使用范围？
当一个小流程还无法稳定产出可评审结果时，不要继续接入更多系统。先修输入模板、复核规则和证据要求。
团队最容易漏掉什么？
最容易漏掉复核和回滚：谁检查输出，出错时如何恢复，日志是否足够定位问题。这些问题比模型能力本身更影响长期使用。
带着规格边界使用 规格 skill
把规格 skill 和可复用模板、评审清单一起用，才能让 AI 输出贴近团队真正需要批准的决策。
备注：规格 skill 是 Spec Coding 的工作流视角，不构成第三方产品功能承诺。
参考资料
- Claude Code 文档：Skills —— 本页用到的 frontmatter 字段说明、位置优先级顺序，以及与斜杠命令、子 agent、
CLAUDE.md的对比。 - Agent Skills 规范 —— 六个可迁移的 frontmatter 字段，适用于要跨工具使用的 skill。
- AGENTS.md —— 仓库级 agent 指令的同类约定，按目录树就近读取。
- Superpowers —— 上文讨论的、基于 skills 的 spec-first 流水线。
字段名于 2026-09-08 对照上述文档核验。外部文档会变动，依赖具体字段前请回查来源。