Matt Pocock Skills 的使用

仓库地址：https://github.com/mattpocock/skills 作者：Matt Pocock（Total TypeScript 作者、前 Vercel 开发者布道师、前 XState 核心团队成员） License：MIT

一分钟速览

• mattpocock/skills 不是框架也不是包，而是一组小而可组合、可任意修改的 Markdown 工作流文件，每个 skill 都能单独拿出来改、组合方式由你自己定、任何模型都能用。
• 每个 skill 是一个 SKILL.md 文件（YAML 头 name + description 加 Markdown 正文），会话启动时只把 name/description 读入内存，相关任务被触发时才加载全文（Anthropic 称之为 Progressive Disclosure），所以装了几十个 skill 初始上下文开销几乎为零。
• 仓库按"谁能调用"把 skills 分成 User-invoked（必须你打 /xxx 才会触发，负责编排流程）和 Model-invoked（你手动调用，或者 agent 自己判断任务匹配时自动触发）两类，铁律是 user-invoked skill 可以调用 model-invoked skill，但绝不能调用另一个 user-invoked skill。
• 安装二选一、不要同时装：Claude Code 插件是只读的订阅式安装，skills.sh 是拷到项目里随便改的拷贝式安装；装完务必勾选 setup-matt-pocock-skills，并在每个仓库跑一次 /setup-matt-pocock-skills 完成配置。
• 整套 skills 围绕四个失败场景设计：需求对齐失败（/grill-me、/grill-with-docs）、缺少项目术语表（共建 CONTEXT.md，/grill-with-docs、/domain-modeling）、缺少反馈回路（/tdd、/diagnosing-bugs）、设计熵增（/to-spec、/improve-codebase-architecture、/codebase-design）。

---

一、这一套 Skill 的摘要

mattpocock/skills 是 Matt Pocock 把自己 .claude 目录里每天真实工程中使用的 agent skills 全部开源出来的仓库。它不是框架、也不是包，而是一组小而可组合、可任意修改的 Markdown 工作流文件。

设计哲学

Matt 在 README 里明确反对 GSD / BMAD / Spec-Kit 这类"接管流程"的框架：流程被框架接管后，你会失去控制权，框架本身出了 bug 你还没法修。这套 skills 反过来——每个 skill 都很小、可以单独拿出来改、组合方式由你自己定、任何模型都能用。用他自己的话说："折腾它们，把它们变成你自己的东西。"

解决的四个失败场景

整个仓库围绕 AI 编程中四个常见的失败模式设计：

#	失败场景	解法	关键 Skill
1	Agent 没做我想要的（需求对齐失败）	在动手前反过来"烤问"用户，把每个分支问清楚	/grill-me、/grill-with-docs
2	Agent 太啰嗦（缺少项目术语表）	共建 CONTEXT.md，沉淀项目"统一语言"	/grill-with-docs、/domain-modeling
3	代码跑不起来（缺少反馈回路）	红绿重构 TDD + 结构化调试循环	/tdd、/diagnosing-bugs
4	越写越像一团泥（设计熵增）	模块"加深"评审、把"统一语言"贯穿到每一层	/to-spec、/improve-codebase-architecture、/codebase-design

Skill 的加载机制

每个 skill 是一个 SKILL.md 文件，YAML 头（name + description）+ Markdown 正文。会话启动时只把 name/description 读入内存，相关任务被触发时才加载全文（Anthropic 称之为 Progressive Disclosure）。所以即便装了几十个 skill，初始上下文开销几乎为零。

调用方式分类

仓库按"谁能调用"把 skills 分成两类：

• User-invoked（用户调用）：必须你打 /xxx 才会触发，负责编排流程。例如 /grill-me、/to-spec、/implement。
• Model-invoked（模型调用）：你手动调用，或者 agent 自己判断任务匹配时自动触发。承载可复用的"纪律"。例如 tdd、diagnosing-bugs、grilling。

一条铁律：user-invoked skill 可以调用 model-invoked skill，但绝不能调用另一个 user-invoked skill。

---

二、安装

三十秒上手

两条路，两种哲学，任选其一，不要同时装（同时装会让每个 skill 出现两份）。

方式 A：Claude Code 插件（订阅式）

整包以只读方式安装，作者一更新你就自动同步，相当于"订阅"他的方法论。

claude plugins install mattpocock-skills

或者在 Claude Code 会话内：

/plugin install mattpocock-skills

它在 Claude Code 官方 marketplace 里，不需要先加源。

方式 B：skills.sh（可编辑拷贝式）

把 skill 文件作为可编辑的普通文件拷到你的项目里，你可以随便改，作者不会在背后动你的版本。需要更新时跑 npx skills update。

npx skills@latest add mattpocock/skills

适用于 Codex、其他 agent，也适用于想要 fork 改造的 Claude Code 用户。安装器会让你勾选要哪些 skill、装到哪些 agent 上。

务必勾选 setup-matt-pocock-skills，这是后面所有配置的入口。

项目级配置

安装完后，在仓库里跑一次：

/setup-matt-pocock-skills

每个仓库只跑一次。它会问你三件事：

1. 用哪个 issue 跟踪器（GitHub Issues / Linear / 本地文件）
2. triage 时用什么标签集合（/triage 会用）
3. 生成的文档（spec / ADR / CONTEXT.md 等）放哪

验证

跑一次 /grill-me，随便挑一个想做的功能，让它拷问你 10 分钟。能感觉到需求被压实的对话过程就说明装好了。

---

三、每一个 Skill 的具体使用场景

下文按官方分类：Engineering 与 Productivity。每条先标出调用方式（User / Model），再给适用场景与"什么时候不要用"。

A. Engineering 类

User-invoked（用户调用）

/ask-matt — 路由器

• 场景：不知道眼前这个活该用哪个 skill。
• 作用：问几个问题，告诉你用哪个 user-invoked skill 最合适。
• 不要用：你心里已经有明确流程时。

/grill-with-docs — 带文档沉淀的烤问

• 场景：要做工程改动，既想把需求问清楚，又想顺手沉淀项目术语表和 ADR。
• 作用：边拷问边把术语更新进 CONTEXT.md，重要决策落成 ADR。
• 不要用：纯非代码场景（写一封邮件、定一个生活决策），用 /grill-me 即可。

/triage — 状态机式 issue 分诊

• 场景：issue 列表堆积如山，需要把它们推过一个"分诊状态机"。
• 作用：按你 /setup-matt-pocock-skills 时配置的标签集，把每个 issue 标注到合适的下一步。
• 不要用：你只有一两个 issue，手动处理更快。

/improve-codebase-architecture — 架构"加深"巡检

• 场景：每隔几天主动巡检 codebase，找出可以"加深"的模块。
• 作用：扫描、生成 HTML 报告列出候选，然后陪你逐条 grill。
• 注意：它是 survey，不是 rescue——在老旧泥球代码库上它能找出真实候选，但不会替你解开泥球。
• 不要用：刚写完的小项目，还没什么可加深的。

/setup-matt-pocock-skills — 配置入口

• 场景：每个仓库跑一次，初始化 issue 跟踪器、标签、文档路径。
• 不要用：已经跑过的仓库。

/to-spec — 直接落 spec

• 场景：当前对话已经聊透了，不需要再拷问一遍，直接把讨论结果凝练成 spec 并发到 issue tracker。
• 不要用：需求还没对齐，应该先 /grill-with-docs。

/to-tickets — 拆 tracer-bullet 工单

• 场景：spec / 计划已经有了，要拆成一组端到端、可独立部署的工单，每张工单自带"阻塞边"声明。
• 作用：避免横向切片（先把所有前端做完再做完所有后端）造成的依赖堆叠。
• 不要用：只有一个原子改动。

/implement — 实现

• 场景：已有 spec 或一组 tickets，要落地代码。
• 作用：按 spec/tickets 干活，在事先约定的"接缝"处自动驱动 /tdd，最后用 /code-review 收尾再提交。
• 不要用：还没 spec，应该先 /to-spec。

/wayfinder — 大型工作拆解

• 场景：一个会话装不下的巨型工作（大型重构、跨季度迁移）。
• 作用：把工作映射为 issue tracker 上的"决策工单"图，一次解决一个决策，直到通往目的地的路径清晰。
• 不要用：能在单会话搞定的任务。

Model-invoked（模型可自动调用）

prototype — 一次性原型

• 场景：需要快速验证一个设计问题。
• 作用：状态/逻辑问题 → 单个可分享 HTML 文件；UI 问题 → 在同一路由下可切换的多个差异化 UI 变体。
• 不要用：要进生产的代码。

diagnosing-bugs — 结构化调试

• 场景：复杂 bug 或性能回归，光看代码看不出来。
• 作用： disciplined loop：搭一个"在本 bug 上变红"的反馈回路 → 最小化复现 → 假设 → 插桩 → 修复 → 回归测试。每阶段相位把关。
• 不要用：一眼就能看出来的 typo 类 bug。

research — 调研

• 场景：要对某个问题查高可信一手资料，并把结论留在仓库里。
• 作用：作为 background agent 运行，最终产出带引用的 Markdown。
• 不要用：随便百度一下就能回答的问题。

tdd — 测试驱动

• 场景：加功能或修 bug 时，强制 red-green-refactor。
• 作用：先写失败的测试，再写最小实现，再重构。每次一个垂直切片。
• 不要用：纯探索性 spike（用 prototype）。

domain-modeling — 领域建模

• 场景：项目术语不稳定、容易漂移。
• 作用：主动挑战 glossary、用边界场景压测术语、把更新写回 CONTEXT.md 和 ADR。
• 不要用：一个人写一周就丢的项目。

codebase-design — 深模块设计纪律

• 场景：设计新模块或重构旧模块的接口。
• 作用：共享一套"深模块"词汇——大量行为藏在很小的接口后面，放在干净的接缝处，通过接口可测。
• 不要用：临时的 throwaway 脚本。

code-review — 双轴 code review

• 场景：自某个固定点以来的 diff 要审。
• 作用：两个并行 sub-agent：Standards 轴（是否符合仓库编码规范 + Fowler 坏味道基线）、Spec 轴（是否忠实实现原 issue/spec）。并行跑互不污染。
• 不要用：还没形成 diff 的阶段。

resolving-merge-conflicts — 解 merge 冲突

• 场景：git merge / rebase 进行中遇到冲突。
• 作用：按 hunk 逐段处理，按"每一边的主源"追溯真实意图来决策，最后完成操作。绝不 --abort。
• 不要用：想直接放弃这次合并时。

wizard — 人机协作 bash 向导

• 场景：有些步骤只能人来做（开通基础设施、配 CI secrets、走第三方后台、跑一次性迁移）。
• 作用：生成交互式 bash 向导，一步一步带人做。
• 不要用：纯代码可以搞定的步骤。

B. Productivity 类

User-invoked

/grill-me — 纯烤问（非代码）

• 场景：要做非代码决策（写一篇文章、做一个生活决策、构思一个产品 idea），想让 agent 把每个分支都问清楚。
• 作用：无情采访，直到设计树的每一条分支都被解决。
• 不要用：工程改动（用 /grill-with-docs，会顺手沉淀文档）。

/handoff — 会话交接

• 场景：当前会话要结束、要交给下一个 agent 继续。
• 作用：把当前对话压缩成交接文档。
• 不要用：单会话就能搞定的任务。

/teach — 多会话教学

• 场景：要学一个新技能或概念，需要多次会话推进。
• 作用：把当前目录当有状态的教学工作区，跨会话带你学。
• 不要用：一问一答就能解决的疑问。

/to-questionnaire — 反向问卷

• 场景：有一个决策你一个人答不了，要问唯一能答的那个人。
• 作用：把它变成一份 Markdown 问卷，可异步填，也可会议同填。它拷问你"发送方"（给谁的、要回什么），不拷问主题本身。
• 不要用：你自己就能答的决策。

/wait-what — 重新表达

• 场景：刚才那条消息没听懂/没落地，立刻开火。
• 作用：用你缺失的上下文重新讲一遍，用 CONTEXT.md 的术语讲人话。
• 不要用：你已经懂了，只是想深挖。

Model-invoked

grilling — 可复用采访原语

• 场景：被 grill-me、grill-with-docs、triage、wayfinder、improve-codebase-architecture 共用的内核。
• 作用：无情采访用户直到设计树每条分支被解决。
• 不要用：直接调用它（应该用上面五个 user-invoked 封装）。

writing-for-agents — 给 agent 写文档

• 场景：写 SKILL.md、AGENTS.md/CLAUDE.md、以及任何被 agent 通过指针取到的文档。
• 作用：约束文档写得"agent 能稳定理解"。
• 不要用：写给人看的纯散文。

---

四、实战案例

下面用一个完整的端到端流程串起来，从"想做功能"到"提交 PR"，对应每一步该用哪个 skill。设定：你在做一个 TypeScript 课程视频管理后台（参考 Matt 自己的 course-video-manager 仓库），现在要加一个"视频转码队列"功能。

步骤 0：第一次进仓库

/setup-matt-pocock-skills

回答三个问题：issue tracker 选 GitHub Issues；triage 标签集填 needs-spec / ready / in-progress / blocked；文档放在 docs/。

步骤 1：先别写代码，先烤问

/grill-with-docs

目标："加一个视频转码队列"。让 agent 反过来拷问你：

• 队列是单进程内存的还是基于 Redis？
• 失败重试几次？退避策略？
• 是否要在 UI 实时显示进度？
• "转码"这个词在项目里叫什么？和"渲染"是一回事吗？

agent 把每个术语写进 CONTEXT.md，例如：

- Transcode: 将源视频转码为多分辨率 H.264。不要叫"渲染"。
- Queue: 基于 BullMQ 的持久化队列，不是 in-memory。

关键决策（比如"BullMQ + Redis"）落成 docs/adr/0001-transcode-queue.md。

步骤 2：把对话凝成 spec

/to-spec

不再采访，直接把刚才的对话凝成一份 spec，发布为 GitHub Issue #42。

步骤 3：拆 tracer-bullet 工单

/to-tickets

拆成一组端到端、可独立部署的工单：

• #43 队列骨架：能 enqueue 一个 dummy job、worker 能消费（DB + Redis 配好）
• #44 转码逻辑接 ffmpeg（依赖 #43）
• #45 UI 进度条挂到 job 事件流（依赖 #43）
• #46 失败重试与死信（依赖 #43）

每张工单都声明阻塞边，避免横向切片。

步骤 4：实现 + TDD

/implement

agent 按 #43 干活，在事先约定的"接缝"（比如 enqueueTranscode() 这个纯函数）自动驱动 /tdd：

1. Red：写 enqueueTranscode() 的失败测试——断言入队后 BullMQ 里有一条 job。
2. Green：写最小实现让测试过。
3. Refactor：把"入队"和"序列化参数"分开，加深模块。

每完成一张工单，/implement 自动用 /code-review 收尾，跑 Standards + Spec 双轴评审，过了再提交。

步骤 5：当 agent 输出跑不通

假设 #44 接 ffmpeg 时偶发 SIGTERM，agent 一通乱试。这时手动触发：

/diagnosing-bugs

按 disciplined loop：

1. 搭一个"在本 SIGTERM 上变红"的反馈回路（一个能复现的最小 job）。
2. 最小化复现路径。
3. 假设：ffmpeg 子进程被 OOM killer 杀掉。
4. 插桩：在 worker 里加 docker stats 采样。
5. 修复：给 ffmpeg 加 memory limit + 转码参数降分辨率。
6. 回归测试：把最小复现 job 加进 e2e 套件。

步骤 6：隔几天巡检架构

每周或每两周跑一次：

/improve-codebase-architecture

它扫出一份 HTML 报告，列出可以"加深"的候选。比如它可能指出 TranscodeService 既管队列又管 ffmpeg 调用，是个浅模块。你选一条，agent 陪你 grill 这一条要不要拆、怎么拆，最终落到 ADR。

步骤 7：超大迁移用 wayfinder

半年后要把整个队列从 BullMQ 迁到 SQS。这不是一个会话能装下的：

/wayfinder

它把这次迁移映射成一组决策工单：

• #200 是否需要双写期？
• #201 SQS 的可见性超时怎么定？
• #202 如何回滚？

