本文内容均基于官方仓库
docs/目录下的 22 篇技能说明文档整理，用于说明「什么时候用这些技能」以及「怎么用效果最好」。
mattpocock/skills 是 Matt Pocock 每日用来做真实工程开发（而非"氛围编程 / vibe coding"）的一套 AI 编程智能体（agent）技能集。
它的设计哲学可以用一句话概括：小巧、易于改造、可组合、适用于任何模型。它不试图"接管你的流程"（像 GSD / BMAD / Spec-Kit 那样），而是把数十年工程经验浓缩成一组可复用的"纪律 / 规范"，交还你对流程的掌控权。
核心主张：软件工程的基本功（对齐、共享语言、反馈回路、代码设计）在 AI 时代比以往更重要，而不是更不重要。 这套技能就是为补上 AI 编程最常被忽视的基本功而生。
文档把技能沿两个维度组织，理解它们是用好整套系统的基础。
| 类型 | 触发方式 | 职责 |
|---|---|---|
| 用户调用型（User-invoked） | 你主动输入命令，如 /grill-me |
做"编排"，是流程的入口 |
| 模型调用型（Model-invoked） | 你或智能体都能触发，任务契合时智能体会自动调用 | 承载可复用的"纪律 / 规范" |
重要规则：一个用户调用型技能可以调用模型调用型技能，但绝不能调用另一个用户调用型技能。这样保证流程不会失控、不会重复。
文档反复强调一个概念：flow（流程）——是"穿过一组技能的路径"，而不只是单个技能。整个仓库的能力被组织成：
-
一条主构建流程（main flow）：从想法到上线
grill-with-docs → to-spec → to-tickets → implement → code-review -
两条汇入车道（on-ramps）：从两侧并入主流程
- triage 车道：处理"别人提交进来的 bug / 需求"（问题追踪系统里已有的东西）
- codebase-health 车道：定期体检，发现"该重构哪里"（生成想法）
-
一堆独立工具（standalone）：随时单独调用，不属于任何链路
不确定用哪个时，任何技能文档都会指向
/ask-matt——它是整个仓库的"路由器"，描述你的处境，它就告诉你该用哪个技能、什么顺序。
这是整张工程技能网的地基，每个仓库只需跑一次，且必须在任何其它工程技能之前跑。
它做什么：用对话式引导，把"这个仓库的工程技能该怎么行为"写成配置（不是硬编码行为），写到 docs/agents/ 下：
issue-tracker.md：问题追踪系统（GitHub / GitLab / 本地 markdown / 其它）domain.md：领域文档放在哪（默认根目录一个CONTEXT.md+docs/adr/）triage-labels.md：分诊标签（仅当装了 triage 时）
它智能推断后只跟你确认关键项：比如根据 git remote 推荐追踪系统、保留默认标签（needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix）等。日常微调只是改 docs/agents/*.md，无需重跑。
效果最好的用法：新仓库拉下来后，第一件事就是 /setup-matt-pocock-skills，把它当"开工仪式"。之后 triage、to-spec、to-tickets 才知道往哪写、用哪些标签。
这是最核心的链路。何时用：当你"有一个自己想做的改动"时，沿这条链路走。
做什么：一次只问你一个问题，沿"决策树"逐枝走，直到你和智能体达成共享理解；并且边问边落笔——把术语写进 CONTEXT.md 词汇表，把难以回退的决策写成 ADR（docs/adr/）。
何时用：一个改动刚开始、方案还模糊、领域语言还没定，想在写任何代码前先把两者都逼清晰时。
如何用最好：
- 它是有状态的（会写文件），所以要在"可以安全写这些文件"的地方跑。
- 能靠读代码回答的问题它自己会去读，不会拿空白问题烦你；每个问题都附带智能体自己的推荐答案，你是在"对一个提案做反应"。
- 词汇表只放术语、不放实现细节；ADR 只在"难回退、脱离上下文会令人意外、且是真实权衡"时才写——大多数会话只产出更锋利的词汇表，几乎没有 ADR，这正是正确的形态。
对照：
/grill-me是同一个拷问，但无状态（什么文件都不写，只留在对话里）；/grilling是底层"拷问原语"，模型调用型，其它技能共用它而非各自再造。只想拷问不想要文档产物时用grill-me。
做什么：把当前对话 + 代码理解综合成一份规格说明（spec / PRD），发布到问题追踪系统。它不再访谈你——对齐工作在上一步已完成，这里只做"综合"。
何时用：方案谈透了、领域语言定了，想在写代码前把共享理解落盘时。
规格说明包含：问题陈述、解决方案（高层形态）、用户故事（可逐条独立验证）、已确定的实现决策、测试决策（在哪个 seam 测、怎样算完成）、范围外事项、补充说明。
如何用最好：它发布时自带 ready-for-agent 标签，无需再单独 triage。动手前先勾画"特性将在哪些 seam（接缝） 上被测试"，并寻找深模块机会——好接口给测试一个稳定目标，下面的代码怎么变测试都不用动。
若还没对齐，先回去
grill-with-docs。要进一步拆成工单，接/to-tickets。
做什么：把计划 / 规格 / 对话拆成一组工单，每个都是垂直切片（tracer bullet）——一刀切穿所有集成层（schema、API、UI、测试）的细窄端到端切片，而非只切某一层。
何时用：已有共识计划或写好的规格，想拆成工单时。
如何用最好：
- 垂直切片，不是水平切片：水平切片一次只交付一层（比如所有 schema），在每层都落地前啥都用不了；垂直切片一次打通一条窄路径，做完即可演示。这正是"工单可以放心交给智能体"的原因。
- 拆之前先想 prefactoring（"先让改动变容易，再做那件容易的事"），把它排最前。
- 工单之间声明阻塞边（blocking edges）：本地文件模式下写成文本、按阻塞顺序编号；真实追踪系统（GitHub / Linear）下变成原生阻塞链接——所有阻塞已完成的工单处于 frontier（前沿），可被认领，于是多个智能体可并行。
- 特例——wide refactor（大规模重构）：当一次机械改动（重命名列、改共享符号类型）影响面波及全代码库、没有任何垂直切片能单独变绿时，改用 expand–contract（扩展–收缩）：先并排扩出新形态→分批迁移调用点（CI 全程绿）→最后删旧形态。
它只生产"工件"，怎么跑（手工顺序、还是并行舰队）由你定。
做什么：按规格 / 工单构建，内部驱动 TDD、类型检查、全套测试，再交给 code-review 并最终提交到当前分支。它不决定"做什么"——那是上游的事，它是"手"不是"脑"。
何时用：工作已写成规格或拆成工单，准备变成代码时。
如何用最好：它运行在预先约定的 seam 上——不中途现造接缝，而是用 to-spec 时已选好的接口，通过 tdd 写测试。围绕核心保持紧凑循环：频繁类型检查、边写边跑单测文件、最后跑全套，再以 review 收尾并提交。
做什么：对你给定的固定点（HEAD、某 commit / 分支 / tag / merge-base）与此点之间的 diff，沿两条互相独立的轴审查：
- Standards 轴：代码是否遵循本仓库文档化的规范（加一套固定的 ~12 个 Fowler 坏味道基线：神秘命名、重复代码、特性嫉妒、数据泥团……）。有文档的仓库规范永远覆盖基线；每个坏味道都是"判断"而非硬性违规。
- Spec 轴：代码是否真的实现了源头 issue / spec 要求，有没有漏需求或夹带范围蔓延。
两条轴作为并行子智能体运行，报告并排呈现，绝不合并——因为一次改动可能过一轴败一轴，混在一起会让一条掩盖另一条。
何时用：有 diff 要对照已知良好点评判时（审分支、审 PR、审进行中的改动、"自 X 以来"的东西）。
如何用最好：Spec 轴需要能找到源头 spec（commit 里的 issue 引用、你传入的路径、或 docs/·specs/ 下的 spec）；找不到时它明确报"无 spec"而非瞎编需求。Standards 轴什么都不依赖，哪怕仓库没写规范也自带 Fowler 基线。
做什么：把追踪系统里的原始、未评估的报告，推过一个小型状态机——分类、核实声明、必要时拷问成形、留下 ready-for-agent 简报。每个被处理项恰好带一个类别角色（bug / enhancement）和一个状态角色（needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix）。它永远先推荐并等你确认，绝不盲目标。
何时用：追踪系统里堆积了未评估报告，想把它们分拣、核实、变成"人或智能体可认领的工作"时。
如何用最好（关键）：
- 先核实再出简报：bug 按报告步骤复现、PR 拉下来跑测试，再回报"已确认 / 失败 / 信息不足"。信息不足本身就是强
needs-info信号。 - 跑两个代码库检查：冗余性（已实现？那是
wontfix）、既往拒绝（.out-of-scope/已说 no？）。 - PR 就是"带代码的 issue"：外部 PR 走同一台状态机，只是状态对照 diff 而非报告。
- 每条发到追踪系统的评论都以
> *This was generated by AI during triage.*免责声明开头。
这是"反向"流程：处理追踪系统里已有的东西，而
to-spec是从新对话往追踪系统里填充。
做什么：扫描代码库寻找深化（deepening）机会——把浅模块（接口几乎和它所隐藏的东西一样复杂）变成深模块——把它们呈现为一份自包含的可视化 HTML 报告，然后对你选中的那个做拷问式推进。
何时用：作为定期健康检查的维护动作——每隔几天跑一次，或当代码库开始让人"为了理解一个概念要在小模块间反复横跳"时。
如何用最好：
- 它用**删除测试（deletion test）**过滤候选：删掉这个模块，复杂度是"集中到更小接口后"还是"只是被搬了家"？只取"集中"的情况——这避免了报告退化成泛泛的清理建议。
- 默认聚焦"开发实际落点"：读近期 commit，偏向你仍在改的代码（深化它回报最大）。
- 报告写到操作系统临时目录，不进仓库；每张卡片含涉及文件、摩擦、白话方案、 locality/leverage 收益、前后对比图、以及
Strong/Worth exploring/Speculative徽章。然后它停下问你想探索哪个——选中后对它跑grilling决策树，边定边更新领域模型。
若你已经知道要重设计哪个模块、只缺措辞思考，直接用
/codebase-design（它是"设计工作台"，本技能是"发现候选的勘察"）。
/diagnosing-bugs（模型可调用）：针对难解 bug 和性能回退的规范化诊断循环——复现→最小化→假设→插桩→修复→回归测试。核心心法：先有"紧反馈回路"再谈假设——一个能在本 bug 上变红的、可运行的命令。它把大量精力花在 Phase 1 构造并收紧这个复现命令（快、确定、智能体可跑），因为"30 秒的偶发循环"几乎等于没有。非确定 bug 的目标是提高复现率而非干净复现。/resolving-merge-conflicts（模型可调用）：逐个 hunk 推进进行中的 git merge / rebase 冲突，按意图而非按文本解决——动 hunk 前先回溯每侧到其第一手来源（commit message、PR、原始 issue）理解"为什么改"，兼容时保留双侧意图，绝不为了消除标记而现编行为，也绝不用--abort，一定把操作跑到提交完成。
/research（模型可调用）：只从第一手来源（官方文档、源码、规范、第一方 API，绝不要二手转述）回答问题，把发现写成一份带引用的 Markdown 文件。关键是作为后台子智能体运行：你继续干活，它去把每个论断追到源头，丢回一份你可反应的文档。/prototype（模型可调用）：造一个从第一天起就是一次性的小程序，只为回答一个设计问题（状态模型对不对？UI 长啥样？）。两分支：逻辑/状态问题→可交互终端小程序；UI 问题→同一路由下多个天差地别的变体用浮动条切换。原型本身是第一手来源——答案捕获后，把验证过的决策并入真代码，原型留在临时分支（不进 main、永不合并）并留个上下文指针；main 分支保持干净，原始探索随时可重跑。/teach：把当前目录变成常设"教学工作区"，跨多个会话教你一个主题。有状态（记住你学了啥）、基于**存储强度（storage strength，长期 retention）而非流利度（fluency，当下回忆的错觉）、按最近发展区（zone of proximal development）**出难度恰好的课。适合"学习是个项目"的场景，不适合一次性答疑。
/domain-modeling（模型可调用）：主动构建并打磨项目的通用语言（ubiquitous language）——挑战模糊术语、用具体场景压测关系，术语一确定就写进CONTEXT.md、决策写进docs/adr/。词汇表 vs ADR 有不同门槛：ADR 只在"难回退 + 脱离上下文令人意外 + 真实权衡"三者皆备时才写。它的杀手锏：你说"某功能如何工作"时，它对照代码指出矛盾（"你的代码取消整个 Order，但你刚说允许部分取消——哪个对？"），逼语言与代码一致。/codebase-design（模型可调用）：提供设计深模块的共享精确词汇（module / interface / depth / seam / adapter / leverage / locality）。它是语言不是流程——不替你重构，只统一措辞，让每次设计对话说同一种话。深模块=大量行为藏在极小接口后；用删除测试和"一个 adapter=假设接缝，两个 adapter=真实接缝"来判断。
/grilling（模型可调用）：底层"拷问原语"，决策树逐节点下降，单次单问、按依赖顺序——这是grill-me和grill-with-docs共用的引擎。/wayfinder：当工作量大到一次智能体会话装不下、且通往目标的路还笼罩在"战争迷雾"中时，把它绘成追踪系统上的一组决策工单地图，逐个解决直到路清晰。它只规划不执行——每个工单解决一个"待定决策"而非"待执行切片"。地图是索引不是仓库；雾（fog）是能感觉到但还定不下来的决策；前沿（frontier）是开放、未阻塞、未认领的工单。HITL（人在环，拷问/原型）工单必须经实时交互解决，智能体绝不自答；AFK（智能体独做，如 research）工单可并行烧。/handoff：把当前对话压缩（compaction）成一份交接文档（存到 OS 临时目录，不进工作区），让新智能体能接手。只带"活线程"（在做什么、为什么、下一步），其余用路径/URL 引用而非复制；写入前脱敏（API key、密码、PII 剥离）。/writing-great-skills：写 / 改技能时的元参考。根 virtue 是可预测性（predictability）——目标不是每次输出相同，而是每次过程相同。关键概念是认知负荷（cognitive load） vs 上下文负荷（context load）：模型调用型技能每轮都占上下文但能自触发；用户调用型零上下文负荷但"你得记住它存在"——这正是本仓库大量用用户调用型、并配ask-matt路由器来化解认知负荷的原因。还讲了 leading words（预训练里已有的紧凑概念，如 tight / red / tracer bullet）、渐进式披露、剪枝、失败模式（ premature completion / duplication / sediment / sprawl / no-op）。
- 新仓库第一步永远先
/setup-matt-pocock-skills，否则下游技能会瞎猜追踪系统和标签。 - 每次动手前都先对齐：模糊方案用
grill-with-docs（想要文档产物）或grill-me（只想要对话里的共识）。这是整套系统最受欢迎、回报最高的环节，别跳过。 - 让共享语言活起来：
CONTEXT.md词汇表 +docs/adr/ADR 是跨会话的资产，越用越省 token、越易导航。 - TDD 一次只写一个测试：红→刚够绿的代码→下一个，绝不要"先写一堆测试再写一堆代码"。测试只针对公开接口，期望值来自独立事实源（spec / 已知好值），别用和代码相同方式算出来的值（那会造出"同义反复"的假绿测试）。
- 拆工单用垂直切片（探路子弹），不是水平切片；真实追踪系统下利用阻塞边做并行 frontier。
- 大规模重构走 expand–contract，别硬塞进垂直切片。
- code-review 始终跑双轴，并且要提供源头 spec 给 Spec 轴，否则它只能审 Standards。
- triage 先核实再出简报：bug 不先复现、PR 不先跑，就别进
ready-for-agent。 - debug 先造"会变红的复现命令"，再谈任何假设；没有紧反馈回路就不诊断。
- 架构体检每隔几天跑一次
improve-codebase-architecture，用删除测试判断该深化哪个模块。 - merge 冲突按意图解，回溯第一手来源；绝不
--abort，一定跑到提交完成。 - 不确定就用
/ask-matt路由；长会话靠/handoff交接，避免上下文丢失。
| 你的处境 | 用这个 |
|---|---|
| 新仓库，从没配置过工程技能 | /setup-matt-pocock-skills（一次性） |
| 有想法但方案模糊、领域语言没定 | /grill-with-docs（要文档）或 /grill-me（只对话） |
| 方案谈透了，想写成规格 | /to-spec |
| 有规格，想拆成可并行工单 | /to-tickets |
| 工单就绪，准备写代码 | /implement（内部驱动 /tdd） |
| 改完了想审（"实现得对不对"+"是不是该做的事"） | /code-review |
| 追踪系统里堆了未评估的 bug / 需求 / PR | /triage |
| 代码库变"泥球"，想找该深化的地方 | /improve-codebase-architecture |
| 有个具体行为想测试先行地做 | /tdd |
| 难解 bug / 性能回退 / 偶发 flake | /diagnosing-bugs |
| 进行中的 merge / rebase 卡在冲突 | /resolving-merge-conflicts |
| 想搞清楚"某 API 到底怎么行为"（要查资料） | /research |
| 设计问题拿不准（状态模型 / UI 长相） | /prototype |
| 工作量超大、路线图还雾蒙蒙 | /wayfinder |
| 术语打架、概念没被精确命名 | /domain-modeling |
| 想设计/改进模块接口、找接缝 | /codebase-design |
| 会话太长怕丢上下文 / 要交给别的智能体 | /handoff |
| 想跨会话系统学一个主题 | /teach |
| 想写 / 改技能本身 | /writing-great-skills |
| 完全不确定从哪开始 | /ask-matt（路由器） |
- 作为可编辑技能（推荐，可改造）：
npx skills@latest add mattpocock/skills，安装时务必勾选/setup-matt-pocock-skills，然后在智能体里跑它。 - 作为 Claude Code 插件（只读、自动更新）：
/plugin marketplace add mattpocock/skills然后/plugin install mattpocock-skills@mattpocock。 - 单个技能也可独立安装 / 更新，例如：
npx skills add mattpocock/skills --skill=tdd与npx skills update tdd。
小结：这套技能的本质，是把"对齐、共享语言、反馈回路、代码设计"这些被 AI 编程最容易跳过的基本功，固化成一组可组合、可预测、你始终掌舵的流程。把它当"工程纪律的脚手架"而非"黑盒自动化"，效果最好。