mattpocock/skills 实践指南

面向第一次接触这套 skills 的工程师：从安装、首次配置，到把"想法 → 规格 → 工单 → 实现 → 验证 → 评审"串成一条可直接上手的工作流。全部内容基于对 mattpocock/skills 仓库的真实阅读（README、CONTEXT.md、各 SKILL.md 与 docs/ 页面），示例对话与工单内容翻译为中文。

一、项目定位与核心理念

这是 Matt Pocock（Total TypeScript 作者）日常自用的 agent skills 集合，口号是 "Skills For Real Engineers"——做真实的工程，而不是 vibe coding。

反流程框架立场

README 开篇就点明了与主流 SDD 框架的分歧：

"开发真实应用是困难的。GSD、BMAD、Spec-Kit 这类方法试图通过拥有流程（owning the process）来提供帮助。但在这样做的同时，它们拿走了你的控制权，而且流程里的 bug 很难解决。"

"这些 skills 被设计为小而易改、可组合。它们适用于任何模型，基于数十年的工程经验。拿去魔改，变成你自己的。"

与 Spec-Kit 等"规格即源码、命令链驱动全流程"的框架相比，差异在于：

维度GSD / BMAD / Spec-Kitmattpocock/skills
流程归属框架拥有流程，定义固定的阶段链与命令顺序不拥有流程；只提供可组合的 skill，由工程师自己决定何时调用哪个
控制粒度整条流水线被编排好，人按框架的节奏走每个 skill 是一个独立工具（访谈、写规格、拆工单、TDD……），工程师保留每一步的控制权
可修改性流程的 bug 难以定位和修复skill 就是普通 Markdown 文件，可以直接改、可以只取一部分
状态存放spec 模板是强制的 source of truth产物落在 issue tracker、CONTEXT.md、docs/adr/ 这些团队已有的位置，而非框架私有格式

要解决的四个失败模式

README 把这套 skills 的存在理由归纳为 AI 编码的四个常见失败模式，每个对应一组 skill：

  1. "Agent 没做我要的东西"——错位（misalignment）是最常见的失败。解法是拷问式访谈（grilling session）：让 agent 反过来向你追问细节。对应 /grill-with-docs（有仓库时）与 /grill-me（无仓库时）。
  2. "Agent 太啰嗦"——缺一套共享语言。解法是领域词汇表 CONTEXT.md：同一个概念用一个词。README 举的例子：没有共享语言时 agent 写"课程里某个章节下的一节课被'实体化'（即在文件系统里分配了位置）时出了问题"，有了之后就是一句话——"materialization cascade 出了问题"。这同时让命名一致、代码库更易导航、思考 token 更少。
  3. "代码不工作"——缺反馈回路。解法是静态类型、浏览器访问、自动化测试，核心是 /tdd 的 red-green 循环；调试硬 bug 用 /diagnosing-bugs 的分阶段纪律。
  4. "我们堆出了一个烂泥球"——agent 加速了编码，也以前所未有的速度加速了软件熵。解法是认真关心代码设计：/to-spec 在写规格前追问你动到哪些模块，/improve-codebase-architecture 定期扫描"深化（deepening）机会"。

User-invoked 与 Model-invoked：两类 skill

这套 skills 只沿一条轴划分：谁能调用它。

组合规则只有一条：user-invoked 的 skill 可以调用 model-invoked 的 skill，但绝不能调用另一个 user-invoked 的 skill。这就是为什么 implement 内部"驱动 tdd、收尾时跑 code-review"是合法的，而主链路上每一步都要由你亲手敲下斜杠命令——编排权在人手里，这正是"工程师保留控制权"的落地方式。

二、安装：两条路，两种哲学

README 明确说"二选一，两个都装会让每个 skill 出现两份"：

