目标读者：技术负责人、想把团队流程「教给 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 成了「事实标准」？

Progressive Disclosure · 渐进披露 ① Metadata name + description 启动时始终加载 ~100 tokens / skill ② Instructions SKILL.md 正文 匹配后才整篇加载 建议 < 500 行 ③ Resources scripts / 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 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 怎么写才不会被误召回？

description = What + When +（可选）When NOT ❌ 易误召回 Helps with git and testing. 问题： · 太宽：「任何 git」都可能命中 · 无 When：Agent 不知何时加载 · 无排除：日常 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当误召回成本高时，用短排除句（Anthropic docx skill 就是范例）
别把流程写进 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

anthropics/skills 能力型 / 工具型 description 很长 Triggers include… Do NOT use for… 适合：宽触发面 文档/设计/办公技能 mattpocock/skills 工程纪律型 短 description Use when… 精炼 正文强调完成标准 适合：可组合小技能 用户调用 + 模型调用 obra/superpowers 方法论 / 铁律型 description 偏 When Iron Law / Red Flags 防合理化借口表 适合：强约束流程 TDD / 完成前验证

5.1 真实 description 对照

Anthropic docx（节选气质）——触发面极宽，用 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…"

Matt tdd——短、可组合、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.

obra test-driven-development——几乎是「默认总开」的 When：

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

obra verification-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
「绝对不能跳」的质量门禁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/repo>

Matt 的集：

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

6.2 调用路径

用户话语 → 匹配 description → 加载正文 → 按步执行

也可 显式调用（若客户端支持 /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
P1API 评审清单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
# 人工智能
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

我用 NVIDIA SkillSpector 纯静态扫了一遍 GitHub 最火的 agent skills：能挖出多少注入？0 个

avatar 龙虾开发者社区
cover

周榜换血九成，Agent Skills 星数翻倍

avatar 龙虾开发者社区
cover

智能体从入门到精通：6个必学GitHub开源项目

avatar 龙虾开发者社区