一次解决一个决策，直到通往 SQS 的路径清晰。

步骤 8：会议中有人提了"再加一个 Webhook" 的需求

会议当场你想确认你理解对了，开火：

/wait-what

agent 用 CONTEXT.md 的术语重新讲一遍，把"Webhook 是 push 给外部、和现有 Progress 事件流不是一回事"这个区别讲清楚。

步骤 9：会话太大要换 agent

/handoff

把当前对话压缩成交接文档，下一个 agent 接着干。

---

一句话总结每步对应的 skill

步骤	Skill	类别
仓库初始化	/setup-matt-pocock-skills	Engineering / User
需求烤问 + 沉淀术语	/grill-with-docs	Engineering / User
落 spec	/to-spec	Engineering / User
拆 tracer-bullet 工单	/to-tickets	Engineering / User
实现 + TDD	/implement + tdd	Engineering / User + Model
Code review 收尾	code-review	Engineering / Model
调试 hard bug	diagnosing-bugs	Engineering / Model
架构巡检	/improve-codebase-architecture	Engineering / User
大型迁移规划	/wayfinder	Engineering / User
没听懂时重新表达	/wait-what	Productivity / User
跨会话交接	/handoff	Productivity / User
不知道用哪个	/ask-matt	Engineering / User

---

五、上手路线（半小时体验）

按官方推荐的"上手感"顺序：

1. /grill-me —— 任意挑一个想法，让它拷问你 10 分钟。
2. /grill-with-docs —— 换成工程场景，看 CONTEXT.md 怎么自己长大。
3. /tdd —— 跑一个小需求，观察 red-green-refactor 的节奏。
4. /implement —— 配合 spec 或 ticket 批量干活。
5. （可选）/wayfinder —— 任务大到单会话装不下时用。

全部走完大概一小时，前五步半小时内能体验完。

---

常见问题（FAQ）

mattpocock/skills 和 GSD、BMAD、Spec-Kit 这类框架该怎么选？

这套 skills 明确反对 GSD / BMAD / Spec-Kit 这类"接管流程"的框架。Matt Pocock 在 README 里的理由是：流程被框架接管后，你会失去控制权，框架本身出了 bug 你还没法修；而 mattpocock/skills 的每个 skill 都很小、可以单独拿出来改、组合方式由你自己定、任何模型都能用。

这些 skill 只能在 Claude Code 里用吗？

不是，Claude Code 只是它的两种安装方式之一。方式 A（claude plugins install mattpocock-skills）是 Claude Code 专用的只读订阅式安装；方式 B（npx skills@latest add mattpocock/skills）适用于 Codex、其他 agent，也适用于想要 fork 改造的 Claude Code 用户，安装器还会让你勾选要哪些 skill、装到哪些 agent 上。

User-invoked skill 和 Model-invoked skill 有什么区别？

User-invoked skill 必须你打 /xxx 才会触发，负责编排流程；Model-invoked skill 则是你手动调用、或者 agent 自己判断任务匹配时自动触发，承载可复用的"纪律"。两者之间有一条铁律：user-invoked skill 可以调用 model-invoked skill，但绝不能调用另一个 user-invoked skill。

Claude Code 插件和 skills.sh 这两种安装方式可以同时用吗？

不可以，任选其一，不要同时装，因为同时装会让每个 skill 出现两份。Claude Code 插件是整包只读安装、作者一更新你就自动同步的"订阅"方式；skills.sh 则是把 skill 文件作为可编辑的普通文件拷到你的项目里，你可以随便改，作者不会在背后动你的版本。

装了几十个 skill，会不会一开始就把上下文占满？

不会，因为这套 skill 采用 Progressive Disclosure 的加载机制。每个 skill 是一个 SKILL.md 文件（YAML 头 name + description 加 Markdown 正文），会话启动时只把 name/description 读入内存，相关任务被触发时才加载全文，所以即便装了几十个 skill，初始上下文开销几乎为零。

不知道该用哪个 skill 的时候怎么办？

直接调用 /ask-matt 这个路由器。它会问你几个问题，然后告诉你眼前这个活该用哪个 user-invoked skill 最合适；如果你心里已经有明确流程，就不需要用它的。