方式命令哲学适合谁
Claude Code 插件 claude plugins install mattpocock-skills
或会话内 /plugin install mattpocock-skills		 订阅制：整套 skills 作为托管的只读包安装，作者发布更新时自动跟进。在 Claude Code 官方 marketplace 里，无需先添加市场 想"开箱即用、跟着作者升级"的人
skills.sh 安装器
（Codex 及其他 agent；也适合折腾党）		 npx skills@latest add mattpocock/skills 复制制：把 skill 文件复制进你的项目，成为你拥有、可编辑的普通文件。安装器允许你挑选要哪些 skill、装给哪些 agent。更新靠手动 npx skills update 用 Codex 等其他 agent 的人；以及想魔改 skill 内容、让它们"变成自己的"的人
注意：用 npx 安装器时，务必勾选 setup-matt-pocock-skills——它是后续所有 engineering skills 的前置配置步骤。README 专门加粗提醒了这一点。

三、首次配置：/setup-matt-pocock-skills

装好之后在仓库里跑一次 /setup-matt-pocock-skills（每个仓库一次）。它是提示驱动的 skill，不是确定性脚本：流程是"探索 → 向你汇报发现 → 逐项确认 → 落盘"。

它做什么

先探索仓库现状：git remote 指向哪里、有没有 CLAUDE.md/AGENTS.md、有没有 CONTEXT.md 和 docs/adr/、triage skill 是否安装、有没有 monorepo 信号（pnpm-workspace.yaml 等）。然后分三节与你确认：

  1. Issue tracker（问题追踪器）：to-tickets、triage、to-spec 这些 skill 要往哪里读写 issue。默认推荐 GitHub（用 gh CLI）；也支持 GitLab（glab）、本地 Markdown（issue 以文件形式放在 .scratch/<feature>/ 下，适合个人项目或无 remote 的仓库）、以及其他（Jira、Linear 等，用一段自由文本描述工作流）。
  2. Triage 标签词汇表：仅当 triage 已安装才问。默认是五个规范角色，标签字符串与角色同名：needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。推荐直接接受默认值。
  3. 领域文档布局：默认单上下文（根目录一个 CONTEXT.md + docs/adr/），几乎适合所有仓库；只有发现 monorepo 信号时才提供多上下文选项（根 CONTEXT-MAP.md 指向各上下文自己的 CONTEXT.md）。

它写什么

落盘前会把要写入的内容草稿给你过目。之后这些文件可以直接手改；只有想换 tracker 或推倒重来时才需要重跑该 skill。没有跑过 setup 时，to-spec/to-tickets/triage/code-review 会提示你先补跑。

四、工作流总览：一条主链路，两条入口匝道

仓库里的 ask-matt skill 本身就是一张路由图（"你不记得每个 skill 是干嘛的，就问"），它把所有 user-invoked skill 组织成：一条主链路（idea → ship）、两条入口匝道（triage / diagnosing-bugs / wayfinder 汇入主流）、加上代码库健康与若干独立工具。

                    [入口匝道]                          [主链路]
  别人提的 bug/需求 ──→ /triage ──────────────┐
  硬 bug ────────────→ /diagnosing-bugs ──→（修复 + 回归测试）
  超大模糊工程 ──────→ /wayfinder ──→ 地图清晰后汇入 to-spec
                                              │
  想法 → /grill-with-docs → [/prototype 绕行] → /to-spec → /to-tickets
                                              │
                                              ▼
                              每个 ticket 一个新会话：/implement
                              （内部驱动 /tdd，收尾跑 /code-review）
                                              │
                                              ▼
                                   提交，由你更新工单状态

  底层词汇层（被上面各 skill 自动取用）：/domain-modeling、/codebase-design、/grilling
  独立工具：/research、/wizard、/resolving-merge-conflicts、/handoff、/wait-what …

上下文卫生：这条链路对"什么时候清空上下文"有明确规定

从 /grill-with-docs 到 /to-tickets 保持在同一个不中断的上下文窗口里（中间不要 compact 或 clear），让访谈、规格、工单建立在同一份思考之上。之后每个 ticket 开一个全新会话跑 /implement，因为 ticket 本身就是自包含的。唯一的约束是 "smart zone"（约 150K token 内模型仍然思路清晰的窗口）：快撞上时，在最近的阶段边界 /compact，不要带病硬撑。

五、逐个 skill：何时触发、做什么、产出什么

1. 想法阶段

/grill-with-docs —— 拷问式访谈 + 顺手沉淀文档（user-invoked）

/prototype —— 用一次性代码回答设计问题（model-invoked）

/research —— 把阅读跑腿活丢给后台 agent（model-invoked）

2. 规格阶段

/to-spec —— 把对话直接合成规格，不再访谈（user-invoked）

3. 工单阶段

/to-tickets —— 拆出 tracer-bullet 工单并声明阻塞边（user-invoked）

4. 实现阶段

/implement —— 极简的工作→反馈→提交循环（user-invoked）

SKILL.md 全文只有几句话，刻意简单：按 spec 或 ticket 实现；在事先约定的接缝处尽量用 /tdd；定期跑类型检查和单测试文件，完整测试套件只在最后跑一次；完成后用 /code-review 评审；提交到当前分支。它是"编排者"，纪律都在它驱动的 model-invoked skill 里。

/tdd —— red → green 循环的纪律参考（model-invoked）

5. 验证与评审阶段

/code-review —— 双轴评审（model-invoked）

6. 入口匝道与配套

/triage —— 把外部 issue 推过状态机（user-invoked）

/diagnosing-bugs —— 硬 bug 的六阶段诊断纪律（model-invoked）

为"第一眼看不出来的 bug、间歇性 flake、两个已知良好状态之间溜进来的回归"准备。核心立场：没有反馈回路，盯着代码看多久都没用。六个阶段：

  1. 构建反馈回路（"这才是这个 skill 的本体，其他都是机械步骤"）：造一条能在这个 bug 上变红的紧致 pass/fail 信号——失败测试、curl 脚本、CLI 快照对比、无头浏览器、流量回放、一次性 harness、属性/fuzz 循环、二分 harness……完成标准是：能说出一条已经跑过至少一次的命令，它 red-capable、确定性、秒级、agent 可无人值守运行。回路不存在之前禁止进入假设阶段。
  2. 复现 + 最小化：确认复现的是用户描述的那个失败（而不是附近的另一个），然后一次砍一个要素，砍到"每个剩余要素都是承重墙"。
  3. 假设：先列 3–5 个可证伪的排序假设（"如果 X 是原因，那么改 Y 会让 bug 消失"），列出来先给用户过目再动手。
  4. 插桩：一次只改一个变量；调试器优先于日志；每条调试日志打唯一前缀（如 [DEBUG-a4f2]），收尾时一次 grep 全部清除。
  5. 修复 + 回归测试：回归测试写在修复之前，但只在存在"正确接缝"时——如果没有能复现真实 bug 模式的接缝，"没有接缝"本身就是发现，记下来，它正是 /improve-codebase-architecture 的输入。
  6. 清理：原始场景不再复现、回归测试通过、调试日志清干净、真正的原因写进 commit/PR 信息。

/wayfinder —— 装不进一个会话的大工程，先画地图（user-invoked）

词汇层与独立工具（速查）

skill定位
/domain-modeling领域建模的主动纪律：挑战模糊术语、用边缘场景压力测试概念关系、当场更新 CONTEXT.md 与 ADR。被 grill-with-docs、triage、wayfinder 驱动
/codebase-design深模块词汇表（module / interface / depth / seam / adapter / leverage / locality）：小接口背后藏大量行为。删除测试、"接口即测试面"、"一个适配器是假想接缝，两个才是真接缝"。/tdd 与 /improve-codebase-architecture 共用
/improve-codebase-architecture扫描代码库找"深化机会"，产出一份自包含的 HTML 可视化报告（写进系统临时目录，不污染仓库），你挑一个候选项后进入 grill 环节。作者建议隔几天跑一次；它是"调查"不是"救援"
/resolving-merge-conflicts逐个 hunk 解决进行中的 merge/rebase 冲突：回溯双方改动的一手来源（commit、PR、原始 issue），按意图解决而不是按行取舍，绝不 --abort
/wizard把"只有人能做的事"（开通基础设施、配凭证和 CI secrets、在第三方后台点点点、一次性迁移）生成成交互式 bash 向导脚本，逐步打开 URL、隐藏输入密钥、幂等写 .env 和 GitHub secrets
/grill-me与 grill-with-docs 同一场访谈，但无状态、不留文件——用于没有仓库的场景。有仓库时永远优先 grill-with-docs
/handoff、/wait-what、/teach、/to-questionnaireproductivity 桶：会话交接文档；一句话没听懂时让 agent 用你的 CONTEXT.md 词汇重讲一遍；跨会话教学；给"唯一知道答案的人"写异步问卷

六、中文示例

以下示例内容按各 SKILL.md 定义的格式翻译/演绎为中文，命令与文件名保持原文。

示例 1：/grill-with-docs 的一轮拷问

背景：你想给博客系统加"草稿"功能。agent 按 grilling 的格式提问——整轮前沿一次问完，每题带推荐答案（❓/➡️ 格式即 SKILL.md 规定格式）：

❓ **Q1** - **草稿的可见性**: 草稿是只对作者可见，
   还是可以通过一个不可猜测的链接分享给他人预览？
   这决定了我们是否需要引入"预览令牌"这个概念。

➡️ 推荐: 先只做作者可见。预览分享是一个独立功能，
   它的权限模型会把这次改动的范围扩大一倍。

---

❓ **Q2** - **"发布"是不是一个独立动作**: 文章从草稿到公开,
   是用户在编辑器里点"发布"按钮的瞬间完成,
   还是需要经过审核队列?

➡️ 推荐: 单动作即时发布。你的仓库里没有任何审核
   相关代码,引入队列会牵扯出通知、角色两个新概念。

---

❓ **Q3** - **术语确认**: 你说"草稿"时,指的是"从未公开
   过的文章",还是也包括"已发布文章的未发布修改"?
   你的 CONTEXT.md 目前只有 Article 这一个概念。

➡️ 推荐: 本次只覆盖前者,并在 CONTEXT.md 里把 Draft
   定义为"从未发布过的 Article"。后者(已发布文章的
   修订)是个更深的模型,值得单独开一次 grill。

你回答后，agent 重算前沿、问下一轮；期间"Draft"一词敲定后会当场写入 CONTEXT.md。若"发布不可撤销、立即公开"这类决策同时满足"难以逆转 + 没有上下文令人惊讶 + 真实权衡"三个条件，agent 会主动提议记成 ADR。

示例 2：/to-spec 产出的规格骨架

## Problem Statement（问题陈述）
博主在正式发布前无法保存半成品文章，关掉编辑器就丢失进度。

## Solution（方案）
为 Article 引入 Draft 状态：作者可以随时保存、回到草稿列表继续编辑，
确认后一键发布。

## User Stories（用户故事，一份极长的编号列表）
1. 作为博主,我想把写了一半的文章存为草稿,以便不会丢失进度
2. 作为博主,我想在草稿列表里看到所有未发布文章,以便选择继续编辑哪篇
3. 作为博主,我想点击"发布"让草稿立即公开,以便读者可以看到
4. ……（覆盖该功能的方方面面,尽可能详尽）

## Implementation Decisions（实现决策）
- 修改的模块: Article 模块增加状态字段（draft / published）; 新增
  DraftList 模块负责草稿的查询
- Article 的接口增加 publish() 动作; 发布即时生效, 无审核队列
- Schema 变更: articles 表增加 status 列, 默认 'published'
  （存量文章全部为已发布）
- （不含具体文件路径与代码片段——它们很快过期）

## Testing Decisions（测试决策）
- 好测试的标准: 只测外部行为, 不测实现细节
- 测试接缝: 在 Article 模块的公开接口这一层测试（唯一接缝,
  已与作者确认）
- 先例: 参照代码库中 orders 模块的接口级测试写法

## Out of Scope（范围之外）
- 草稿的分享预览链接
- 已发布文章的修订版本

示例 3：/to-tickets 拆出的本地 tracer-bullet ticket

本地 tracker 模式下，一个 ticket 一个文件，按依赖顺序编号：

# .scratch/draft-feature/issues/01-draft-crud.md

# 01: 草稿的保存与列表

**What to build:** 博主能把写了一半的文章存为草稿,
并在草稿列表里看到它、点进去继续编辑——从 schema
到 UI 整条路径打通, 功能本身即可演示。

**Blocked by:** None (can start immediately)

**Status:** ready-for-agent

- [ ] 保存一篇只有标题、没有正文的文章后, 它出现在草稿列表
- [ ] 从列表点进草稿能恢复之前的内容并继续编辑
- [ ] 已发布文章不出现在草稿列表中
# .scratch/draft-feature/issues/02-publish-action.md

# 02: 一键发布草稿

**What to build:** 博主在草稿编辑器里点"发布",
文章立即公开可见, 并从草稿列表消失。

**Blocked by:** 01: 草稿的保存与列表

**Status:** ready-for-agent

- [ ] 发布后文章出现在公开文章列表, 携带发布时间
- [ ] 发布后不再出现在草稿列表
- [ ] 发布动作不可撤销地对外可见（无审核队列）

注意每个 ticket 都能回答"做完后能演示什么"，且答案是行为而不是某一层——这是 tracer bullet 与水平切片的分水岭。

示例 4：/tdd 的 red → green 切片

动手前，agent 先停下来确认接缝（铁律：不写未确认接缝处的测试）：

agent: 我打算只在 Article 模块的公开接口这一层测试:
       saveDraft() / listDrafts() / publish() 三个入口。
       不直接测数据库, 不测内部的状态转换函数。
       这个接缝符合你的预期吗?
你:    可以。

然后一个切片一个循环——先红：

// draft.test.ts —— 先写失败测试, 运行, 看它红
test("作者可以把写了一半的文章存为草稿", async () => {
  const article = await saveDraft({ title: "未完成的思考", body: "" });

  const drafts = await listDrafts({ authorId: article.authorId });

  // 期望值来自规格的字面事实, 不是按代码逻辑重算
  expect(drafts).toHaveLength(1);
  expect(drafts[0].status).toBe("draft");
});

再绿：只写刚好让这个测试通过的代码（不预支"发布"功能的任何实现）。绿了以后才写下一个测试（"已发布文章不出现在草稿列表"），再红、再绿。全程没有独立的重构阶段——重构留待 /code-review。

示例 5：/triage 的状态机速览

你:   /triage 让我看看有什么需要我处理的

agent: 【未打标签】（从未分诊, 最旧在前）
       1. #58 [issue] "导出 CSV 时中文乱码" — 2026-09-02
       2. #61 [PR] 外部贡献者: 修复移动端导航折叠
       【needs-triage】
       3. #55 [issue] "希望支持深色模式" — 已初步评估
       【needs-info 且报告者有新回复】
       4. #49 [issue] "偶发登录态丢失" — 报告者 3 天前补充了日志

你:   看看 #58

agent: （复现了乱码, 确认 bug 属实; 在代码库里按领域概念搜索
       发现导出功能已存在于 Export 模块）
       建议: 类别 bug + 状态 ready-for-agent。
       已按你的确认发布 agent brief, 打上标签。
       （评论以 "This was generated by AI during triage." 开头）

七、实践建议

以下全部来自仓库文档（README、docs/ 各页的 Common questions 与 It's working if 一节），是作者和社区已经踩过的坑：

链路顺序与上下文

  1. 从 grill 到 to-tickets 不要 clear/compact。访谈中敲定的大部分共识只存在于对话里（词汇表不收、ADR 门槛高），clear 掉就永远丢了；而且大 spec 从 tracker 取回时可能被截断。同一个窗口跑完 grill-with-docs → to-spec → to-tickets，然后才按 ticket 分会话。
  2. 不确定用哪个 skill，就问 /ask-matt。它是覆盖全部 user-invoked skill 的路由器。
  3. 规模决定入口：一次会话能敲定 → grill-with-docs；一个窗口能装下的构建 → 直接 implement；跨会话 → to-spec + to-tickets；连路都看不清的大工程 → wayfinder。最常见的误用是对范围清晰的功能动用 wayfinder。

质量控制

  1. 拆票过度是 to-tickets 最常被报告的问题。quiz 环节就是给你推回来的地方：让它合并。验收时逐票问一句"做完能演示什么"，答不上来的就是水平切片。还可以在发布前抽查验收标准：每条都要能说出"什么观察会证明它不成立"，并且在实现起点上它应该是红的。
  2. 别把 to-tickets 产的 ticket 再拿去 triage——它们天生 agent-ready；triage 只处理"别人交来的"工作。
  3. implement 不会可靠地关闭或勾选 ticket（GitHub 和本地 Markdown 都一样），ticket 状态由你自己更新。
  4. 在 CLAUDE.md 里声明浏览器/e2e 测试在行为跑通之后再写——否则 agent 可能先写 Playwright 测试，然后在慢循环里空转。
  5. grill-with-docs 依赖 grilling 和 domain-modeling 两个 skill 被正确加载。如果它一次性倒出所有问题、不给推荐答案、也不提 CONTEXT.md，说明依赖没加载上——直接问 agent 它加载了哪些 skill。在别的编排框架（SDD 包装器、多 agent 框架）里内嵌调用它时，有"访谈照跑但文件没落盘"的未修复报告，跑完检查工作目录再信结果。

GitHub 上的已知毛边

  1. ticket 可能没有自动建成 spec issue 的子 issue（issue #554），gh issue create --parent / gh issue edit <parent> --add-sub-issue 可以手动补。
  2. 阻塞关系可能被写成正文文字而非原生 blocking link（issue #513），手动补：gh issue create --blocked-by 12,15。

让 skills 保持锋利

  1. 隔几天跑一次 /improve-codebase-architecture，把"深化机会"变成下一轮 grill-with-docs 的输入。它是调查不是救援——老代码库它能找到真候选，但不会替你解开烂泥。
  2. CONTEXT.md 只是词汇表：别往里塞实现细节、规格或草稿笔记。ADR 只记"难以逆转 + 令人惊讶 + 真实权衡"三者齐备的决策。
  3. skill 是建议性控制，不是强制。文档坦率承认没有指令能让 agent 100% 遵守（有用户追问为何先写实现，模型回答"我知道 skill 说了一次一个测试。我读了。我只是默认了自己的习惯"）。循环即使不被严格执行也值得跑；某个切片要求严格遵守时，盯着跑。

八、与 AI-Native SDLC Playbook 工件链的对应

Playbook 的工件链是 intent.md → spec.md → plan.md → diff+tests → PR+review findings → incident record，强调"每个阶段提交工件、下一阶段读取工件"的循环。mattpocock/skills 的产物可以映射上去，但有两个刻意的"缺口"：

Playbook 环节mattpocock/skills 对应物说明
intent.md（意图）对话本身 + CONTEXT.md / ADR 增量grill-with-docs 沉淀的是词汇与关键决策，不是完整的意图文档；意图的主体留在对话里，由下一步立刻消费。这是它刻意轻量的地方
spec.md（规格）/to-spec 发布到 issue tracker 的规格 issue（ready-for-agent）
plan.md（计划）/to-tickets 的 tracer-bullet ticket 集 + 阻塞边；超大工程则先用 /wayfinder 的决策地图充当前置规划
diff + tests/implement 驱动 /tdd 产出的实现与接口级测试（只测事先约定的接缝）
PR + review findings/code-review 的双轴报告（Standards / Spec 并列呈现）+ 提交
incident record（事故记录）/diagnosing-bugs 收尾时把正确假设写进 commit/PR 信息；被拒绝的增强进 .out-of-scope/ 知识库；架构缺陷回流到 /improve-codebase-architecture

对照 Playbook 的三个控制分层：这套 skills 几乎全部是 skill 层的建议性控制——没有 hook、没有确定性强制，人类审批以"quiz 确认"的形式嵌在 to-tickets 的发布前、tdd 的接缝确认、grilling 的每轮等待里。它不追求 Playbook 式的自动化闭环，而是把"工程师保留控制权"推到底：工件链存在，但每个环节的推进都由人敲下命令。两种立场的取舍本身，就是 AI 原生 SDLC 设计空间里最有意思的一道题。