Matt Pocock Skills v1.3 全解析：从 grill 到 retro 的 AI 工程化工作流实战
前言：为什么又是一套 Skills？
用 Claude Code、Codex 写代码久了，你大概踩过这几个坑：
- Agent 做出来的东西不是你想要的；
- Agent 话太多，20 个词说 1 个词的事；
- 代码跑不起来，它也不知道；
- 项目越写越乱，最后变成一团泥球。
GSD、BMAD、Spec-Kit 这类框架试图"接管流程"来解决问题。Matt Pocock（Total TypeScript 作者）的思路相反：不接管流程，只提供一组小而可组合的 skill，每个都短到你能读完、改掉、变成自己的。
这套仓库自称 Skills For Real Engineers——给真正做工程的人，不是 vibe coding。它的 README 直接把四个坑和对应的 skill 对上了号：
本文你将学到：
- v1.0 → v1.3.1 每个版本改了什么，重点是 v1.3 的新 skill 和破坏性变更；
- main 分支上还没发布、但值得提前知道的改动；
- 一个从零开始的完整实战：安装 → 配置 → 拷问需求 → 写 spec → 拆票 → TDD 实现 → 代码评审 → 写 PR → 复盘；
- 老用户升级时要做的三件事。
一、先搞懂两个核心概念
读变更日志之前，先建立两个概念。整个仓库的设计都围绕它们展开。
1.1 User-invoked vs Model-invoked
仓库里的 skill 按"谁能触发"分成两类：
- User-invoked（用户触发）：只有你敲 /xxx 才会运行，职责是编排流程。例如 /to-spec、/implement。它们在 frontmatter 里写了 disable-model-invocation: true。
- Model-invoked（模型触发）：你可以手动调用，Agent 也能在任务合适时自己调用，职责是沉淀可复用的纪律。例如 tdd、code-review、grilling。
有一条铁律：user-invoked 可以调用 model-invoked，但永远不能调用另一个 user-invoked。
这样一来，流程的"方向盘"始终在你手里，而 TDD、评审这些"手艺"可以被任意流程复用。
1.2 共享语言：GLOSSARY.md
这是 Matt 认为"整个仓库里最酷的技巧"。他举了自己项目里的例子：
- 之前："当某个课程章节里的一节课被变成'真实的'（也就是在文件系统里给它分配了位置）时出了问题"
- 之后："物化级联（materialization cascade）出了问题"
把项目术语沉淀进 GLOSSARY.md，Agent 读代码、起变量名、写 spec 都用同一套词。好处不只是省 token：命名一致，代码更好导航，Agent 思考时也更聚焦。
⚠️ 注意：v1.3.0 起，这个文件从 CONTEXT.md 改名为 GLOSSARY.md。老用户请看文末升级指南。
二、版本演进：v1.0 到 v1.3.1
仓库用 changesets 管理版本。先用一张表看全貌：
2.1 前情回顾：v1.0 ~ v1.2 打下的地基
这三个版本做了三件大事，理解它们才能看懂 v1.3。
第一，有了"路由"。 v1.0 新增 /ask-matt：你不用记住每个 skill，直接问它"我现在该用哪个"。它维护了一张流程地图，后续每加一个 skill 都要同步更新这张图。
第二，统一了规划链路。 v1.1 把 PRD 统一叫 spec，把三个拆任务的 skill 合成一个 to-tickets。主流程由此定型：
idea → /to-spec → /to-tickets → /implement
第三，变成了插件，并且跨 Harness。 v1.2 起可以用 Claude Code 插件一键安装；每个 SKILL.md 旁边加了 agents/openai.yaml，让同一份 skill 在 Codex 里也能用：
# skills/engineering/tdd/agents/openai.yaml
interface:
display_name: "TDD"
short_description: "Test-driven red-green-refactor"
另外，v1.2 把 grilling 从"一次问一个问题"改成"一轮问完整个前沿（frontier）"。前沿指所有前置条件已经确定、现在就能问的问题。按官方说法，同样 13 个问题，原来要 13 轮，现在约 3 轮问完。
2.2 v1.3.0：三个 skill 转正，一个被删，一个改名
v1.3.0 是近期最重要的版本。逐条看。
① implement-spec：并行实现整份 spec
以前拆完票，只能用 /implement 一张一张做。implement-spec 换了个视角：票据不是步骤列表，而是一张任务图（task graph）。
它的工作方式：
- 读 spec 和票据，理解依赖关系；
- （可选）派一个探索子代理先查资料，把笔记写到仓库外的公共目录，后续子代理共享；
- 创建一条集成分支（integration branch）；
- 对每张"前沿"票据，起一个实现子代理，各自在独立 worktree 里用 tdd 实现；
- 一个子代理完成后，由合并子代理把它的成果合进集成分支；
- 前沿变化了，就继续派新的实现子代理；
- 全部完成后，对整条集成分支跑一次 code-review，并用一个子代理修完所有问题。
转正前还做了几处打磨：
- 目标是集成分支，不是 PR。只有当你的 tracker 通过 PR 关闭工作、或你明确要求时，才会在第一次合并后开 draft PR（没有新提交的分支开不了 PR）；
- 没配置 issue tracker 时，会提示你先运行 /setup-matt-pocock-skills，而不是默默默认用 gh；
- 每个实现子代理开工前先确认 worktree 基于集成分支，交付前先把集成分支最新代码合进自己的分支，保证每次合并都是 fast-forward。
一句话：想自己逐张驱动就用 /implement，想当"包工头"编排并行就用 /implement-spec。
② pr：PR 描述该长什么样
pr 是 model-invoked 的，Agent 写 PR 时会自动用上。它规定 PR 正文只有三段：
## Summary
<最小的可视化：伪代码 / 调用树 / 文件树 / Mermaid / diff>
## Evidence
- **Before:** <截图 / 输出 / 失败的测试>
**After:** <截图 / 输出 / 通过的测试>
## Merge Danger
**Door:** <one-way 或 two-way>
**Blast Radius:** <一个词描述影响面>
几个值得学的点：
- Summary 选最小视图。改了逻辑就写伪代码，改了调用链就画调用树，改了目录就画文件树。这部分改编自 HumanLayer 的 Dex Horthy 写的 show-me。
- 证据分级：截图是 S 级，测试结果和控制台输出是 A 级。
- 单向门 / 双向门：能轻松回滚的是双向门，删数据、改不可逆决策的是单向门。
③ retro：复盘的是环境，不是代码
这是我个人最喜欢的一个。/retro 在一次编码会话后回看全过程，但它不改代码，而是改进 Agent 的工作环境。它检查七类问题：
其中最有价值的一条规则是：先给违规分类。
- 机械性违规（固定语法模式、禁用 API、import 形态、文件位置）→ 直接做成确定性检查：lint 规则、pre-commit hook 或 CI job；
- 判断性问题（跨文件一致性、"和周围风格一致"）→ 才写进 CODING_STANDARDS.md。
它还点明了一个分工原则：实现代理的上下文压力最大，评审代理只拿到 diff、压力最小，所以编码规范应该由评审代理来执行。CLAUDE.md / AGENTS.md 会进入每个 Agent 的上下文，要极度克制，基本只放导航指针。
④ 删除 resolving-merge-conflicts
官方理由很简单：不再需要了，Agent 自己就能处理进行中的 merge / rebase 冲突。这个 skill 没有替代品，文档页保留并标记为归档。
⑤ CONTEXT.md → GLOSSARY.md（破坏性）
所有读写领域文档的 skill 都改了名：CONTEXT.md → GLOSSARY.md，CONTEXT-MAP.md → GLOSSARY-MAP.md。skill 以后只认新名字。
⑥ 几个容易被忽略的补丁
- 跨 skill 调用规范化：以前 skill 里写"运行 /grilling skill"，Agent 并不总会加载它。现在统一写成 Call the Skill tool with "grilling"，命中率更高，也不再依赖 Claude Code 的斜杠语法。比如 grill-with-docs 的全部内容只有一行：
Call the Skill tool twice, for "grilling" and "domain-modeling".
- 修复违反铁律的调用：好几个 skill 曾试图"调用" setup-matt-pocock-skills（user-invoked），现在改为"提示用户去运行它"。
- YAML 修复：6 个 skill 的 description 因为一个未加引号的冒号导致 YAML 无效，npx skills 安装时被直接跳过。如果你之前发现 to-spec、code-review 装不上，原因就在这。
- 全仓库去掉破折号（em-dash），并在 CLAUDE.md 里禁止再引入。
2.3 v1.3.1
只有一条修正：ask-matt 里说 diagnosing-bugs 修完会交接给 improve-codebase-architecture，但这一步早被删了。现在改为：修完 bug 后在同一会话跑 /retro，问"什么能提前避免这个 bug"；如果结论是缺少合适的接缝（seam），再交给 /improve-codebase-architecture。
2.4 main 分支上的未发布改动
v1.3.1 之后又有 47 个提交、17 个待发布 changeset。挑对日常使用影响最大的：
另外，README 的安装说明也重写了：Claude Code、Codex、GitHub Copilot 都改为可自动更新的插件安装。
💡 有几条改动的 changeset 都写着同一句话："Re-run /setup-matt-pocock-skills to refresh docs/agents/"。发布后记得重跑一次 setup。
三、实战：从一个需求走完主流程
下面用一个具体场景走一遍。假设你有一个 TypeScript 电商后端，要加一个"优惠券"功能。我们用本地 Markdown 作为 issue tracker，这样不需要 GitHub 仓库也能跟着做。
3.1 安装
Claude Code（推荐，自动更新）：
claude plugin install mattpocock-skills@claude-plugins-official
Codex：
codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock
Cursor、OpenCode、Windsurf 等其他 Agent（需手动更新）：
npx skills@latest add mattpocock/skills -a cursor
⚠️ 两个坑：
- 插件和 skills.sh 二选一。同一个 Agent 两种都装，每个 skill 会出现两次。
- 用 npx skills 时，选择 skill 那一步一定勾上 setup-matt-pocock-skills。
插件里包含 27 个 skill（Engineering 20 个，Productivity 7 个）。in-progress/ 下的 beta skill 不在插件里，需要单独装：
npx skills@latest add mattpocock/skills --skill=claude-handoff
3.2 每个仓库跑一次 setup
在项目根目录打开 Claude Code，输入：
/setup-matt-pocock-skills
它不是脚本，而是"先探索、再确认、后写入"。它会检查 git remote、CLAUDE.md、GLOSSARY.md、docs/adr/、.scratch/ 以及是否有 monorepo 信号，然后按节问你：
- A. Issue tracker：GitHub / GitLab / 本地 Markdown / 其他（Jira、Linear 用一段话描述流程即可）。这里选本地 Markdown；
- B. Triage 标签：只有装了 triage 才会问，而且只问一句"保留默认标签吗？"；
- C. 领域文档布局：默认单上下文，只有检测到 monorepo 才会问。
确认后，它会在 CLAUDE.md 里写入一段：
## Agent skills
### Issue tracker
Issues live as local markdown files under `.scratch/`. See `docs/agents/issue-tracker.md`.
### Domain docs
Single-context: one `GLOSSARY.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.
并生成 docs/agents/issue-tracker.md 和 docs/agents/domain.md。其他 skill 都通过这段"指针"找到 tracker，而不是写死路径。
本地 tracker 的约定是：
.scratch/
└── <feature-slug>/
├── spec.md # /to-spec 产出
└── issues/
├── 01-<slug>.md # 一票一文件，从 01 开始
└── 02-<slug>.md
3.3 /grill-with-docs：先被拷问，再写代码
/grill-with-docs 我想给结算流程加优惠券：支持满减和折扣，一个订单只能用一张
它会加载 grilling 和 domain-modeling 两个 skill，一轮抛出所有当前能问的问题，每题附推荐答案。格式固定，大致是这样（示意）：
❓ **Q1** - **优惠券与订单的关系**：一个订单只能用一张券，那"购物车"阶段能否预选券？
还是只在"下单"时选择？
➡️ 推荐：只在下单时选择，购物车不持有券。回答 yes 即接受。
---
❓ **Q2** - **折扣叠加顺序**：满减券的门槛按原价还是按会员价计算？
➡️ 推荐：按会员价计算门槛。回答 yes 即接受。
你可以按编号回答，比如 Q1 yes，Q2 按原价。几个要点：
- 事实是 Agent 的事：能查代码得到的信息，它会派子代理去查，不来问你；
- 决策是你的事：它会停下来等你答；
- 前沿问空了，它会确认"我们是否达成共识"，没确认之前不会动手。
grill-with-docs 比 grill-me 多做的一件事是：一旦某个术语被敲定，就立刻写进 GLOSSARY.md；遇到难以逆转的决定，就写一条 ADR。会话结束后你可能得到：
<!-- GLOSSARY.md（示意） -->
# Checkout
下单与结算上下文：负责把购物车变成一笔可支付的订单。
## Language
**Coupon**:
用户在下单时可选的一次性折扣凭证，一个 Order 最多关联一张。
_Avoid_: 代金券、红包、voucher
**Threshold**:
满减券生效所需的最低金额，按商品原价计算。
_Avoid_: 门槛价、起用金额
domain-modeling 对术语表的要求很"偏执"：同一概念有多个叫法时只选一个，其余列进 _Avoid_；定义只写一两句；通用编程概念不进表。
docs/adr/0001-coupon-applied-at-order-not-cart.md
💡 如果对话中途 Agent 说了一大段你看不懂的话，直接输入 /wait-what。它会用简化技术英语（ASD-STE100）加上 GLOSSARY.md 里的术语重新解释一遍。整个 skill 只有三行。
3.4 需要可运行的答案？绕道 /prototype
如果某个问题"纸上谈兵"定不下来，比如优惠券的状态机到底该有几个状态，可以绕道原型：
- /handoff 把当前对话压缩成交接文档；
- 在新目录开新会话，用 /prototype 做一个单文件 HTML 原型，带状态面板和引导式演练；
- 再 /handoff 回来，在原对话里引用结论。
原型代码不会被删，而是保存在 prototype/<name> 分支上作为"一手资料"。
3.5 /to-spec：不再提问，只做综合
/to-spec
它不会再拷问你，而是把刚才的对话综合成一份 spec。只有一处会停下来确认：测试接缝（seam）。原则是：
- 优先复用现有接缝；
- 接缝越高越好；
- 接缝越少越好，理想是一个。
spec 模板包括：Problem Statement、Solution、User Stories（要求"极其详尽"）、Implementation Decisions、Testing Decisions、Out of Scope、Further Notes。注意它明确禁止写具体文件路径和代码片段，因为这些很快会过时。唯一的例外是原型产出的状态机、类型定义这类"比文字更精确"的片段。
产物会写到 .scratch/coupon/spec.md，并标记 ready-for-agent。
3.6 /to-tickets：拆成曳光弹
/to-tickets
它把 spec 拆成曳光弹（tracer bullet）式的垂直切片，规则是：
- 每张票打通所有层（schema、API、UI、测试），而不是只做某一层；
- 每张票完成后可以独立演示或验证；
- 每张票的大小要能放进一个全新的上下文窗口；
- 预重构（prefactoring）放最前面："先让改动变简单，再做简单的改动"。
它会先给你一个编号清单，问你粒度、依赖是否合理，确认后才写文件。一张票大概长这样：
# 02: 下单时应用满减券
**What to build:** 用户在下单时选择一张满减券，订单金额达到 Threshold 时
按券面额扣减，未达到时提示差额。
**Blocked by:** 01
**Status:** ready-for-agent
- [ ] 达到门槛时订单应付金额正确扣减
- [ ] 未达门槛时返回差额提示
- [ ] 已使用的 Coupon 不能再次应用
💡 遇到"重命名一个字段、影响上千个调用点"这种宽重构，它不会硬拆成垂直切片，而是按 expand–contract 排序：先加新形态、再分批迁移调用点、最后删除旧形态，保证每一批 CI 都是绿的。
⚠️ 上下文卫生：从 /grill-with-docs 到 /to-tickets 请保持在同一个上下文窗口里，不要中途 /compact 或 /clear。ask-matt 给出的"聪明区"大约是 150k token，快到上限时，在最近的阶段边界 /compact。
3.7 实现：/implement 或 /implement-spec
方式一：逐张驱动。
/implement .scratch/coupon/issues/01-coupon-model.md
按最新 main 的行为，它会先读取票据并复述标题，然后：
- 调用 tdd，在事先约定的接缝上做 red → green；
- 频繁跑类型检查和单个测试文件，最后跑一次全量测试；
- 调用 code-review 评审；
- 提交到当前分支。
做完一张票就 /clear，再做下一张。每张票都自包含，上一张的上下文可以丢掉。
方式二：并行编排。
/implement-spec .scratch/coupon/spec.md
适合票据多、依赖图有明显并行空间的场景。它的完整流程见 2.2 节。
tdd 的三个反模式
tdd 现在是"纯参考"型 skill，不再规定一步步的工作流，而是告诉 Agent 什么样的测试值得留下。它点名了三个反模式：
// ❌ 同义反复：用代码的算法重新计算期望值，永远不会失败
expect(applyCoupon(price, coupon)).toBe(price - coupon.amount)
// ✅ 期望值来自独立的事实来源：写死的已知结果、规格里的例子
expect(applyCoupon(300, fullReduction(200, 30))).toBe(270)
- 耦合实现：mock 内部协作者、测私有方法、绕过接口直接查数据库；
- 同义反复：如上例；
- 水平切片：先写完所有测试再写实现。正确做法是一个测试 → 一个实现 → 循环。
还有一点容易忽略：重构不在 TDD 循环里，它属于评审阶段。
code-review 的两条轴
code-review 会并行启动两个子代理，互不污染：
- Standards：是否符合仓库的编码规范，外加一套 Fowler《重构》里的 12 种代码坏味道作为基线（神秘命名、重复代码、依恋情结、数据泥团、基本类型偏执、霰弹式修改等）；
- Spec：是否忠实实现了 spec，有没有遗漏、有没有范围蔓延、有没有"看似实现但实际错了"。
两份报告分开呈现、不合并排序。因为"规范全对但做错了东西"和"做对了东西但破坏规范"是两种不同的失败，合在一起会互相掩盖。
另外两条约束：仓库自己的规范永远优先于基线；坏味道永远只是"判断建议"，不是硬性违规。
你也可以单独用它评审任意分支：
/code-review 对比 main 评审当前分支
3.8 pr：自动套模板
如果你让 Agent 开 PR，pr 会自动生效。比如这次改动，Summary 可能是一棵调用树：
createOrder
validateCart
+ applyCoupon
+ checkThreshold
persistOrder
Evidence 贴上前后的测试结果，Merge Danger 标明：新增功能、可通过开关回滚，是双向门（two-way door），影响面（Blast Radius）为 checkout。
3.9 /retro：让下一次更顺
在同一个会话里、/clear 之前运行：
/retro
它会按严重程度列出改进建议，比如（示意）：
- Automated checks：Agent 两次把金额写成浮点数运算，这是机械问题，建议加一条 lint 规则禁止对 Money 类型使用 + / -；
- Navigation：Agent 花了 6 次搜索才找到价格计算模块，建议在 CLAUDE.md 里加一行导航指针；
- Coding standards："金额一律用分存储"属于判断性约定，写入 CODING_STANDARDS.md，由评审代理执行。
下一次构建就从一个更好的环境开始。这就是主流程的闭环。
3.10 三个"入口匝道"
不是所有工作都从一个想法开始。ask-matt 还定义了三条汇入主流程的匝道：
两个提醒：
- /triage 只处理不是你创建的 issue，/to-tickets 产出的票已经是 agent-ready，别再 triage；
- /wayfinder 是最重的流程，产出的是决策而非交付物。范围清晰的功能用 /grill-with-docs 就够了。
记不住也没关系，随时问：
/ask-matt 我有一个线上偶发的 500，该从哪开始？
四、老用户升级指南
如果你在 v1.2 或更早就装了这套 skill，升级到 v1.3 请检查三件事：
1. 重命名领域文档
git mv CONTEXT.md GLOSSARY.md
# 多上下文仓库还要：
git mv CONTEXT-MAP.md GLOSSARY-MAP.md
不改名的话，skill 会当作项目里没有术语表。
2. 重跑 setup
/setup-matt-pocock-skills
刷新 docs/agents/issue-tracker.md，拿到 sub-issue 命令、外部 PR 列表修复、glab 命令修复等改动。它会就地更新已有的 ## Agent skills 段，不会重复追加。
3. 清理已删除的 skill
- resolving-merge-conflicts（v1.3.0 删除，无替代）；
- 更早删除的：ubiquitous-language → domain-modeling，design-an-interface → codebase-design，qa → triage + to-tickets，write-a-skill / writing-great-skills → writing-for-agents。
用插件安装的会自动更新；用 npx skills 装的，执行：
npx skills@latest update
五、常见问题
Q1：grilling 能不能用 Claude Code 的 AskUserQuestion 弹窗提问？
官方明确不做。理由有二：skill 要跨 Harness，各家的提问工具不同；结构化选择题会把 Agent 推向"预设答案"，违背了 grilling 让你用自己的话回答开放问题的初衷。如果你就是喜欢弹窗，在自己的 CLAUDE.md 里加一句 "when grilling, ask via AskUserQuestion" 即可。
Q2：可以给仓库贡献新 skill 吗？
不接受。仓库只放作者自己每天在用的 skill，每个 skill 都意味着长期维护成本。他的原则是：能用现有 skill 组合出来的行为，就不该有新 skill。 你可以用 skills.sh 发布自己的。
Q3：misc/ 下的 skill 还能用吗？
能用，但已冻结，不再接受 bug 和 PR。git-guardrails-claude-code、setup-pre-commit 等都在这里，想用就装一份自己改。
Q4：没有 GitHub 仓库能用吗？
能。setup 时选本地 Markdown，所有 spec 和票据都写在 .scratch/ 下，wayfinder 也有对应的本地实现。
Q5：/handoff 和 /compact 怎么选？
v1.2 之后的 ask-matt 给了一棵决策树，按顺序问自己：
- 能不能继续？（成本为零，保留一手上下文）
- 接下来的事和当前上下文无关？→ /clear
- 要换 Harness、换目录、交给同事、或中途分叉支线？→ /handoff
- 任务边界清晰、能独立跑完？→ 交给子代理
- 以上都不是 → /compact（默认选项，但放在最后）
总结
这次 v1.3 的升级可以用三句话概括：
- 主流程补齐了尾巴：implement-spec 负责并行，pr 负责交付，retro 负责闭环。主流程现在是 grill → spec → tickets → implement → review → PR → retro。
- 约定更一致：GLOSSARY.md 统一命名，"Call the Skill tool" 统一调用方式，user-invoked 和 model-invoked 的边界更清晰。
- 更轻：删掉不再需要的 skill，不接受新 skill 贡献，坚持"小而可组合"。
我觉得这套 skill 最值得借鉴的，不是某个具体命令，而是背后的工程观：先对齐，再动手；用共享语言压缩沟通；用反馈回路代替猜测；把犯过的错变成环境里的护栏。 这些原则在 AI 时代没有过时，反而因为 Agent 写代码太快，变得更重要了。
如果你还没试过，建议从最小的组合开始：/grill-with-
本文由 AI图鉴自动抓取并翻译，版权归原作者所有；如需查看原文请点下方链接。
Matt Pocock Skills v1.3 Total Parsing: AI Engineering workflow Field
Foreword: Why is it another Skills?
It's been a long time since Claude Code and Codex, and you probably stepped on these holes:
-Agent made something that you didn't want;
- Agent talks too much, 20 words say one word;
- The code can't run, it doesn't know;
- The project became more messy and turned into a mud ball.
Such frameworks as GSD, BMAD, Spec-Kit attempt to "take over the process" to solve the problem. Matt Pocock (Total TypeScript author) has the opposite idea: instead of taking over the process, he offers a small group of skills that can be combined, each shorter than you can read, change and become yourself.
This warehouse calls itself Skills For Real Engineers -- for real engineering, not vibe coding. Its README directs four pits and the corresponding stil:
Here you will learn:
- v1.0 → v1.3.1 What has been changed in each version, focusing on v1.3 new skill and destructive changes;
- There is no publish on the main branch but it deserves to be changed in advance;
- A full-scale battle from scratch: install configuration torture demand write spec write write TPD achieve code evaluation write PR double disk;
- Three things old users do when they upgrade.
I. Understanding the two core concepts
Before reading the change log, two concepts are established. The entire warehouse was designed around them.
1.1 User-invoked vs Model-invoked
Skill in the warehouse divided into two categories by "who can trigger"?
- User-invoked (user trigger): Only you knock / xx will run. The job is to organize the process. For example /to-spec, /implement. It's written in front matter that it's possible-model-information: true.
- Model-invoked (mode trigger): You can call manually, and Agent can call yourself when the mission is right. The duty is to settle reusable discipline. For example, tdd, code-review, gilling.
There is an iron rule: user-invoked can call model-invoked, but never another user-invoked.
So, you always have the wheel of the process, and the TDD, the evaluation of these crafts, can be reused by any process.
1.2 Shared language: GLOSSARY.md
It's Matt thinks "the coolest technique in the whole warehouse." He gave the example of his project:
- Before: "There was a problem when a section of a course was turned into 'real'.
- And then: "There's a problem with the artery cascade."
The project terminology is deposited into GLOSARY.md, Agent reads the code, starts the variable name and writes spec in the same set of terms. The benefits are not just token: identical names, better code navigation, and Agent thinking more focused.
Note: v1.3.0 from CONTEXT.md to GLOSARY.md. Old users are requested to read the end-of-text upgrade guide.
II. Version evolution: v1.0 to v1.3.1
Warehouse management version with changesets. Let's see the whole picture with a watch:
2.1 Previously: V1.0 ~ v1.2 Based
The three versions did three important things to understand them to understand v1.3.
First, there's the route. v1.0 Add /ask-matt: You don't have to remember every skill, just ask it, "Who should I use?" It maintains a process map, which is updated simultaneously for every additional skill.
Second, planning chains are harmonized. v1.1 Aligning the PRD with a spec and combining the skill of the three missions into one to-tickets. The main process is thus stereotyped:
idea → /to-spec → /to-tickets → /implement
Third, it becomes a plugin and cross Harness. v1.2 Up to be installed with a one-click Claude Code plugin; each SKILL.md is accompanied by agents/openai.yaml so that the same skill can also be used in Codex:
# skills/engineering/tdd/agents/openai.yaml
interface:
display_name: "TDD"
short_description: "Test-driven red-green-refactor"
Also, v1.2 replaces the "question at once" with "frontier." Frontlines are all questions that have been identified and can be asked now. In official terms, the same 13 questions, originally 13 rounds, are now about 3 rounds.
2.2 v1.3.0: Three skills corrected, one deleted, one renamed
v1.3.0 is the most important version in the near future. Article by article.
1 implement-spec: achieve the whole in parallel
Once the tickets were broken, one by one. Implement-spec has a different perspective: a document is not a step list, but a task map (task graph).
It works:
- Read spec and papers to understand dependency;
- Sending (optional) an exploratory sub-agent to first check the information, write notes to a public directory outside the warehouse and share them with the successor;
- Creation of an integrated branch (integration brancy);
- For each "front line" instrument, a sub-agent of realization is created, each with a tddd in an independent worktree;
- Once a sub-agent has been completed, the merger sub-agent integrates its results into an integrated branch;
- New agents for realization continue to be assigned when the front line changes;
- Once it's all finished, run the whole integrated branch once and fix all the problems with a sub-agent.
There were a couple of grindings before the shift:
- The goal is an integrated branch, not a PR. Only when your tracker closes a job through a PR, or when you explicitly request it, will you open a draft PR after the first merger (without a new branch being submitted);
- When no issue tracker is configured, you are prompted to run /setup-matt-pocock-skills instead of using gh;
- The worktree is based on an integrated branch before the commissioning of each realization sub-agent, which consolidates the latest code of the integrated branch into its own branch before delivery, ensuring that each merger is fast-forward.
One sentence: Use /implement if you want to drive one by one, use /implement-spec if you want to be a foreman.
2 pr: PR describes what it looks like
pr is model-infoked, which is automatically used by Agent when writing PR. It provides that there are only three paragraphs in the PR text:
## Summary
< Minimal visualization: pseudocode / call tree / file tree / Mermaid / diff>
## Evidence
-**Before:** < Caption / Output / Failed Test>
**After:** <Map / Output / Test passed >
## Merge Danger
**Door:** <one-way or two-way>
** Blast Radius:** < A word to describe impact >
A few points worth learning:
- Summary selects the smallest view. The logic changes, the code is false, the chain is changed, the tree is called, the directory is changed and the file tree is drawn. This part is adapted from the show-me by Dex Horthy of HumanLayer.
- Evidence classification: The screenshot is Level S, the test result and the console output is Level A.
- One-way door / two-way door: it's the two-way door that can easily roll back, and it's the one-way door that deletes data and makes irreversible decisions.
3 retro: Reset is environment, not code
This is my personal favorite. /retro looks back at the whole process after a coding session, but it does not change the code, but improves the Agent working environment. It examines seven categories of issues:
One of the most valuable rules is the classification of violations first.
- Mechanical violations (fixed syntax mode, disablement of API, import form, location of file) directly into definitive checks: Lint rules, pre-committee hook or CI job;
- The issue of judgement (cross-document consistency, "conformity with surrounding style") was written in CODING STANDARDS.md.
It also points to the principle of division of labour: the pressure to achieve the agent ' s context is greatest, the evaluation agent receives only diff, and the pressure is minimal, so the code regulation should be implemented by the evaluation agent. CLUDE.md / AGENTS.md will enter context for each Agent, with extreme restraint and essentially only a navigational pointer.
4 Delete
The official reason is simple: no longer needed, Agent can deal with ongoing conflict / rebase. This skill has no alternative, the document page is kept and marked as archive.
5 CONTEXT.md GHOSSARY.md
All files in the reading and writing field have been renamed: CONTEXT.md → GLOSARY.md, CONTEXT-MAP.md → GLOSARY-MAP.md. Skill will only recognize new names later.
6 easily ignored patches
- Cross Skill Call Normalization: Previously Skill wrote "Running / Grilling Skill", Agent does not always load it. Call the Skill tool with "grilling" with a higher hit rate and no longer relying on Claude Code's slash syntax. For example, there is only one line to the full content of Gill-with-docs:
Call the Skill tool twice, for "grilling" and "domain-modeling".
- Fixing iron-busting calls: several skills have tried to "call" setup-matt-pocock-skills (user-invoked) and now "tip users to run it".
-YAML fixes: 6 skills description was aborted when installed by an unquoted colon. If you've found out before to-spec, code-review can't fit, that's why.
- The entire warehouse removes the decoy (em-dash) and prohibits its reintroduction in the CLAUDE.md.
2.3 v1.3.1
There's only one amendment: ask-matt said that the repair of diagnosing-bugs was handed over to improve-code-architecure, but this step was deleted. Now, after the bug is fixed, run in the same conversation /retro, ask, "What avoids this bug in advance"; if the conclusion is that there is a lack of a suitable seam, then give it to /improve-code-architecure.
2.4 Main branch unmodified publish
v1.3.1 There were 47 subsequent submissions and 17 pending publish changeset. The most important impact on daily use is selected:
In addition, the installation instructions for README have been rewritten: Claude Code, Codex, GitHub Copilot has been replaced with automatically updated plugin installation.
💡 Changeset, with several changes, writes the same sentence: "Re-run/setup-matt-pocock-skills to refresh docs/agents/". Remember to run again after publish.
III. THE PLAYING: ENDING THE MAIN PROCESS FROM A REQUIREMENT
Let's go over it with a specific scene. Suppose you have a TypeScript backend, add a coupon. We use local Markdown as issue tracker, so we don't need GitHub warehouse to do it.
3.1 Installation
Claude Code (recommended, automatically updated):
claude plugin install mattpocock-skills@claude-plugins-official
Codex：
codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock
Cursor, OpenCode, Windsurf and others Agent (to be manually updated):
npx skills@latest add mattpocock/skills -a cursor
Two pits:
- Plugin and skills.sh two or one. The same Agent both will appear twice for each skill.
- When using npx skills, choose skill that step to setup-matt-pocock-skills.
The plugin contains 27 skills (20 Engineering, Production 7). In-process/ Beta skill is not in the plugin and needs to be installed separately:
npx skills@latest add mattpocock/skills --skill=claude-handoff
3.2 One run per warehouse setup
Claude Code, enter:
/setup-matt-pocock-skills
It's not a script, it's "explor, confirm, write." It will check for prompt remote, CLAUDE.md, GLOSARY.md, docs/adr/,.scratch/ and if there is a signal for monorepo, then ask you by section:
- A. Issue tracker: GitHub / GitLab / Local Markdown / Other (Jira, Linear describes the process in a single sentence). Here is the local Marktown;
- B. Triage label: only if it is loaded will it ask, and only one sentence will be asked: "Retention of the default label?";
- C. Field document layout: the default context, only if the monorepo is detected.
Upon confirmation, it will write a paragraph in CLAUDE.md:
## Agent skills
### Issue tracker
Issues live as local markdown files under `.scratch/`. See `docs/agents/issue-tracker.md`.
### Domain docs
Single-context: one `GLOSSARY.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.
It also produces docs/agendas/issue-tracker.md and docs/agendas/domain.md. The rest of Skill found tracker through this pointer instead of writing a dead path.
Local tracker engagement:
.scratch/
└── <feature-slug>/
spec.md /to-spec output
└── issues/
Ideas-01-<slug>.md # One vote and one document, starting at 01
└── 02-<slug>.md
3.3 /grill-with-docs: Torture first, then code later
/grill-with-docs I'd like to add coupons to the settlement process: to support full reduction and discount, one order only.
It loads two skills of gilling and domain-modeling, and throws out all the questions that can be asked at the moment, each with a recommended answer. The format is fixed, broadly as follows (indicators):
**Q1** - **The relationship between coupons and orders**: Can a purchase order be made with only one ticket?
Or is it only for "down order"?
• Recommendations: The shopping cart is not in possession of a ticket only at the next order. Answer yes is accepted.
---
**Q2** - ** Order of discounts added**: the threshold for full vouchers is based on original or membership prices?
Recommendations: threshold based on membership. Answer yes is accepted.
You can answer by number, like Q1 yes, Q2 at the original price. Several points:
- The truth is, Agent: he can check the code's information, he'll send his agent to look into it, not ask you;
- Decision-making is your business: it will stop and wait for your answer;
- The front line's empty. It'll confirm if we agree. We won't do it before we know.
Once a term is finalized, it is written in GLOSSARY.md, and an ADR is written in case of a decision that cannot be reversed. After the session, you might get:
{\cHFFFFFF}{\cH00FFFF} {\cHFFFFFF}{\cH00FFFF}
# Checkout
context: Responsible for turning the shopping cart into a payable order.
## Language
**Coupon**:
The one-time discount voucher that the user can choose at the time of the next order, with an Order associated with up to one.
Avoid : voucher, red bag, voucher
**Threshold**:
The minimum amount required for a full voucher to become effective is calculated at the original commodity price.
Avoid : threshold, start-up amount
The terminological requirements are "biased": The same concept is called more than one and the rest is listed in Avoid; the definition is written only in one or two sentences; the generic programming concept is not included in the table.
docs/adr/0001-coupon-applied-at-order-not-cart.md
If Agent had said a lot of things you couldn't understand, he would have entered /wait-what. It would be re-explained with the terminology in the simplified technology English (ASD-STE100) plus GLOSSARY.md. The whole skill has only three lines.
3.4 Need operational answers? Detour /prototype
If there's a problem with the paper, like how many states the coupons should have, we can go around the prototype:
- /handoff compress the current dialogue into a cross-cutting document;
- Opening a new session in a new directory, using /prototype as a single file HTML prototype, with a status panel and a steering exercise;
- Again/handoff comes back and quotes the conclusions from the original conversation.
The prototype code will not be deleted but will be kept as "firsthand information" on the prototype/<name> branch.
3.5 /to-spec: no more questions, only synthesis
/to-spec
It's not going to torture you, it's going to synthesize the conversation into a spec. Only one will stop to confirm: test stitches (seam). The principles are:
- Prioritize reuse of existing seams;
- The higher the seam, the better;
- The less stitches the better, the better.
The spec templates include: Problem Statement, Solution, User Stores (requirement for "extreme detail"), Immunisation Decisions, Testing Decisions, Out of Spope, Further Notes. Note that it expressly prohibits the writing of specific document paths and code segments, as they will soon become obsolete. The only exception is the prototype output's status machine, the type definition of such "more precise" clips.
The product will be written at.scratch/coupon/spec.md and marked ready-for-agent.
3.6 /to-tickets: Dismantling to tracer
/to-tickets
It removes specs into vertical slices of tracer bullet, the rule being:
- Each ticket leads to all layers (schema, API, UI, test) rather than only one level;
- Each ticket can be independently demonstrated or validated;
- The size of each ticket should include a new context window;
- Pre-refactoring: "Simplify changes before making simple changes."
It will provide you with a numbered list of the size, rationality of your dependence and confirmation before writing a document. One ticket is about this:
#02: Apply full coupons on the next order
**What to build:** User selects a full coupon at the time the order reaches Threshold
Deductions based on the face of the voucher, with a reminder of the difference if not achieved.
**Blocked by:** 01
**Status:** ready-for-agent
- [ ] Correct deduction of the amount due for orders upon reaching the threshold
- [ ] Return the difference when the threshold is not met
- [ ] Used Coupon cannot be applied again
💡 In the case of "rename a field and affect thousands of call points", it is not hard to break into vertical slices, but rather sorted by expansion-contract: add new forms, move points and eventually delete old ones, making sure that each batch of CI is green.
context Health: From /grill-with-docs to /to-tickets, please stay in the same context window, do not go halfway /compact or /clar. Assk-matt gives about 150k token, fast to up limited-time, at the nearest stage of boundary /compact.
3.7 Achieved:/implement or/implement-spec
Mode one: A one-by-one drive.
/implement .scratch/coupon/issues/01-coupon-model.md
Following the latest moin, it reads the instrument and repeats the title, and then:
- Call tdd and make red gien on the pre-arranged seam;
- Frequent running type checks and individual test files, with a final full run;
- Call the code-review evaluation;
- Submit to current branch.
Finish one ticket and make the next. Each ticket is self-contained and the last context can be dropped.
Mode 2: Parallel organization.
/implement-spec .scratch/coupon/spec.md
A scenario suitable for multiple instruments, relying on the map for a distinct parallel space. It's a complete process in Section 2.2.
tdd's three reverse modes
Tdd is now a "pure reference" skill, no longer providing for step-by-step workflow, but instead telling Agent what kind of test is worth staying. It named three reverse patterns:
/ / ❌ Synonyms: Recalculate expectations with code algorithms, never fail
expect(applyCoupon(price, coupon)).toBe(price - coupon.amount)
/ / / Expectations are from independent factual sources: known results of death, examples in specifications
expect(applyCoupon(300, fullReduction(200, 30))).toBe(270)
- Convergence: mock internal collaborators, private methods, direct access to databases by bypassing interfaces;
- Synonyms: as in the previous case;
- Horizontal Slices: Write all tests before writing. The correct approach is a test of a realization of a loop.
There's one more thing that can easily be ignored: it's not in the TDD cycle, it's in the evaluation phase.
Two axes of code-review
Code-review will launch two sub-agents in parallel without contamination:
- Standards: Compatibility with the warehouse code code plus a set of 12 code bad tastes in Fowler ' s Reconstruction as a baseline (mysterious naming, duplicate code, attachment, data mud, basic types of paranoia, shatter modifications, etc.);
- Spec: if it's true or not, if it's true, if it's true, if it's missing, if it's not widespread, if it's not "appearable but it's actually wrong".
The two reports are presented separately and are not consolidated. Because doing the right thing and doing the wrong thing and breaking the wrong thing are two different failures, and together they cover up each other.
Two other constraints: the warehouse's own norms will always take precedence over the baseline; the bad taste will always be just a "judgment of judgment" rather than a hard violation.
You can also use it alone to evaluate any branch:
/code-review Compare Main
3.8 pr: Autoset Templates
If you let Agent drive the PR, it'll take effect automatically. Like this change, Summary could be a call tree:
createOrder
validateCart
+ applyCoupon
+ checkThreshold
persistOrder
Evidence paste the test results, Merge Danger indicates that the new function, which can roll back through a switch, is tow-way door, and the impact side (Blast Radius) is checkout.
3.9 /retro: Make next time easier
Run in the same session, before/clar:
/retro
It lists recommendations for improvement by severity, such as (indicators):
- Automated checks: Agent twice wrote the amount into floating point operations, which is a mechanical problem, and suggested adding a lint rule to prohibit the use of +/ - for the Money type;
- Navigation: Agent took six searches to find the price calculation module and suggested adding a line of navigational indicators to the CLAUDE.md;
- Coding standings: "Equals are stored separately" is a judgmental agreement, written in CODING STANDARDS.md and executed by an assessor.
The next construction starts with a better environment. That's the closed ring of the main process.
3.10 Three portals.
Not all work starts with an idea. Ask-matt also defines the three main remittance channels:
Two reminders:
- /Triage handles only those issues that you did not create, /to-tickets are already anent-ready, no more triage;
- /wayfinder is the most heavy process, producing decisions rather than deliverables. A clear range of functionality is enough.
It doesn't matter if you can't remember.
I've got 500 on the line.
IV. Upgrading guidance for older users
If you have this skill in v1.2 or earlier, upgrade to v1.3, check three things:
1. Rename Field Documents
git mv CONTEXT.md GLOSSARY.md
# The multi-context warehouse also:
git mv CONTEXT-MAP.md GLOSSARY-MAP.md
If you don't change your name, Skill will take it there's no glossary in the project.
2. Rerun setup
/setup-matt-pocock-skills
Updates docs/agendas/issue-tracker.md, get sub-issue commands, external PR list fixes, glab command fixes, etc. It will update the existing #Agent skills in place and will not be repeated.
3. Clear deleted skill
- resolution-merge-conflits (v1.3.0 deleted, no substitute);
- Earlier deleted: ubiquitous-language — domain-modeling, design-an-interface — codebase-design, qa — to-tickets, write-a-skill/wringing-great-skills — writing-for-agents.
Automatically updated with plugins; loaded with npx skills, execute:
npx skills@latest update
Common issues
Q1: Grilling, can I ask you a question with Claude Code's AskUserQuestion window?
Officially clear. There's two reasons: Skill's going to cross Harness, and there's a different question-and-answer tool; the structured choice is going to push Agent to "preset the answer," and it's going against the point that you're going to answer open questions in your own words. If you just like to pop a window, add a line to your own CLUDE.md.
Q2: Can you contribute to the warehouse?
Not accepted. The warehouse only leaves the author with the skill, and every skill means long-term maintenance costs. His principle is that there should be no new skill if you can combine existing skills. You can use skills.sh publish yourself.
Q3:misc/ Skill is still working?
Available, but frozen, no longer accepting bugs and PRs. Here's all the giddy-guardrails-claude-code, setup-pre-committee and so on.
Q4: No GitHub repository available?
Yes. Setup selects local Markdown, and all specs and bills are written under.scratch/, and the wayfinder has corresponding local realizations.
Q5:/handoff and /compact how?
v1.2 Then ask-matt gave a decision tree and asked himself in order:
- Can we continue?
- What's next has nothing to do with the current context? /clar
- Should we change Harness, change the directory, give it to colleagues, or split the fork? /handoff
- The mission is clear and can run independently? Give it to the agent.
- None of the above is →/compact (default option, but at the end)
Summary
This upgrade of v1.3 can be summarized in three sentences:
- Main process completes the tail: implement-spec for parallel, pr for delivery, retro for closure. The main process is now gill-spec-tick-ticks-implement-review-PR-retro.
- A more consistent agreement: GLOSARY.md unifiedly named, "Call the Skill tool" unifiedly called, clearer border between user-invoked and model-invoked.
- Lighter: delete the needless skill, don't accept the new skill contribution, insist on "small but groupable".
And I think the best thing to learn from this is not a specific order, but the vision behind it: alignment before doing it; condensed communication in shared language; feedback loops instead of guesswork; turning mistakes into a fence in the environment. These principles were not obsolete in the AI era, but rather became more important because Agent wrote code too quickly.
If you haven't tried yet, suggest starting with the smallest combination: /grill-with-
Auto-fetched and translated by AI Atlas. All rights belong to the original author.