把一个团队 SOP 写成 SKILL.md：从 0 到被 Agent 正确调用

目标读者技术负责人、想把团队流程「教给 Agent」的工程师预计阅读1520 分钟主线Skills 正在成为跨 Claude Code / Cursor / Codex 的事实标准agentskills.io关键词SKILL.md、Agent Skills、mattpocock/skills、anthropics/skills、obra/superpowers、description、误召回开篇SOP 躺在 Wiki 里Agent 看不见团队里常见一幕Wiki「PR 合并前必须总结改动 → 跑单测 → 写 changelog」 人「我知道但忙起来就跳」 Agent「我不知道你们有这条规矩」Agent Skills要解决的正是把这段 SOP 从「给人看的文档」变成「Agent 会主动加载的可执行说明书」。标准形态极简一个目录 一个SKILL.mdpr-ship-checklist/ SKILL.md # 必填YAML frontmatter Markdown 指令 references/ # 可选changelog 模板、测试命令表 scripts/ # 可选可执行辅助脚本本文用 mattpocock/skills 的写法纪律现场做一个「总结 PR / 跑单测 / 生成 changelog」技能讲清description怎么写才不会被误召回并对比 anthropics/skills、obra/superpowers。一、为什么说 Skills 成了「事实标准」Progressive Disclosure · 渐进披露① Metadataname description启动时始终加载~100 tokens / skill② InstructionsSKILL.md 正文匹配后才整篇加载建议 500 行③ Resourcesscripts / references按需再读避免上下文膨胀Claude Code、Cursor、Codex、OpenCode 等纷纷支持同一份SKILL.md契约Agent Skills Spec字段必填作用name✅小写连字符≤64与目录名一致description✅≤1024做什么 何时用发现层license/compatibility/metadata/allowed-tools可选许可、环境、工具白名单等关键机制只有description在启动时进系统提示。正文要等 Agent「觉得相关」才会加载。所以——写坏 description 技能永远不被调用或被错误调用。正文再完美也救不了发现层。这正是本期「Skills 成事实标准」的工程含义跨工具可移植的 SOP 封装格式。二、从 SOP 到 Skill先画清「触发边界」团队原始 SOP口语版准备合并 PR 时1用中文总结本次改动2跑相关单测并贴结果3按 Keep a Changelog 更新CHANGELOG.md。Agent 需要的是可判定的触发词 可验证的完成标准不是散文。团队 SOP人读「合并前记得…」模糊、靠自觉散落在 Wiki / 口头→description发现What When关键词PR / 单测changelog / 合并前排除日常改代码→正文执行有序步骤完成标准命令与模板证据先于声称完成Matt Pocock 在writing-for-agents里把description称作context pointer上下文指针指针的措辞决定 Agent 会不会去碰正文而不是正文本身有多好。三、实战写出pr-ship-checklist技能3.1 目录mkdir-p.claude/skills/pr-ship-checklist/references# 或 Cursor: .agents/skills/pr-ship-checklist/3.2 完整SKILL.md可直接复制--- name: pr-ship-checklist description: Summarizes the current PR diff, runs the projects unit tests with evidence, and updates CHANGELOG.md in Keep a Changelog format before merge or PR creation. Use when the user asks to prepare a PR for merge, ship a change, write a PR summary, run unit tests before merging, generate or update a changelog, or says 合并前检查 / ship checklist / ready to merge. Do NOT use for routine coding, exploratory debugging, or writing new features without an intent to open or merge a PR. --- # PR Ship Checklist 把「总结 PR → 跑单测 → 写 changelog」当作一次垂直交付不要跳步。 ## Inputs 向用户确认未知则先问勿臆测 1. **范围**相对哪个 base默认 origin/main 2. **测试命令**仓库标准命令是什么优先读 package.json / pom.xml / Makefile勿发明 3. **Changelog 路径**默认 CHANGELOG.md若仓库另有约定服从仓库。 ## Steps ### 1) 总结 PR完成标准有 diff 证据 1. 运行只读 git 命令收集事实例如 - git status -sb - git log --oneline origin/main..HEAD - git diff --stat origin/main...HEAD 2. 用中文输出 **PR 摘要**结构固定为 - **背景 / 动机**12 句 - **改动要点**37 条对应真实文件路径 - **风险与回滚**至少 1 条无则写「低风险 / 可直接 revert 提交」 3. **禁止**在未查看 diff 的情况下编造文件列表。 ### 2) 跑单测完成标准有命令输出 1. 确定测试命令环境里已有配置则用之否则询问用户。 2. **真正执行**测试命令不要说「应该会过」。 3. 在回复中粘贴 - 完整命令 - exit code - 失败时的关键断言 / 堆栈摘要≤40 行 4. 若失败停止 changelog先报告失败并给出最小修复建议。 ### 3) 生成 / 更新 Changelog完成标准文件已改或给出精确补丁 1. 打开现有 CHANGELOG.md若无文件按 Keep a Changelog 创建。 2. 在 ## [Unreleased] 下按类型追加条目Added / Changed / Fixed / Removed。 3. 每条对应本次 PR 真实改动避免空话「优化性能」→「将 X 查询改为批量接口降低 N1」。 4. 展示最终 changelog 片段供用户确认。 ## Done when 同时满足 - [ ] PR 摘要已基于真实 diff - [ ] 单测已执行且贴出证据或明确失败 - [ ] CHANGELOG.md 已更新或给出可应用的完整 diff ## Out of scope - 代替用户点 GitHub「Create PR」按钮除非用户明确要求并用 gh - 大规模重构、与本次 diff 无关的格式化 - 在测试失败时仍声称「可以合并」3.3 可选references/changelog-template.md## [Unreleased] ### Added - … ### Changed - … ### Fixed - … ### Removed - …正文里用指针引用详见 [changelog-template.md](references/changelog-template.md)——这就是progressive disclosure。四、description怎么写才不会被误召回description What When 可选When NOT❌ 易误召回Helps with git and testing.问题· 太宽「任何 git」都可能命中· 无 WhenAgent 不知何时加载· 无排除日常 commit 也被抢结果该用不用 / 不该用乱用✅ 高精度召回Summarizes PR… Use when…ready to merge / changelog…做法· What三件具体交付物· When触发短语列表· Do NOT显式排除日常编码结果合并前稳定命中4.1 官方与社区共识合并版来自 agentskills.io、Anthropic best practices、Matt 的 pointer 理论规则说明第三人称description 会进系统提示别用「我帮你…」What When先说能力再说触发场景与关键词具体分支每个触发是不同分支别堆同义反复正面表述优先「写一句话摘要」优于长篇「不要写小说」否定词会抢注意力必要时写 Do NOT当误召回成本高时用短排除句Anthropicdocxskill 就是范例别把流程写进 description流程进正文否则 Agent 可能只跟摘要、不读全文Front-load最关键的任务词放前Summarizes the PR…4.2 误召回三宗罪对照改坏例子为什么坏改法Helps with PRs and tests.过宽写清三步交付物 合并前场景Use for all git operations.抢commit/rebase限定 ship / merge / changelog把 20 步 checklist 塞进 description发现层膨胀 跳过正文description 只保留触发步骤放 body4.3 自测召回2 分钟对新 skill用这些用户话术自测用户说期望「准备合并帮我做 ship checklist」✅ 应激活「根据 diff 写 PR 说明并更新 changelog」✅ 应激活「这个函数怎么优化一下」❌ 不应激活「帮我 commit」❌ 不应激活除非你故意纳入「单测挂了帮我看」❌ 更该走 debug/TDD skill不准就改 description先别改正文。五、三家写法对比anthropics / mattpocock / obraanthropics/skills能力型 / 工具型description 很长Triggers include…Do NOT use for…适合宽触发面文档/设计/办公技能mattpocock/skills工程纪律型短 descriptionUse when… 精炼正文强调完成标准适合可组合小技能用户调用 模型调用obra/superpowers方法论 / 铁律型description 偏 WhenIron Law / Red Flags防合理化借口表适合强约束流程TDD / 完成前验证5.1 真实 description 对照Anthropicdocx节选气质——触发面极宽用 Triggers Do NOT 双侧封边description:Use this skill whenever the user wants to create,read,edit,or manipulate Word documents (.docx)… Triggers include:… Do NOT use for PDFs,spreadsheets…Matttdd——短、可组合、When 清晰description:Test-driven development. Use when the user wants to build features or fix bugs test-first,mentions red-green-refactor,or wants integration tests.obratest-driven-development——几乎是「默认总开」的 Whendescription:Use when implementing any feature or bugfix,before writing implementation codeobraverification-before-completion——场景闸门极锋利description:Use when about to claim work is complete,fixed,or passing,before committing or creating PRs-requires running verification commands and confirming output before making any success claims; evidence before assertions always5.2 怎么选风格写你的团队 SOP你的 SOP 类型更接近description 策略办公/格式/多触发同义词Anthropic长 Triggers Do NOT小而可组合的工程步骤Matt短 What 精确 When「绝对不能跳」的质量门禁SuperpowersWhen 闸门 正文 Iron Law本文的pr-ship-checklist走Matt 骨架 Anthropic 式 Do NOT Superpowers 式证据门禁的混合发现层精炼执行层强制「先跑命令再声称完成」。六、装上并验证「被正确调用」6.1 安装位置常见Agent路径Claude Code~/.claude/skills/或项目.claude/skills/Codex / 通用.agents/skills/用 skills.shnpx skills add owner/repoMatt 的集npx skillslatestaddmattpocock/skills# Claude Code 插件/plugin install mattpocock-skills6.2 调用路径用户话语→匹配 description→加载正文→按步执行也可显式调用若客户端支持/pr-ship-checklist适合「用户调用型」技能。Matt 区分User-invoked编排流程如/grill-meModel-invoked任务匹配时自动伸手如tddpr-ship-checklist两者皆可合并前口头触发或/pr-ship-checklist。6.3 验收清单合并前话术能稳定激活该 skill看 Agent 是否引用其步骤日常「改个小函数」不会误激活测试失败时 Agent不会假装 changelog 已完成Changelog 条目能对应到真实文件路径七、团队落地把 Wiki SOP 批量「技能化」建议优先级优先级SOP 例子Skill 名灵感P0合并前检查pr-ship-checklistP0上线前验证verification-before-releaseP1事故复盘模板incident-postmortemP1API 评审清单api-design-reviewP2周报生成weekly-eng-report原则呼应本期主线一个 Skill 一个可完成的结果不要「全能工程助手」description 当产品文案打磨和写应用商店副标题一样认真证据门禁能跑命令的必须跑学 Superpowers可组合小技能互相调用而不是一个 2000 行巨无浓缩总结Skills 可移植的团队 SOP 封装格式事实标准 写好 Skill 的关键路径 1. 把人读 SOP 拆成 What / When / Steps / Done when 2. description 只做发现第三人称 触发词 必要 Do NOT 3. 正文写完成标准与命令证据细节丢 references/ 4. 用话术表测召回先改 description 再改正文 三家气质 Anthropic → 宽触发 Do NOT Matt → 短指针 可组合工程纪律 Superpowers → 铁律 防跳步 今天就做把「总结 PR / 跑单测 / 写 changelog」写成 pr-ship-checklist。参考Agent Skills Spechttps://agentskills.io/specificationmattpocock/skillshttps://github.com/mattpocock/skillsanthropics/skillshttps://github.com/anthropics/skillsobra/superpowershttps://github.com/obra/superpowersAnthropic Skills best practiceshttps://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices