Matt Pocock skills 使用指南：把 agent 拉回工程纪律

/research/matt-pocock-skills-usage-guide.md

这份文档整理的是 mattpocock/skills 这个仓库的用法。它不是一个“万能开发流程框架”，更像一组给 Claude Code、Codex 等 coding agent 使用的工程工作习惯：先对齐需求，再沉淀领域语言，再按测试和审查推进代码。

我看的版本是仓库 main 分支 commit 8515a080a74dbcf5019a1a78efc24b5fcafb36b8，仓库 README 里对它的定位是 “Skills for Real Engineers”，强调小、可组合、可改造，而不是让某个大流程框架接管整个项目。

它解决的不是“让 agent 更会写代码”，而是让 agent 少跑偏

这个仓库的核心判断很明确：AI 写代码的问题通常不在“模型不会敲代码”，而在下面几件事。

第一，用户和 agent 没有真正对齐。用户以为自己说清楚了，agent 也以为自己理解了，最后做出来的东西和预期完全不同。仓库用 grill-me / grill-with-docs 这种“追问式访谈”来解决这个问题。

第二，项目没有稳定的领域语言。agent 进入一个 codebase 后，会临时猜术语、猜模块边界，结果回答很啰嗦，代码命名也不一致。仓库用 CONTEXT.md 和 ADR 来记录领域语言与关键决策。

第三，反馈环太弱。没有测试、没有复现脚本、没有明确验收，agent 就只能凭感觉改。仓库用 tdd、diagnosing-bugs、code-review 把红绿循环、最小复现、双轴审查固化下来。

第四，agent 会加速代码熵增。写得快并不等于设计好，很多项目会更快变成 ball of mud。仓库用 codebase-design 和 improve-codebase-architecture 把“深模块、接口、seam、locality、leverage”这些设计词汇变成 agent 可执行的检查语言。

安装方式

官方 README 给的最快安装方式是：

npx skills@latest add mattpocock/skills

执行后会让你选择要安装哪些 skills，以及安装到哪些 coding agents。README 特别提醒：一定要选 setup-matt-pocock-skills，因为其他工程类技能依赖它写入的项目配置。

如果只想安装 setup 技能，公开文档里也给了单技能命令：

npx skills add mattpocock/skills --skill=setup-matt-pocock-skills

更新单个 skill：

npx skills update setup-matt-pocock-skills

仓库里还有一个 scripts/link-skills.sh，会把 repo 下的 skills 软链到：

~/.claude/skills
~/.agents/skills

但这个脚本文件自己写明了它是 maintainer/dev-only，不是官方支持的 installer。正常用户优先用 npx skills...，不要把 link-skills.sh 当主安装路径。

第一次使用：必须先在目标 repo 里跑 setup

安装后，进入你真正要开发的项目仓库，先运行：

/setup-matt-pocock-skills

它不是一个静态脚本，而是一个 prompt-driven skill。它会先检查当前 repo，再一步步问你三个决定。

1. Issue tracker 放在哪里

它会判断当前 repo 是否是 GitHub / GitLab，也支持 local markdown 或其他自定义工作流。这个决定会被后续技能读取，因为 triage、to-prd、to-issues 都需要知道“任务应该写到哪里”。

常见选择：

GitHub Issues：使用 gh CLI。
GitLab Issues：使用 glab CLI。
Local markdown：写到 .scratch/<feature>/，适合个人项目或没有远程 issue tracker 的项目。
Other：例如 Jira、Linear，需要你描述工作流。

如果选择 GitHub / GitLab，它还会问是否把外部 PR 当成 request surface。打开后，triage 会把外部 PR 当作“带代码的 issue”一起处理。

2. Triage labels 怎么映射

它内置五个状态角色：

needs-triage：需要维护者评估。
needs-info：等待报告者补充信息。
ready-for-agent：信息足够，可以交给 agent 独立处理。
ready-for-human：需要人类实现或判断。
wontfix：不处理。

注意这里的名字是“角色”，不一定等于你 issue tracker 里的真实 label。setup 的作用就是把这些角色映射到你仓库实际使用的 label，避免 agent 自作主张创建一堆重复标签。

3. Domain docs 放在哪里

它会确认你的项目是单上下文还是多上下文。

单上下文一般是：

CONTEXT.md

多上下文一般是：

CONTEXT-MAP.md
src/ordering/CONTEXT.md
src/billing/CONTEXT.md

CONTEXT.md 在这个体系里不是需求文档，也不是技术实现说明，而是领域词汇表。它记录“这个项目里的 Order、Materialization、Account 到底指什么”，让 agent 后续写代码、写 issue、写 PRD 时使用同一套语言。

setup 完成后，通常会产生这些文件：

docs/agents/issue-tracker.md
docs/agents/triage-labels.md
docs/agents/domain.md

并在 CLAUDE.md 或 AGENTS.md 里加入一个 ## Agent skills 区块，告诉后续 agent 去读这些配置。

两类技能：user-invoked 和 model-invoked

这个仓库把 skills 分成两类。

User-invoked 是必须由用户手动输入的技能，比如：

/grill-with-docs
/to-prd
/to-issues
/triage

它们负责启动流程、做编排、产生外部动作。

Model-invoked 是 agent 可以在合适时机自动调用的技能，也可以被用户直接调用，比如：

/tdd
/diagnosing-bugs
/code-review
/codebase-design
/domain-modeling

它们更像底层纪律：测试纪律、调试纪律、代码设计词汇、审查规则。

一个重要规则：user-invoked skill 可以调用 model-invoked skill，但不要互相调用另一个 user-invoked skill。这样可以避免流程之间互相套娃。

推荐主流程：从想法到交付

如果你要从一个模糊想法开始，仓库推荐的主线大概是：

/setup-matt-pocock-skills
    ↓
/grill-with-docs
    ↓
必要时 /prototype
    ↓
/to-prd
    ↓
/to-issues
    ↓
/implement
    ↓
/tdd + /code-review

第一步：`/grill-with-docs`

当你有一个 codebase，并且想做一个功能或改一个设计，先用：

/grill-with-docs

它会做两件事。

一是像 grill-me 一样追问你，把目标、约束、分支决策问清楚。它要求 agent 一次只问一个问题，能从代码里查到的事实就自己查，真正需要你拍板的决策才问你。

二是把过程中沉淀出来的领域语言写入 CONTEXT.md，把值得记录的架构取舍写成 ADR。这样下一次 agent 进入项目时，不用重新猜你的语言。

适合场景：

“我要做一个新功能，但还没完全想清楚。”
“这个需求容易跑偏，先让 agent 问清楚。”
“我要让 agent 理解这个项目的业务词汇。”

如果没有 codebase，只是想打磨一个想法，就用：

/grill-me

grill-me 不写项目文档，适合纯计划、纯产品想法、非代码问题。

第二步：必要时用 `/prototype`

如果某个设计问题靠对话说不清，可以让 agent 做一个 throwaway prototype：

/prototype

它有两条分支。

如果问题是“这个状态模型/业务逻辑能不能跑通”，它会做一个小型 terminal app，让你交互式推动状态变化。

如果问题是“这个 UI 应该长什么样”，它会做几个完全不同的 UI 变体，放在同一路由下切换。

这里的重点是 throwaway。原型的价值是回答问题，不是留下代码。用完要删除，或者把验证后的决策吸收到正式实现、ADR、issue 或 PRD 里。

第三步：`/to-prd`

当对话已经足够清楚，需要把它整理成 PRD：

/to-prd

这个技能明确说：不要再访谈用户，只综合当前上下文。它会输出一份 PRD，并发布到 setup 配置好的 issue tracker。

PRD 结构包括：

Problem Statement
Solution
User Stories
Implementation Decisions
Testing Decisions
Out of Scope
Further Notes

注意它会要求先确认测试 seam。也就是说，在写 PRD 时就要讨论“这个功能将通过哪个公共接口来验证”，而不是写完实现再补测试。

第四步：`/to-issues`

如果 PRD 很大，就用：

/to-issues

它会把 PRD 拆成独立可领取的 issue。拆分原则不是“先数据库、再 API、再 UI”这种横向切片，而是 vertical slice / tracer bullet：每个 issue 都应该穿过相关层，完成一条窄但完整的用户路径。

例如不推荐：

1. 建表
2. 写 API
3. 写前端

更推荐：

1. 用户能创建一个最小可用的 X
2. 用户能编辑 X 的核心字段
3. 用户能在列表里看到 X 的状态

每个 issue 都要可演示、可验证、尽量独立。

对于“大范围机械重构”，它不强行 vertical slice，而是用 expand-contract：先加新形式，再分批迁移调用点，最后删旧形式。

第五步：`/implement`

实现时用：

/implement

它会基于 PRD 或 issue 开始实现。这个 skill 本身很短，但规定了几个关键动作：

尽量使用 /tdd。
定期跑 typecheck。
定期跑单个测试文件。
最后跑完整测试套件。
完成后调用 /code-review。
最后提交当前分支。

它更像“实现入口”，真正的工程纪律来自下面的 tdd 和 code-review。

关键工程技能怎么用

`/tdd`：只在约定好的 seam 上写测试

/tdd 的核心不是“多写测试”，而是红绿循环。

它要求：

先确认测试 seam。
先写失败测试。
只写足够让测试通过的实现。
一次一个 slice。
不在 red-green 阶段做大重构。

它特别反对三类测试。

第一类是实现耦合测试：测试私有方法、mock 内部协作者、通过数据库旁路验证结果。这种测试会在重构时乱炸。

第二类是 tautological test：断言逻辑和实现逻辑同源，比如 expect(add(a, b)).toBe(a + b)。这种测试永远不会真正反驳代码。

第三类是 horizontal slicing：一口气写一堆想象中的测试，再写实现。它要求每次只做一个垂直 slice，让测试随着真实实现反馈演进。

`/diagnosing-bugs`：没有红色反馈环，就不要猜原因

这个技能对调试很严格。它的第一阶段只有一个目标：构造一个能稳定暴露 bug 的反馈环。

可以是：

失败测试。
curl / HTTP 脚本。
CLI fixture。
Playwright / Puppeteer 脚本。
录制 trace 回放。
最小 harness。
fuzz loop。
git bisect harness。

它的硬门槛是：必须能说出一个已经运行过的命令，并且这个命令能驱动真实 bug 路径、捕获用户描述的具体症状、足够快、足够确定。

没有这个命令，就不要进入“我猜可能是 X”的阶段。这一点很适合约束 agent，因为 agent 最容易一上来就编理论。

后续流程是：

反馈环 → 复现 → 最小化 → 3~5 个可证伪假设 → 针对性插桩 → 修复 → 回归测试 → 清理 debug 日志 → 复盘

`/code-review`：把“代码质量”和“是否符合需求”分开审

/code-review 要求用户给一个 fixed point，例如：

main
HEAD~5
某个 commit SHA
某个 tag

然后用三点 diff：

git diff <fixed-point>...HEAD

它把审查拆成两个轴。

Standards：是否符合仓库已有 coding standards，以及一些 Fowler code smell 基线，例如 duplicated code、feature envy、primitive obsession、shotgun surgery、speculative generality 等。

Spec：是否忠实实现了 issue / PRD / spec，有没有漏需求、做错需求、或额外做了没要求的东西。

这两个轴要分开报告，不能混成一个“总体评价”。因为一段代码可能写得很漂亮但做错需求，也可能实现需求正确但代码设计很差。

`/codebase-design`：统一设计语言

这是很多其他技能背后的词汇表。它要求统一使用这些词：

Module
Interface
Implementation
Depth
Seam
Adapter
Leverage
Locality

它强调 deep module：小 interface 后面藏大量行为。判断一个模块是否值得存在，可以用 deletion test：删掉它之后，复杂性是消失了，还是重新散落到多个调用方？如果只是消失，它可能只是中间人；如果会散落，它就在提供 locality 和 leverage。

这个 skill 的价值不在于提供某个固定架构，而是让 agent 在讨论设计时有稳定词汇，不要每次都用 service、component、boundary、API 这些含混词乱讲。

`/improve-codebase-architecture`：定期扫架构摩擦

这个技能适合在项目稳定推进时定期跑。它会扫描 codebase，寻找 deepening opportunities，也就是哪些浅模块可以变深、哪些 seam 放得不好、哪些逻辑因为缺乏 locality 难测难改。

它会输出一个自包含 HTML 报告，放在系统临时目录，而不是写进 repo。每个候选项会包含：

涉及文件。
当前问题。
建议改法。
对 locality / leverage / testability 的收益。
before / after 图示。
推荐强度。

它不会直接开始改代码，而是先问你想探索哪个候选。选中后再进入 grilling loop。

Issue 工作流怎么用

`/triage`

triage 用来处理别人丢进来的 issue 或外部 PR，不是处理你自己通过 /to-issues 生成的 agent-ready issue。

它会把 issue / PR 放进状态机：

unlabeled → needs-triage → needs-info / ready-for-agent / ready-for-human / wontfix

处理具体 issue 时，它会：

读取 issue / PR 正文、评论、标签、作者和日期。
如果是 PR，还要看 diff。
搜索 codebase，判断需求是否已经实现。
查 .out-of-scope/，判断是否以前被拒绝过。
对 bug 做复现，对 PR 做验证。
如有必要，调用 grilling 和 domain-modeling 补齐需求。
最后更新标签、评论、关闭或写 agent brief。

如果 triage 要往 issue tracker 里发评论，仓库规定评论开头必须带免责声明：

> *This was generated by AI during triage.*

这条很重要，尤其是公开仓库，不要让 AI 评论看起来像人工维护者亲自写的。

`ready-for-agent` 的意义

ready-for-agent 不是“这个任务比较简单”，而是“这个任务已经足够明确，agent 可以 AFK 接手”。一个好的 agent-ready issue 应该包含：

要构建什么。
验收标准。
是否有父 issue。
是否被其他 issue 阻塞。
相关 domain language。
不能依赖用户临场解释的隐藏上下文。

非代码工作流

`/handoff`

当对话太长，或者你想开一个新 session 继续工作，就用：

/handoff

它会把当前对话压成一个 Markdown handoff 文件，保存在系统临时目录，不写进当前 workspace。它要求：

不重复已经在 PRD、issue、ADR、commit、diff 里保存过的内容，只引用路径或 URL。
隐去 API key、密码、个人隐私等敏感信息。
写出 suggested skills，提示下一个 agent 应该调用哪些 skills。

它和 /compact 的区别是：handoff 是开新 session 的桥，compact 是在同一 session 里继续。

`/teach`

teach 把当前目录当作一个长期学习 workspace。它会维护：

MISSION.md
RESOURCES.md
reference/*.html
learning-records/*.md
lessons/*.html
assets/*
NOTES.md

它的教学思想是：先明确学习使命，再找可信资源，然后做短小、可交互、可复习的 HTML lesson。新版 changelog 还强调 reuse-first：写 lesson 前先看 assets/，能复用组件就复用，必要时把新组件沉淀到 assets/。

这适合长期学习某个主题，不适合临时问答。

`/writing-great-skills`

这个 skill 是给写 skills 的人看的。它的核心判断是：skill 的价值不是“写更多提示词”，而是提高随机系统的可预测性。

几个关键词很有用：

user-invoked：只有用户能触发，减少 context load，但增加用户记忆负担。
model-invoked：模型能自动触发，增加 context load，但减少用户操作。
router skill：当 user-invoked 太多时，用一个路由技能帮用户选择。
leading word：用一个强概念锚定行为，例如 tight loop、red、tracer bullet。
no-op：删掉那些不会改变模型行为的废话。
sediment：技能长期堆补丁后留下的沉积层。
negation：不要只写“不要做 X”，尽量写正向目标行为。

如果你想把这套东西迁移到 Hermes skills，这个文件比具体工程技能还值得看。

这个仓库里有哪些主技能

下面只列 README 和 .claude-plugin/plugin.json 中实际作为主包暴露的 promoted skills。仓库里还有 deprecated、misc、personal、in-progress 等目录，不建议普通用户一上来就装或依赖。

Engineering / user-invoked

Skill	什么时候用	产物
`ask-matt`	不知道该走哪个流程	给你路由到合适 skill
`setup-matt-pocock-skills`	每个 repo 第一次使用前	`docs/agents/*.md` + `CLAUDE.md`/`AGENTS.md` 配置块
`grill-with-docs`	有 codebase，要把需求问清楚	对齐后的计划、`CONTEXT.md`、ADR
`to-prd`	对话已经清楚，要沉淀成 PRD	issue tracker 里的 PRD
`to-issues`	PRD 太大，需要拆成 agent 可执行 issue	一组 vertical slice issues
`implement`	根据 PRD / issue 实现	代码、测试、审查、commit
`triage`	处理外部 issue / PR	标签、评论、agent brief
`improve-codebase-architecture`	定期扫架构问题	HTML 架构报告 + 后续 grilling

Engineering / model-invoked

Skill	什么时候用	核心纪律
`tdd`	写功能或修 bug 时需要 test-first	seam 先行，红绿循环，垂直 slice
`diagnosing-bugs`	难 bug、慢、flaky、回归	先构造红色反馈环，再假设
`code-review`	审分支、PR、WIP diff	Standards / Spec 双轴审查
`codebase-design`	设计模块、接口、seam	deep module、locality、leverage
`domain-modeling`	领域词汇和 ADR 需要维护	`CONTEXT.md` 只做 glossary
`prototype`	需要 runnable answer	throwaway logic/UI prototype
`research`	需要读官方资料	后台调研 + cited Markdown

Productivity

Skill	类型	什么时候用
`grill-me`	user-invoked	没有 codebase 的计划打磨
`grilling`	model-invoked	作为 grill-me / grill-with-docs 背后的访谈循环
`handoff`	user-invoked	跨 session 交接上下文
`teach`	user-invoked	多 session 学习某个主题
`writing-great-skills`	user-invoked	写/改 agent skills

几个实际使用配方

配方一：新项目第一次接入

1. 安装 skills：npx skills@latest add mattpocock/skills
2. 进入目标 repo
3. 运行 /setup-matt-pocock-skills
4. 选择 issue tracker
5. 映射 triage labels
6. 确认 domain docs 布局
7. 检查 docs/agents/*.md 和 CLAUDE.md / AGENTS.md
8. 以后从 /ask-matt 或 /grill-with-docs 开始

配方二：一个中等复杂功能

/grill-with-docs
  → 问清目标、边界、术语、决策
/to-prd
  → 生成 PRD，确认测试 seam
/to-issues
  → 拆成 vertical slice issue
新 session + /implement <某个 issue>
  → /tdd 实现
  → /code-review 审查
  → commit

如果功能很小，可以跳过 /to-prd 和 /to-issues，直接在同一个 session 里 /implement。

配方三：修一个难 bug

/diagnosing-bugs
  → 先构造一个能红的反馈环
  → 复现并最小化
  → 列 3~5 个可证伪假设
  → 插桩验证
  → 写 regression test
  → 修复
  → 清理 debug 日志
  → 必要时交给 /improve-codebase-architecture

不要一上来问 agent “你觉得原因是什么”。这个技能就是为了防这种坏习惯。

配方四：维护一个已经变乱的项目

/improve-codebase-architecture
  → 生成临时 HTML 架构报告
  → 选择一个 deepening opportunity
  → 进入 grilling loop
  → 必要时用 /codebase-design 设计 seam/interface
  → 后续再 /to-prd 或 /implement

这个流程不是“自动重构”。它先找候选，再让人选方向，最后再进入实现流程。

配方五：处理开源仓库 issue

/triage
  → 看 unlabeled / needs-triage / needs-info
  → 选一个 issue / PR
  → agent 查上下文、查代码、查 out-of-scope
  → bug 先复现，PR 先验证 diff
  → 决定 needs-info / ready-for-agent / ready-for-human / wontfix

公开评论要带 AI triage 免责声明。

迁移到 Hermes / Codex 使用时要注意什么

这套 skills 是按 Agent Skills / Claude Code 生态写的，仓库里有 .claude-plugin/plugin.json，README 也说安装时选择 coding agents。它不是为 Hermes 原生 skill 系统写的，但很多内容可以迁移。

我不建议把整个仓库无脑软链进 Hermes。原因有三个。

第一，技能里有很多对 Claude Code 工具和 slash command 语义的默认假设，比如 /setup-matt-pocock-skills、子 agent、临时 HTML 打开方式、issue tracker 操作等。Hermes 可以学流程，但工具调用细节不同。

第二，这个仓库的 promoted / non-promoted 边界很重要。misc、personal、in-progress、deprecated 目录下也有 SKILL.md，但 CLAUDE.md 明确说 promoted bucket 才应该进 README 和 plugin。迁移时不要把所有 SKILL.md 都当同等稳定能力。

第三，它的价值主要是工程纪律，不是具体脚本。最值得迁移的是这些模式：

grilling：一次只问一个决策问题，事实自己查，决策问用户。
diagnosing-bugs：没有红色反馈环，不进入猜原因。
tdd：先确认 seam，再红绿循环。
code-review：Standards / Spec 分开审。
codebase-design：统一用 deep module / seam / interface / locality / leverage 讨论设计。
to-issues：按 vertical slice 拆任务，而不是按技术层拆。

如果要移植到 Hermes，建议先移植 4 个：

diagnosing-bugs
tdd
code-review
grilling

这四个最通用，和具体平台耦合少，能直接提高 agent 交付质量。

我看到的一个小不一致

仓库里存在 skills/engineering/resolving-merge-conflicts/SKILL.md 和对应 docs，但当前 top-level README 的 Reference 区和 .claude-plugin/plugin.json 没把它列进主 promoted 列表。CHANGELOG 又提到 1.0.0 添加了这个 skill。

所以实际使用时，我会把它当成“仓库里有、但主安装包是否包含需要确认”的技能。不要在核心流程里默认依赖它，除非你安装后能在 agent 里看到 /resolving-merge-conflicts。

最短建议

如果你只是想把这套东西用起来，不要先研究所有 skill。按这个顺序就够了：

/setup-matt-pocock-skills
/ask-matt
/grill-with-docs
/to-prd
/to-issues
/implement

修 bug 时直接用：

/diagnosing-bugs

写代码时让 agent 走：

/tdd
/code-review

维护代码质量时定期跑：

/improve-codebase-architecture

真正值得学的不是命令名，而是它背后的工作顺序：先对齐，再建语言，再切小，再验证，再审查。agent 能写得快，但这些 skills 的作用是让它写得不那么飘。