摘要：
mattpocock/skills不是一套让模型“更聪明”的咒语，而是把需求访谈、领域建模、TDD、任务拆分和代码评审写成可组合的执行协议。本文从安装和调用机制入手，拆解grilling、tdd、implement、code-review四个核心 Skill，并用一个订单取消需求演示它如何把临时对话变成可检查的工程流程。
本文分析基于 2026 年 8 月 20 日拉取的 main 分支，提交为 885e2ca。仓库仍在快速迭代，具体 Skill 名称和流程以后可能变化。
提示词解决不了工程流程问题
给编码 Agent 一段足够长的提示词，确实能改善一次输出。但真实开发的问题通常不在某一段代码怎么写，而在更长的链路上：
- 需求中的分支是否问全了；
- 模型使用的业务术语是否和项目一致；
- 任务有没有小到可以快速验证；
- 测试是在验证行为，还是绑定了实现细节；
- 代码写完后，谁来检查它有没有偏离原始需求；
- 换一个会话后，前面的决策还能不能找回来。
这些问题靠“请认真思考”“请遵循最佳实践”解决不了。它们需要明确的阶段、输入、输出和反馈环。
mattpocock/skills 做的事情，就是把一部分软件工程方法写成 Agent 可以执行的 Markdown 协议。它没有引入新的 Agent 运行时，也没有发明一套复杂 DSL。仓库的主要资产是一组 SKILL.md，外加少量模板、说明文档和平台元数据。
这套设计的重点不是让一个 Skill 包办开发，而是让多个小 Skill 各自负责一种纪律，再由上层 Skill 编排它们。
Skill 到底是什么
一个最小 Skill 可以短到只有几行：
---
name: grill-me
description: A relentless interview to sharpen a plan or design.
disable-model-invocation: true
---
Run a `/grilling` session.
Frontmatter 负责声明身份和调用策略，正文负责告诉 Agent 应该怎样行动。
常见字段包括：
| 字段 | 作用 |
|---|---|
name |
Skill 的稳定名称 |
description |
给人或模型看的触发说明 |
disable-model-invocation |
为 true 时，只允许用户主动调用 |
argument-hint |
提示用户应该传入什么参数 |
Codex 侧还会在 Skill 旁边使用 agents/openai.yaml 保存展示名称、简短说明和隐式调用策略。仓库要求用户触发型 Skill 同时配置 policy.allow_implicit_invocation: false，避免 Claude Code 与 Codex 对同一个 Skill 的调用权限理解不一致。
两种调用类型
仓库用一条很清楚的边界划分所有正式 Skills：
- User-invoked：只能由用户输入名称启动，主要负责流程编排。
- Model-invoked：用户可以调用，模型也可以在符合场景时主动调用，主要承载可复用的工程纪律。
┌─────────────────────┐
│ 用户 │
└──────────┬──────────┘
│
┌─────────────┴─────────────┐
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ User-invoked Skill │ │ Model-invoked Skill │
│ 只能由用户主动触发 │────▶│ 承载可复用工程纪律 │
└─────────────────────┘ └──────────▲──────────┘
│
┌──────────┴──────────┐
│ 模型 │
│ 可按场景自动调用 │
└─────────────────────┘
注意：模型不能隐式启动 User-invoked Skill。
这条边界有两个实际作用。
其一，/implement、/to-spec 这种可能改变项目状态的流程，控制权留在用户手中。其二，tdd、codebase-design 这种底层纪律可以被不同上层流程复用。
仓库还规定：一个 user-invoked Skill 可以调用 model-invoked Skill，但不能调用另一个 user-invoked Skill。也就是说，前置步骤如果必须由用户启动，Skill 只能提醒用户执行，不能偷偷代劳。
25 个正式 Skills 的职责地图
当前正式集合包含 18 个工程类 Skills 和 7 个生产力类 Skills，共 25 个。仓库里还有 in-progress 和 misc 目录，但它们不属于正式发布集合。
用户主动调用
| Skill | 用途 |
|---|---|
ask-matt |
不知道走哪条流程时充当路由器 |
setup-matt-pocock-skills |
配置 Issue Tracker、分诊标签和领域文档布局 |
grill-with-docs |
在仓库中澄清需求，同时维护 CONTEXT.md 和 ADR |
triage |
把外部提交的 Issue 推进到可执行状态 |
improve-codebase-architecture |
扫描代码库中的架构深化机会 |
to-spec |
把已有对话整理成规格，不再重新访谈 |
to-tickets |
把规格拆成带阻塞关系的 tracer-bullet tickets |
implement |
按规格实施，组织 TDD、检查和评审 |
wayfinder |
为跨多个会话的大型工作建立决策地图 |
grill-me |
对非仓库场景进行无状态需求访谈 |
handoff |
生成可移交给其他会话或人员的上下文文档 |
teach |
在目录中建立可持续的学习空间 |
to-questionnaire |
为掌握关键信息的人生成问卷 |
wait-what |
把刚才没讲明白的内容换一种方式解释 |
模型可以主动调用
| Skill | 用途 |
|---|---|
prototype |
用可丢弃原型回答状态或 UI 设计问题 |
diagnosing-bugs |
按复现、最小化、假设、插桩、修复、回归测试诊断疑难 Bug |
research |
基于高可信一手资料生成带引用的研究文档 |
tdd |
约束测试边界并执行逐片的 red-green 循环 |
domain-modeling |
维护领域术语、场景和 ADR |
codebase-design |
提供深模块、接口、seam、adapter 等设计词汇 |
code-review |
分开检查代码标准和规格符合度 |
resolving-merge-conflicts |
根据双方意图逐块解决合并或变基冲突 |
wizard |
为必须由人完成的配置工作生成交互式脚本 |
grilling |
多轮需求访谈的底层原语 |
writing-for-agents |
指导编写 Skill、AGENTS.md 等 Agent 文档 |
这张表适合查找，但不适合拿来当使用顺序。日常开发真正需要记住的是一条主流程。
从想法到交付
┌──────────────┐
│ 想法或需求 │
└──────┬───────┘
▼
┌──────────────────┐
│ grill-with-docs │
│ 澄清需求并记录决策 │
└────────┬─────────┘
▼
┌──────────────────────────┐
│ 需要运行代码才能回答问题？ │
└──────┬─────────────┬─────┘
│ 是 │ 否
▼ │
┌───────────┐ │
│ handoff │ │
└─────┬─────┘ │
▼ │
┌───────────┐ │
│ prototype │ │
└─────┬─────┘ │
▼ │
┌──────────────┐ │
│ handoff 回主线│ │
└──────┬───────┘ │
└───────┬──────┘
▼
┌──────────────────────┐
│ 是否需要多个会话实现？ │
└──────┬─────────┬─────┘
│ 是 │ 否
▼ ▼
┌───────────┐ ┌──────────────┐
│ to-spec │ │ 直接 implement│
└─────┬─────┘ └──────┬───────┘
▼ │
┌────────────┐ │
│ to-tickets │ │
└─────┬──────┘ │
▼ │
┌────────────────┐ │
│ 逐 ticket 实施 │ │
│ implement │ │
└───────┬────────┘ │
└────────┬────┘
▼
┌────────────┐
│ tdd │
│ Red → Green│
└──────┬─────┘
▼
┌─────────────┐
│ code-review │
└──────┬──────┘
▼
┌─────────────┐
│ 提交 │
└─────────────┘
grill-with-docs 负责把需求问清楚，并把稳定术语和难以逆转的决策写进项目文档。如果某个问题仅靠对话无法判断，例如交互手感或复杂状态变化，可以用 prototype 做一次性验证。
小功能可以直接进入 implement。跨多个会话的功能先用 to-spec 固化当前共识，再用 to-tickets 拆成独立任务。每个 ticket 最好在干净上下文中实施，减少前一个任务的细节污染后一个任务。
用“订单取消”走一遍
假设需求只有一句话：
后台增加订单取消功能。
直接让 Agent 开工，通常很快就能得到按钮、接口和几处状态判断。但这里至少藏着这些决策：
- 哪些订单状态允许取消；
- 谁可以取消，客户、客服和管理员权限是否相同；
- 已支付订单是立即退款还是只创建退款申请；
- 库存什么时候返还；
- 部分发货的订单怎么处理；
- 重复请求是否幂等；
- 取消原因和操作人是否进入审计记录。
1. 初始化仓库
安装后，每个项目先运行一次：
/setup-matt-pocock-skills
它会检查当前 Git 远端和仓库文档，然后让用户确认 Issue Tracker、分诊标签、CONTEXT.md 与 ADR 的布局。配置最终写入 docs/agents/，其他工程 Skills 从这里读取约定。
2. 澄清需求
/grill-with-docs 为后台增加订单取消功能
合理的输出不是一份立刻生成的方案，而是几轮有依赖关系的问题。只有“允许取消的订单状态”确定后，才应该继续问各状态下库存和支付怎样处理。
访谈中形成的术语会进入 CONTEXT.md；例如项目最终决定区分“取消订单”和“申请退款”，后续变量名、测试名和规格都应该沿用这套语言。
3. 固化规格并拆任务
/to-spec
/to-tickets
拆票不应按技术层横切成“写 Controller”“写 Service”“写页面”。更合适的是纵向 tracer bullet：
- 未支付订单可取消，并记录审计事件；
- 已支付未发货订单取消后创建退款申请；
- 取消成功后返还预占库存；
- 后台页面展示权限和可取消状态。
每个 ticket 都能从公开入口走到可观察结果，并声明对前置 ticket 的阻塞关系。
4. 实施和评审
/implement <ticket>
implement 会要求先确认适合测试的公开 seam，再用 tdd 一次完成一个纵向切片。完成后运行类型检查、相关单测和全量测试，最后调用 code-review，对照固定基准检查 diff。
四个核心 Skill 的源码设计
grilling：不是问题清单，而是决策树
grilling 的关键概念是 design tree 和 frontier。
Design tree 表示决策之间的依赖关系。Frontier 则是“前置决策已经确定，现在可以提问”的全部节点。每一轮只问当前 frontier，用户回答后重新计算下一轮。
可以把它简化成：
建立决策树
while 仍有未解决节点:
找到前置条件已确定的全部节点
一轮问完这些节点，并给出推荐答案
等待用户决策
根据答案重算决策树
这比一次列出二十个问题更严谨。比如不知道已支付订单采用“退款”还是“退款申请”时，就不该提前追问退款申请由哪个岗位审批。后一个问题依赖前一个答案，不在当前 frontier。
它还明确区分事实和决策：仓库结构、现有接口、配置文件属于事实，应由 Agent 自己调查；产品取舍属于决策，应交给用户。这个约束能减少一种常见低效对话：模型把自己可以查到的信息重新问给用户。
代价也很直接。对于字段改名、文案调整等低风险修改，完整 grilling 会制造不必要的流程成本。它更适合存在业务分支、跨模块影响或不可逆决策的工作。
tdd：先确认 seam，再写测试
这个仓库的 tdd 重点并不只是“测试先行”，而是测试应该放在哪里。
它把 seam 定义为可通过公开接口观察行为的边界，并要求写测试前先和用户确认 seam。测试私有方法、模拟内部协作者、绕过公开入口直接查数据库，都可能让测试和实现耦合。代码重构后行为没变，测试却碎了一地，这种测试提供的是阻力，不是反馈。
Skill 还列出三个反模式：
- Implementation-coupled：断言内部调用或私有实现；
- Tautological：测试用与实现相同的计算方式生成期望值，因此几乎不可能失败；
- Horizontal slicing：先批量写完所有测试，再批量实现，导致测试验证的是想象中的结构。
它推荐一次只做一个垂直切片：
一个 seam
→ 一个失败测试
→ 最少实现使其通过
→ 根据刚学到的信息进入下一片
还有一个容易被忽略的细节：README 用“red-green-refactor”描述 TDD，但当前 tdd/SKILL.md 明确规定重构不属于实现循环，而放到 code-review 阶段。也就是说，这个仓库实际执行的是受约束的 red-green，再集中评审和重构。是否认同这种调整可以讨论，但它至少把 Agent 容易在绿灯后顺手扩大改动的问题显式压住了。
implement：薄编排层
implement/SKILL.md 只有十几行。它没有重复解释怎样写测试、怎样评审，而是规定执行顺序：
读取 spec 或 tickets
→ 在预先确认的 seams 上使用 tdd
→ 经常运行类型检查和单文件测试
→ 最后运行完整测试集
→ 调用 code-review
→ 提交当前分支
这是值得借鉴的 Skill 设计：编排器只描述阶段和交接条件，底层纪律放在独立 Skill 中。否则 implement、diagnosing-bugs 和其他流程会各自复制一份测试规则，规则迟早漂移。
不过“最后提交”也意味着它不是一个适合模型随时自动触发的能力，所以该 Skill 设置了 disable-model-invocation: true。状态改变较大的动作由用户启动，是调用模型设计和权限设计相互配合的例子。
code-review：不要把两种正确混成一个分数
code-review 把评审拆成两个并行轴：
- Standards：是否遵守仓库的编码规范，以及是否出现典型代码坏味道；
- Spec：是否实现了原始需求，有没有漏项、错项或范围蔓延。
两个轴交给不同子 Agent，并行读取同一份 diff，但使用不同证据。最后并列展示结果，不合并排名。
这样做是为了避免两种“看起来不错”的代码蒙混过关：
- 代码非常整洁，但实现错了需求；
- 需求确实实现了，但破坏了项目规范和结构。
Skill 还要求先固定比较基准：
git diff <fixed-point>...HEAD
git log <fixed-point>..HEAD --oneline
三点 diff 让评审针对当前分支从 merge-base 产生的变化。若基准不存在或 diff 为空，应在启动子 Agent 前失败，而不是让两个评审任务各自猜测。
Standards 轴除了读取 CONTRIBUTING.md 等项目规范，还内置了一组 Fowler 代码坏味道基线，例如 Mysterious Name、Feature Envy、Shotgun Surgery 和 Speculative Generality。但仓库规则优先于这份基线，坏味道也只能作为判断线索，不能伪装成确定违规。
安装与更新
仓库提供两条安装路线，二选一即可。
Claude Code 插件
claude plugins install mattpocock-skills
也可以在会话中执行：
/plugin install mattpocock-skills
插件版安装整套只读内容，由插件机制负责更新，适合希望直接跟随上游的人。
Codex、Cursor 和其他兼容 Agent
npx skills@latest add mattpocock/skills
安装器会让用户选择 Skill 和目标 Agent。需要确保选中 setup-matt-pocock-skills，然后在每个项目中运行一次初始化。
这种方式把 Skill 复制成普通文件，适合希望审阅和修改协议的团队。更新命令是：
npx skills update
不要同时安装 Claude Code 插件版和文件版，否则同名 Skill 会出现两份。
日常怎么选
可以从下面几条开始，不必一次采用完整流程：
仓库内的新需求 → /grill-with-docs
已经讨论清楚 → /to-spec
任务跨多个会话 → /to-tickets
按规格开始实现 → /implement
难以稳定定位的 Bug → /diagnosing-bugs
分支或 PR 需要检查 → /code-review
不知道选哪个 → /ask-matt
如何设计自己的 Skill
照抄仓库里的文案不是最有价值的部分。更值得带回自己项目的是下面几条设计原则。
1. 一个 Skill 只维护一种纪律
tdd 管测试反馈环，code-review 管评审，implement 只负责串联。判断是否应该拆 Skill，可以问：这套规则是否会被两个以上流程复用？如果会，应该有单一来源。
2. 区分用户控制和模型自治
会创建 Issue、实施整项工作或提交代码的流程，通常由用户主动启动。诊断规则、测试规范和设计词汇可以允许模型自动调用。不要只按“常用不常用”决定权限，要看它是否会扩大任务范围或改变外部状态。
3. 把失败条件写在昂贵步骤之前
code-review 在启动两个子 Agent 前验证 fixed point 和 diff；tdd 在写测试前确认 seam。好的 Skill 不只是告诉模型成功路径，还会在成本最低的位置阻止错误路径继续扩散。
4. 用项目文件保存稳定事实
业务词汇、Issue Tracker 规则和架构决策不应该只存在聊天记录中。CONTEXT.md、ADR 和 docs/agents/ 把它们变成后续会话可读取的项目资产。
5. 指令要可观察
“保证代码质量”无法验证；“每个切片先出现失败测试”“最后执行完整测试集”“用三点 diff 对固定基准评审”可以验证。Skill 越接近操作协议，越不依赖模型临场领会抽象口号。
6. 给流程写清退出条件
grilling 以 frontier 为空结束，diagnosing-bugs 要求留下回归测试，code-review 要输出两个独立报告。没有退出条件的 Skill 很容易变成无限分析或过早宣布完成。
成本和适用边界
这套仓库最容易被误用的方式，是把完整流程套在所有修改上。
一个明确的 CSS 间距调整，不需要先建立领域模型、生成规格、拆 ticket 再 TDD。一个跨支付、库存和履约的订单取消需求，如果只靠一句提示词直接实现，则很可能在边界条件上付出更高代价。
还需要看到几个现实限制：
- Skill 本质上仍是文字协议，执行效果依赖模型是否可靠遵守；
- 没有类型检查、测试、浏览器或真实服务反馈时，流程写得再严谨也无法证明代码能运行；
grilling能暴露决策树，但也可能把简单问题问得过重；code-review的双轴隔离能减少偏见，却增加上下文和子 Agent 成本；- 不同 Agent 对隐式调用、Skill 工具和元数据的支持并不完全一致；
- 仓库内置的工程偏好不一定符合每个团队，例如把重构移出 red-green 循环就值得团队自行判断。
因此，更合理的采用方式是选择性引入：先使用 grill-with-docs 改善需求对齐，再引入 tdd 和 code-review 建立反馈闭环。只有工作确实跨多个会话时，再启用 spec、tickets 和 handoff 体系。
结语
mattpocock/skills 最有价值的地方，不是收集了 25 个命令，而是展示了一种编写 Agent 工作流的方式：把传统工程经验压缩成小型、可组合、带前置条件和退出条件的执行协议。
模型能力会继续变化，但需求边界、反馈速度、模块设计和评审证据不会因此失效。与其继续扩充一条无所不包的超级提示词，不如先挑出项目中最常失败的一段流程，把它写成一个能检查、能复用、也能被替换的 Skill。
推荐标签：Agent Skills、Codex、Claude Code、Cursor、TDD、AI 编程、软件工程
封面文案：不是让 Agent 更会写代码，而是让它按工程流程工作
参考资料：
Comments | 0条评论