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

目标读者：技术负责人、想把团队流程「教给 Agent」的工程师
预计阅读：15～20 分钟
主线：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.md：

pr-ship-checklist/ SKILL.md # 必填：YAML frontmatter + Markdown 指令 references/ # 可选：changelog 模板、测试命令表 scripts/ # 可选：可执行辅助脚本

本文用 mattpocock/skills 的写法纪律，现场做一个「总结 PR / 跑单测 / 生成 changelog」技能，讲清description怎么写才不会被误召回，并对比 anthropics/skills、obra/superpowers。

---

一、为什么说 Skills 成了「事实标准」？

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 需要的是可判定的触发词 + 可验证的完成标准，不是散文。

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 project's 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 摘要**，结构固定为： - **背景 / 动机**（1～2 句） - **改动要点**（3～7 条，对应真实文件路径） - **风险与回滚**（至少 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 查询改为批量接口，降低 N+1」）。 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怎么写才不会被误召回？

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 只保留触发；步骤放 body

4.3 自测召回（2 分钟）

对新 skill，用这些用户话术自测：

用户说	期望
「准备合并，帮我做 ship checklist」	✅ 应激活
「根据 diff 写 PR 说明并更新 changelog」	✅ 应激活
「这个函数怎么优化一下」	❌ 不应激活
「帮我 commit」	❌ 不应激活（除非你故意纳入）
「单测挂了帮我看」	❌ 更该走 debug/TDD skill

不准就改 description，先别改正文。

---

五、三家写法对比：anthropics / mattpocock / obra

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——几乎是「默认总开」的 When：

description:Use when implementing any feature or bugfix,before writing implementation code

obraverification-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 always

5.2 怎么选风格写你的团队 SOP？

你的 SOP 类型	更接近	description 策略
办公/格式/多触发同义词	Anthropic	长 Triggers + Do NOT
小而可组合的工程步骤	Matt	短 What + 精确 When
「绝对不能跳」的质量门禁	Superpowers	When 闸门 + 正文 Iron Law

本文的pr-ship-checklist走Matt 骨架 + Anthropic 式 Do NOT + Superpowers 式证据门禁的混合：
发现层精炼，执行层强制「先跑命令再声称完成」。

---

六、装上并验证「被正确调用」

6.1 安装位置（常见）

Agent	路径
Claude Code	~/.claude/skills/或项目.claude/skills/
Codex / 通用	.agents/skills/
用 skills.sh	npx skills add <owner/repo>

Matt 的集：

npx skills@latestaddmattpocock/skills# Claude Code 插件：/plugin install mattpocock-skills

6.2 调用路径

也可显式调用（若客户端支持/pr-ship-checklist）：适合「用户调用型」技能。Matt 区分：

• User-invoked：编排流程（如/grill-me）
• Model-invoked：任务匹配时自动伸手（如tdd）

pr-ship-checklist两者皆可：合并前口头触发，或/pr-ship-checklist。

6.3 验收清单

• 合并前话术能稳定激活该 skill（看 Agent 是否引用其步骤）
• 日常「改个小函数」不会误激活
• 测试失败时 Agent不会假装 changelog 已完成
• Changelog 条目能对应到真实文件路径

---

七、团队落地：把 Wiki SOP 批量「技能化」

建议优先级：

优先级	SOP 例子	Skill 名灵感
P0	合并前检查	pr-ship-checklist
P0	上线前验证	verification-before-release
P1	事故复盘模板	incident-postmortem
P1	API 评审清单	api-design-review
P2	周报生成	weekly-eng-report

原则（呼应本期主线）：

1. 一个 Skill = 一个可完成的结果，不要「全能工程助手」
2. description 当产品文案打磨，和写应用商店副标题一样认真
3. 证据门禁：能跑命令的，必须跑（学 Superpowers）
4. 可组合：小技能互相调用，而不是一个 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 Spec：https://agentskills.io/specification
• mattpocock/skills：https://github.com/mattpocock/skills
• anthropics/skills：https://github.com/anthropics/skills
• obra/superpowers：https://github.com/obra/superpowers
• Anthropic Skills best practices：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices