Matt Pocock Skills 学习笔记
最近系统学习了 Matt Pocock 开源的 mattpocock/skills，并尝试在自己的 AI 编程工作流里落地。这篇笔记记录我的理解、用法和取舍，方便以后回顾。
目录
一、核心结论
在我看来，mattpocock/skills 的价值不在于「又多了一批提示词」，而在于把需求对齐、测试反馈、有纪律的调试、架构治理这些工程基本功，写成 Agent 可以按步骤执行的 Skill（检查清单式工作流）。
项目 slogan 是 Skills For Real Engineers — Straight from my .claude directory. 意思是：来自作者日常 Claude Code 里的真实配置，面向能交付、能维护的工程，而不是一次性 vibe coding。
我目前这样区分几类东西：
- • 普通 prompt：像一句提醒，容易被 Agent 忽略，也难在团队里版本化。
- • Skill：目录 +
SKILL.md（YAML 元数据 + 分步约束），触发后按流程走，还能挂附属文档和脚本。 - • GSD / BMAD / Spec-Kit 一类框架：往往接管整条流程；Matt 这条路是小而可组合，我自己选哪些 skill、保留多少控制权。
一句话总结我的体会：AI 很会猜，Skill 的作用是让它少猜、多确认。
二、Matt Pocock 与这个项目
2.1 作者
Matt Pocock 在 TypeScript 圈很有名：Total TypeScript、前 Vercel Developer Advocate、XState 核心贡献者。这套 skills 本质是他每天写代码时怎么约束 Agent 的开源版，不是理论堆砌。
2.2 项目概况
我学习时（2026 年 5 月）仓库已有约 8 万+ star，MIT 协议，2026 年 2 月前后公开后涨得很快。通过 skills.sh 安装时能看到几十个 skill，安装量最高的包括 grill-me、improve-codebase-architecture、tdd、grill-with-docs、to-prd、diagnose。
仓库在 GitHub 上标成 Shell，实际主体是大量 SKILL.md 和配套 markdown 模板，不是传统意义上的应用代码库。
三、我怎么看 AI 编程
学习这套 skills 之后，我调整了对 AI 编程的默认假设：
我以前的误区 现在的做法──────── ───────────把 AI 当「自动完成任务」 把 AI 当「手很快的新同事」一句话就要一堆代码 先对齐 → 再小步 → 再验证prompt 越长越好 流程 + 检查点 + 验收方式界面好看、一跑就挂（vibe coding） 能验证、能拉回（real engineering）
3.1 AI 是同事，不是神
比如我说「做个登录」，Agent 能马上写出接口、页面、状态管理；但如果没问清：手机号还是邮箱？错误给谁看？要不要兼容老用户？token 里放什么？——写得越快，返工越快。
/grill-me 和 /grill-with-docs 对我就是刹车：省时间不是靠少问问题，而是靠少返工。
3.2 从「下令执行」到「先盘清楚」
我遇到过典型的 vibe coding：界面看着对，一跑 404；让 Agent 修，又冒出别的问题。/tdd、/diagnose、/zoom-out 帮我把习惯改成：咱们先把规则和验收说清楚，再动手。
3.3 工程经验要写出来
什么时候该问需求、什么时候该写测试、什么时候该停下调架构、什么时候不能猜 bug——这些以前靠资深同事口头传。Skills 把它们变成 Agent 可反复执行的步骤。不是让 AI 更聪明，而是让 AI 更守规矩。
四、Skill、Prompt 与流程框架
作者强调 small, easy to adapt, and composable。我打算先挑几个用熟，再按需加，而不是一次全装。
五、仓库结构与安装
5.1 目录分层
skills/├── engineering/ # 我写码时主要用这批├── productivity/ # 通用工作流├── misc/ # 偶尔用├── personal/ # 作者自用，不对外├── in-progress/ # 草稿└── deprecated/ # 废弃
公开推广的只有 engineering、productivity、misc，会出现在顶层 README 和 .claude-plugin/plugin.json 里。
5.2 安装
npx skills@latest add mattpocock/skills
我的步骤：
- 1. 选要装的 skills 和目标 Agent（Cursor、Claude Code 等）。
- 2. 务必勾选
/setup-matt-pocock-skills。 - 3. 在 Agent 里跑一遍
/setup-matt-pocock-skills，把仓库配好。
5.3 setup 会写什么
/setup-matt-pocock-skills 是对话驱动的脚手架（不是无脑脚本），会逐项问我，最后生成：
| | |
|---|
| docs/agents/issue-tracker.md | to-issues |
| docs/agents/triage-labels.md | triage |
| docs/agents/domain.md | tdd、diagnose、improve-codebase-architecture 等 |
还会在 CLAUDE.md 或 AGENTS.md 里加 ## Agent skills 块。Issue 跟踪支持 GitHub（gh）、GitLab（glab）、本地 .scratch/ markdown，或其它（Linear、Jira 等要自己描述工作流）。
5.4 Triage 状态机（我记的版本）
分类：bug | enhancement
状态：
- •
ready-for-agent — 规格够清楚，Agent 可以 AFK 领 - •
ready-for-human — 要人做（判断、外部系统、设计决策等）
每个 issue 一个分类 + 一个状态；label 字符串可以在 setup 里映射成我仓库已有的名字。
六、四大失效模式
作者把 Agent 写码常见问题归纳成四类。我按自己的话整理，并对应到具体 skill：
| | | | |
|---|
| | | | /grill-me |
| | | | /grill-with-docs |
| | | | /tdd |
| | | | /to-prd、/improve-codebase-architecture、/zoom-out |
七、我的工作流
这是我打算在真实项目里用的主路径：
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐│ 想法/需求 │ -> │ grill-* │ -> │ to-prd │ -> │ to-issues ││ │ │ + CONTEXT │ │ │ │ 垂直切片 │└─────────────┘ └──────────────┘ └─────────────┘ └──────────────┘ │ ┌────────────────────────────────────────────────────────────┘ v┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐│ triage │ -> │ tdd / │ -> │ PR + CI │ -> │ improve- ││ │ │ prototype? │ │ │ │ architecture │└─────────────┘ └──────────────┘ └─────────────┘ └──────────────┘ │ │ │ bug └── 卡住用 /diagnose，陌生区用 /zoom-out v /diagnose
分阶段说明：
- 1. 对齐：非 trivial 改动前先
/grill-with-docs（有代码库时）；纯讨论用 /grill-me。 - 2. 规格化：上下文够了再
/to-prd 出 PRD 并落到 issue（不会再采访我一遍）。 - 3. 切片：
/to-issues 拆成垂直切片，标 HITL / AFK 和依赖。 - 4. 分拣：
/triage 推进状态；bug 会先试着复现。 - 5. 实现：
/tdd 坚持「一行为 → 一测试 → 最小实现」；设计不确定时 /prototype 做可删原型。 - 6. 排障：
/diagnose — 没有稳定失败信号就不猜原因。 - 7. 还债：隔几天跑
/improve-codebase-architecture。 - 8. 交接：换会话用
/handoff；想省 token 可以 /caveman。
八、核心 Skill 详解
8.1 对齐类
/grill-me
- • 用来 stress-test 计划，或我说 "grill me"。
- • Agent 一次只问一个问题，并给出推荐答案；能读代码搞清楚的不问我。
/grill-with-docs（我写码时优先用这个）
- • 在追问同时：对照
CONTEXT.md 挑术语冲突；把模糊词收成 canonical term；用场景压边界；和代码对账。 - • 术语定了就当场更新
CONTEXT.md（只写词汇，不写实现）；ADR 只在「难逆转 + 后人会懵 + 真实权衡」时写。 - • 支持单上下文（根目录
CONTEXT.md）和多上下文（CONTEXT-MAP.md）。
我印象很深的一个例子：把「lesson 被 made real」这种冗长说法收成 materialization cascade，后面和 Agent 沟通都省事。
8.2 规格与工单类
/to-prd
- • 先列出要动哪些 module，找 deep module，和我确认测试范围。
- • PRD 含：Problem、Solution、User Stories（要细）、Implementation Decisions、Testing Decisions、Out of Scope、Further Notes。
- • 发到 issue tracker，打
ready-for-agent。
/to-issues
- • 必须垂直切片：schema、API、UI、测试贯通，每片能单独验证。
- • HITL（人要介入）和 AFK（Agent 可独立完成）分开，能 AFK 就 AFK。
- • 先给我看重排列表，确认后再按依赖顺序建 issue。
/triage
- • AI 评论要以
> *This was generated by AI during triage.* 开头。 - • 可以查待办、复现 bug、grill、写 agent brief、改状态。
- •
wontfix 的 enhancement 会记进 .out-of-scope/，避免重复讨论。
8.3 实现与质量类
/tdd（建议精读 SKILL.md）
- • 测对外行为，不测实现细节；好测试像规格，重构不该弄挂它们。
- • 反模式：先写完全部测试再写完全部实现（horizontal slice）——测的是想象，不是真行为。
- • 正模式：vertical slice（tracer bullet）
WRONG: RED: test1..test5 → GREEN: impl1..impl5RIGHT: RED→GREEN: test1→impl1 → test2→impl2 → ...
流程：Planning → 第一个 tracer bullet → 循环 RED/GREEN → 全绿后再 Refactor（RED 时不重构）。
/diagnose
六阶段里，Phase 1 建反馈环最关键——没有确定性 pass/fail，就不要开始猜。
反馈环我会按这个顺序试：失败测试 → curl → CLI+fixture → Playwright → 重放 trace → 最小 harness → fuzz → git bisect → 差分 → 必要时 HITL 脚本。
之后：复现 → 3–5 个可证伪假设 → 单变量插桩 → 先回归测试再修 → 清掉 [DEBUG-xxxx] → 架构债大就转 /improve-codebase-architecture。
没有可重复的失败信号，就不要开始猜原因。
/prototype
- • 逻辑/状态机疑问 → 终端小应用；UI 方向 → 同路由多方案切换。
- • 明显标 PROTOTYPE、一条命令能跑、默认不落库、不写测试；学完就删或把结论写进 ADR/issue。
8.4 架构与认知类
/improve-codebase-architecture
用「模块深度」那套词：Module、Interface、Seam、Deletion test 等。流程是 Explore → 给我 deepening 候选 → 我选一个 → grilling 深化 → 必要时更新 CONTEXT/ADR。
/zoom-out
陌生代码区我会主动用：让 Agent 升一层抽象，用项目领域词画模块和 caller 关系。
8.5 效率与协作类
/caveman
极简回复：去掉废话，技术词和代码保持准确。我试过同类任务 token 能明显下降（具体比例因项目而异）。说 "stop caveman" 才关。安全警告、不可逆操作会暂时恢复完整表述。
/handoff
把会话压成 handoff 文档，只引用已有 PRD/ADR/issue，不重复抄一遍；并建议下个会话用哪些 skill。
8.6 其它（按需）
- •
/git-guardrails-claude-code — 拦截危险 git 操作 - •
/setup-pre-commit — Husky + lint-staged 等 - •
/migrate-to-shoehorn — 测试断言迁移 - •
/scaffold-exercises — 练习目录脚手架 - •
/write-a-skill — 按规范写新 skill
九、CONTEXT.md 与 ADR
9.1 CONTEXT.md 我会怎么写
# {Context Name}{这个 bounded context 是干什么的}## Language**Order**:{定义}_Avoid_: Purchase, transaction## Relationships- An **Order** produces one or more **Invoices**## Example dialogue（一段澄清边界的对话）## Flagged ambiguities（曾经混用的词及最终约定）
我的原则：
- • 定义尽量短；只放本项目特有概念，别把
Promise、timeout 这种通用词塞进去。
9.2 什么时候写 ADR
三个条件同时满足才写：难逆转、没上下文会看不懂、做过真实权衡。否则记在 issue 或对话里就够。
9.3 作者仓库里的示范
mattpocock/skills 自己也维护 CONTEXT，用 Issue tracker、Issue、Triage role 等词，并约定不用 backlog 指工具——说明这套方法是作者自己在用的。
十、端到端示例：文章发布权限
用一个后台场景串一下我理解的三个 skill。
10.1 错误开场
帮我加一个文章发布权限。
Agent 很可能直接改按钮和接口，但业务规则根本没定义。
10.2 先用 grill 问清楚
我会让 Agent 先问：
- • 有没有统一的
canPublishArticle()？
对齐后我期望的规格类似：
只有 editor 和 admin 可发布；前端置灰并提示；权限判断集中在 modules/auth/permissions.ts，页面只调这一处。
10.3 再用 tdd 做第一条切片
// permissions.test.tsit("allows editor to publish", () => { expect(canPublishArticle({ role: "editor" })).toBe(true);});it("blocks viewer", () => { expect(canPublishArticle({ role: "viewer" })).toBe(false);});
// permissions.tsexport function canPublishArticle(user: { role: string }) { return user.role === "editor" || user.role === "admin";}
然后再加 UI、接口等下一个切片——每次只推进一个可验证行为。
10.4 上线后偶发失败用 diagnose
我不会让 Agent 先猜「是不是缓存」。我会先要稳定复现，例如：
npm test -- publishArticle.test.ts
或写最小脚本固定 role、文章状态、接口返回；有失败信号后再排查：权限函数、页面传参、字段不一致、后端二次校验等。
十一、我的入门路径
不要一次装全。 我打算按三个阶段练：
| | |
|---|
| /grill-me | 只追问不写码；记下 Agent 问了哪些我没想到的 |
| /tdd | |
| /diagnose | |
熟练后再加：/grill-with-docs（长期项目）、/to-prd + /to-issues（协作）、/improve-codebase-architecture（定期还债）。
这些习惯背后，是我认同的几条工程直觉：
十二、与 BMAD 等的对比
我之前也学过 BMAD，两套东西可以对照着看：
| | |
|---|
| 多角色 + PRD/架构/User Story 工件链 | |
| | |
| 都不鼓励纯 vibe；强调对齐、小步、验证、设计投资 | |
| | 实现阶段用 grill / tdd / diagnose 约束 Agent |
另外我现在的理解是：Claude Code、Cursor 这类是「平台」，决定你能用什么模型和工具；mattpocock/skills 是「怎么协作」，决定 Agent 按什么纪律干活。Cline、Aider、Continue 更偏编辑器集成，内置的 skill 体系深浅不一。我选型时会分开看「用什么工具」和「用什么流程」，不只看 star 数。
十三、局限与注意点
- • 不是银弹：流程不能保证业务一定对，复杂领域还是要人审。
- • 必须先 setup：没跑
/setup-matt-pocock-skills，很多 engineering skill 不知道 issue 和标签从哪读。 - • 公开 skill 不是全部：
personal、in-progress 里还有未推广的内容。 - • 本质是 markdown 流程：真正跑起来靠我项目里的代码和 CI。
- • 前期更慢：grill 和 tdd 开头会拖节奏，换的是少返工；
caveman 省 token 但别在安全相关步骤乱压缩。
