把一个需求交给 Claude Code 或 Codex,写出代码只是其中一步。需求没讲清楚,后面就会反复改。任务太大,一个会话聊不完,下个会话还要重新解释。到了验收,又得回答那个绕不开的问题——凭什么说它已经做好了?
mattpocock-skills 把这些工作分别交给不同的技能处理,再将它们接成流程。你可以让助手追问需求、整理规格、拆分任务、按测试推进实现,也可以单独调用诊断、评审、调研或交接技能。
这套技能由 Matt Pocock 维护,面向使用编程助手做真实项目的开发者。Skill 在这里是一份助手可以读取并执行的工作规程,规定要做哪些动作、留下什么产物、什么时候进入下一步。执行能力仍然来自 Claude Code、Codex 和你的项目环境。
本文按项目 v1.2.3 的技能集合展开,安装方法采用仓库当前的安装说明。
读完这篇,你应该能做三件事:把技能配置到一个项目里,为手里的问题选对入口,并沿着一条适合它的流程做下去。
先看全貌:你手里的工作应该从哪里开始
不用先背下所有技能。先判断你现在卡在哪一步。
flowchart TD
A[手里来了一件工作] --> B{现在最需要解决什么}
B -->|不知道该选哪个技能| R[ask-matt 推荐入口]
B -->|需求还没想清楚| G[grill-with-docs 澄清需求]
B -->|小改动且要求明确| I[implement 实现]
B -->|已有疑难故障| D[diagnosing-bugs 诊断]
B -->|外部反馈堆积| T[triage 分诊]
B -->|项目太大且方向模糊| W[wayfinder 建决策地图]
B -->|代码越来越难改| H[improve-codebase-architecture 找改进机会]
G --> S[to-spec 形成规格]
W -->|关键决策已明确| S
S --> K[to-tickets 拆解工单]
K --> I
T -->|形成可执行工单| I
H -->|选定改进项| G
I --> V[tdd 与 code-review]
V --> F[处理发现并提交]
图里的箭头表示工作如何衔接。需要人手动调用的技能,仍然由你启动,不能把这张图理解成输入一次命令就会自动跑完全部步骤。
实在拿不准,就先找 ask-matt。给它当前目标、已有材料和卡住的地方,它会推荐合适的入口。它承担的是导航职责,选择之后再调用相应技能。
安装只做一次,项目配置要分别做
这里有两个不同的动作。安装让助手拥有这些技能,配置让技能知道这个项目的任务和文档应该放在哪里。
Claude Code:安装插件
在终端执行:
claude plugins install mattpocock-skills
也可以在 Claude Code 会话里执行:
/plugin install mattpocock-skills
Codex 或其他兼容助手:通过 skills.sh 安装
在终端执行:
npx skills@latest add mattpocock/skills
安装器会让你选择技能,以及安装到哪个编程助手。请把 setup-matt-pocock-skills 一并选上,后面要用它配置项目。
如果只准备试一个技能,可以按名称安装:
npx skills@latest add mattpocock/skills --skill=grill-with-docs
不过,组合流程还会使用其他技能。刚上手想跑通完整流程,选择整套更容易避免缺少依赖。采用 skills.sh 安装的单个技能,可按项目给出的方式更新:
npx skills@latest update grill-with-docs
插件和 skills.sh 两条安装路线选一条。
怎么调用,先认清两种技能
有些技能必须由你明确点名(显式调用),负责决定工作进入哪个阶段。有些技能允许助手在任务匹配时自行使用,也可以由你点名使用。
本文把前者标成「手动」,后者标成「可自动」。可自动不等于每次必然触发;某一步必须使用哪个技能时,直接说明最清楚。
调用时,先从助手的技能选择器选中目标技能,再输入需求。文章后面会用「使用某技能……」展示要发送的内容。
安装后的第一项检查也很简单:在目标助手中确认能找到 setup-matt-pocock-skills 和 ask-matt。入口没有出现,就还没到执行流程的阶段。
第一次进入项目,配置三件事
打开你准备开发的项目,调用 setup-matt-pocock-skills。它会先查看项目已有约定,再展示建议和拟写入的内容,经过确认后保存。
flowchart LR
A[打开目标项目] --> B[运行 setup-matt-pocock-skills]
B --> C[检查已有约定]
C --> D[确定任务存放位置]
D --> E[按需确定分诊标签]
E --> F[确定业务文档布局]
F --> G[展示草稿并确认]
G --> H[保存配置供后续技能读取]
你需要理解的选择有三个。
配置项 | 实际决定什么 | 怎么选择 |
|---|
任务跟踪方式 | 规格、工单、进度和讨论放在哪里 | 团队已经用 GitHub 或 GitLab,就沿用;个人项目可选本地 Markdown |
分诊标签 | 用什么名称表示待处理、缺信息、可交给助手等状态 | 已安装 triage 才配置;已有团队标签就映射到原名称 |
业务文档布局 | 业务术语和重要决策保存在哪里 | 一般项目用一套共享文档;确有多个业务上下文的大型仓库再考虑分开 |
GitHub 方案通过 gh 操作,GitLab 方案通过 glab 操作。相应工具需要能够访问目标仓库。选择 Jira、Linear 等其他系统时,你要把实际操作方式告诉它;配置会记录这种约定,外部工具的访问能力还需要环境提供。
如果你只想在个人项目里试用,可以这样开始:
使用 setup-matt-pocock-skills 配置当前项目。
任务使用本地 Markdown 管理。
如果需要分诊标签,采用默认名称。
这是一个普通单项目,沿用已有文档约定。
请先展示发现和配置草稿,再写入。
配置结束后,应当能回答:以后新需求写到哪里,工单放在哪里,业务词汇和重要决策去哪里找。
本地任务方案默认把规格和独立工单放在 .scratch/ 下。CONTEXT.md 保存共享业务词汇,ADR 保存重要架构选择及理由。CLAUDE.md 或 AGENTS.md 中会留下指向配置的入口。这些是使用时需要认识的产物,不必自己从零设计目录。
已有说明文件会被沿用;两者都不存在时,技能会询问创建哪一个。普通单项目一般采用单一业务上下文,只有发现多包仓库等信号才需要讨论更复杂的布局。
如果启用了分诊,默认状态如下:
状态 | 含义 |
|---|
needs-triage | 尚未判断如何处理 |
needs-info | 信息不足,还需要补充 |
ready-for-agent | 可以交给助手执行 |
ready-for-human | 已明确需要人来处理 |
wontfix | 决定不处理 |
这些配置通常每个项目做一次。以后想换任务系统、重做配置,再运行 setup;普通配置内容也可以直接编辑。
最常用的一条流程:把任务看板做出来
用一个具体需求串起来。假定你已有一个 Web 项目,现在要增加任务看板,支持创建任务、查看列表和变更状态。
这句话还不足以直接当验收标准。任务属于个人还是团队?谁能修改状态?删除之后能不能恢复?第一版是否包含拖拽?这些选择会改变后面的实现范围。
需求还模糊,先用 grill-with-docs
你可以这样发起:
/grill-with-docs 帮我澄清当前项目的任务看板需求。
初步想支持创建任务、查看列表和变更状态。
请结合现有项目,帮我确定第一版范围、业务规则和验收条件。
它按问题之间的依赖分轮追问,并在过程中整理共享术语、记录必要的重要决策。
这一阶段的结束标志,应当是能说清楚第一版让用户完成哪些动作、有哪些限制、哪些事情暂时不做。
grill-with-docs 内部组合了两种能力:grilling 负责怎样追问,domain-modeling 负责怎样把业务概念说准、保存下来。
聊不出答案,就做一次 prototype
任务状态怎么流转,有时靠描述很难判断。页面布局也是,看到了才知道是否顺手。这时可以先做一个小原型,只回答那个悬而未决的问题。
/prototype 做一个任务状态流转的交互演示。
我想检查待办、进行中、已完成之间允许怎样转换。
每次操作后展示当前状态,方便我们检查规则。
这次只回答状态设计问题。
prototype 有两类主要产物。逻辑和状态问题可以做成单个 HTML 演示;界面问题可以提供多种差异明显、能够切换比较的方案。
它采用一次性原型的实现标准,目的是快速验证设计。确认的结论要回到正式需求里,原型本身会作为决策依据保留在独立分支。
按项目推荐的跨目录流程,离开原讨论前用 handoff 写交接材料,在新会话做原型,再把结论交接回原会话。原型回答了问题,就回到需求主线。
用 to-spec 把讨论变成规格
/to-spec
to-spec 主要综合已经讨论过的信息,不重新展开一轮需求访谈。但它仍会就必要的测试边界等内容与你确认。
所谓测试边界,就是从哪里观察系统,能够证明行为正确。完成这一步,应当得到一份明确的规格,以及它在任务系统里的链接或本地产物位置。
测试边界:先复用一个高层 seam
这里的 seam,可以理解为“观察或替换模块行为的位置”。优先复用已有、层级最高的 seam,例如从应用服务进入后,让一次测试穿过领域逻辑和数据库:
flowchart LR
A[用户请求] --> B[[应用服务 · 高层 seam]]
B --> C[领域逻辑]
C --> D[数据库]
这样更接近真实使用路径,也能同时验证参数传递、模块协作、状态变化和错误处理。seam 越多,通常就越多测试入口、mock 数据、接口契约和维护成本;分别测通内部各层,仍可能漏掉模块连接起来时的问题。高层 seam 还会把实现细节藏在稳定接口后,内部重构时不容易牵连测试。
“越少越好”不是硬性数字。只有在存在不同实现或适配器、独立变化或部署需求,或者高层 seam 无法稳定复现局部失败时,才增加 seam。判断新 seam 是否值得保留,可以问:它两侧是否真的存在两种会变化的实现?只有一个实现时,新增的往往只是间接调用;两个可替换的适配器,才说明这里有真实边界。
用 to-tickets 拆成可独立验证的任务
/to-tickets
它要求任务「窄而完整」,能穿过相关层形成可验证的结果。这叫垂直切片。
为了说明切片方式,下面是假定第一版已经确定了相关行为、spec后的。
flowchart TD
A[A:创建任务并能在列表看到] --> B[B:修改任务状态并验证刷新后保留]
A --> C[C:筛选列表并验证结果]
B --> D[D:完成剩余验收项]
C --> D
第一张工单就有用户可观察的结果。它可能同时涉及页面、接口、存储和测试,但范围只覆盖创建并看到任务这一条路径。
B、C 都依赖 A。只有依赖已经完成,后面的工作才具备开始条件。没有依赖的工单可以被分别领取。
每张工单开新会话,用 implement 实现
需求讨论、规格和工单拆分尽量保持连续。到了逐张实现工单时,开启新的会话,把目标工单的链接或文件交给助手。
/implement 实现「创建任务并能在列表看到」这张工单。
下一张工单再用新的会话处理。工单应该能够独立承接实现所需的信息,前一张工单的聊天记录可以留在前一个会话里。
implement 在适用时使用 tdd,定期运行类型检查和单个测试文件,结束时运行完整测试,再调用 code-review,处理发现后提交到当前分支。
flowchart TD
A[读取工单及规格] --> B[在适用处使用 tdd]
B --> C[写一个失败测试]
C --> D[运行并确认暴露目标缺口]
D --> E[写最小实现让测试通过]
E --> F{本工单行为是否完成}
F -->|还有行为| C
F -->|已完成| G[运行完整测试]
G --> H[code-review]
H --> I[规范检查]
H --> J[需求检查]
I --> K[处理评审发现并验证]
J --> K
K --> L[提交到当前分支]
这里的测试有两条很实在的要求:先看到失败,再写让它通过的实现;预期结果要来自需求或独立的正确依据。
评审则分别检查「是否符合项目规范」和「是否实现原始需求」,两个方向由独立的子助手处理并分别报告。
其他常用流程,按遇到的问题挑
Bug 难复现:diagnosing-bugs
把实际症状、触发条件、已经观察到的证据交给它:
/diagnosing-bugs 诊断任务状态偶尔回退的问题。
表现是状态修改成功后,刷新页面有时又回到原状态。
这段是提示词示例,需要换成你的真实故障。技能的关键要求是,先拿到一条已经执行过、能够暴露目标问题的检查路径。
flowchart LR
A[建立可重复检查] --> B[复现并缩小条件]
B --> C[列出可被推翻的假设]
C --> D[增加观察并验证]
D --> E{根因是否确认}
E -->|否| C
E -->|是| F[修复并保留回归测试]
F --> G[清理诊断痕迹并记录结论]
结束时看两件事:原来的症状是否被同一条检查路径验证消失,以及是否留下防止它重来的测试。若发现系统缺少合适的测试边界,还可能形成后续架构改进工作。
代码越来越难改:架构扫描 → 选择候选 → 澄清并实施
调用 improve-codebase-architecture,它会寻找能够改进模块边界的机会,并生成可视化 HTML 报告。你选中一个候选后,再围绕它讨论方案。
/improve-codebase-architecture 具体的频繁出错的地方等等
这里会用到 codebase-design 的设计参考。它关心怎样用一个简洁的接口承载足够完整的能力,让调用者少操心内部细节。
确定方案后,再转规格和工单。扫描报告产出的是候选机会,实际改造需要后续执行。
项目太大,连路线都不清楚:wayfinder → to-spec → to-tickets
如果你要做的是一个跨多个会话才能想清楚的新系统,先用 wayfinder 建立决策地图。
/wayfinder,为团队任务协作系统建立决策地图。
目前用户范围、权限和协作方式都还不明确。
请先帮我定义这轮规划的目标。
它的工单主要回答「需要作出什么决定」。有的问题要调研,有的要做原型,有的必须由你回答。尚未清晰到能提问的部分,先留在地图的待明确区域。
flowchart LR
A[wayfinder 明确规划目标] --> B[建立决策地图]
B --> C[逐项调研或讨论]
C --> D{路线是否清晰}
D -->|否| B
D -->|是| E[to-spec 汇总成可实施规格]
E --> F[to-tickets 拆实现工单]
F --> G[implement]
通常每个后续会话处理一个决策工单,调研工单可以例外并行。路线清楚后,再转成实施规格。决策地图里分散的结论,需要经过这一步整理,才适合交给实现阶段。
要换人、换目录或换助手:handoff
/handoff
它将交接文档保存到操作系统临时目录,引用已经存在的规格、工单和其他产物,并对敏感信息脱敏。新会话读取这份文档,再接着工作。
一般的短任务,留在原会话继续就好。需要把上下文搬到另一个地方时,再使用 handoff。
25 个技能分别做什么
「手动」表示必须由人明确调用;「可自动」表示助手可以在适用时使用,你也可以手动点名。
入口、规划与实现
技能 | 调用方式 | 什么时候用 | 做什么、留下什么 |
|---|
setup-matt-pocock-skills | 手动 | 首次在项目里使用工程流程 | 配置任务系统、分诊标签和业务文档布局 |
ask-matt | 手动 | 不知道该选哪个技能 | 根据当前处境推荐技能和工作路径 |
grill-with-docs | 手动 | 有项目、需求尚未清楚 | 分轮追问,收敛需求并维护术语和重要决策 |
to-spec | 手动 | 已有充分讨论,需要明确规格 | 综合问题、用户行为、决策、测试方式和范围,发布规格 |
to-tickets | 手动 | 规格较大,需要分批实现 | 拆成可独立验证的工单,标明依赖并发布 |
implement | 手动 | 已有清楚任务或规格 | 实现、运行检查、调用评审并提交到当前分支 |
wayfinder | 手动 | 工作太大且方向模糊 | 建立决策地图,逐步解决前置问题,形成后续规划依据 |
triage | 手动 | 收到外部原始反馈 | 判断有效性和信息完整度,设置处理状态并整理可执行说明 |
诊断、验证与设计
技能 | 调用方式 | 什么时候用 | 做什么、留下什么 |
|---|
diagnosing-bugs | 可自动 | 疑难 Bug、间歇故障或性能回退 | 建立检查路径,复现、验证假设、修复并补回归测试 |
tdd | 可自动 | 要按测试逐步构建明确行为 | 一次一个失败测试和最小实现,以红绿循环推进 |
code-review | 可自动 | 实现收尾,或评审分支、PR | 对照固定比较点,分别检查规范与需求,报告两类发现 |
improve-codebase-architecture | 手动 | 模块难理解、难改或难测 | 扫描改进机会,生成 HTML 报告,再讨论选定候选 |
codebase-design | 可自动 | 需要设计模块接口和测试边界 | 提供深模块设计参考,帮助控制调用者承担的复杂度 |
domain-modeling | 可自动 | 业务词汇含混或重要概念冲突 | 澄清词义、检查业务场景,维护术语表和必要决策记录 |
prototype | 可自动 | 逻辑或界面靠讨论难以判断 | 创建可运行演示,验证设计并保留原型依据 |
research | 可自动 | 缺少外部事实或可靠材料 | 由后台助手阅读一手资料,留下带引用的 Markdown 调研结果 |
resolving-merge-conflicts | 可自动 | 已处于 merge 或 rebase 冲突 | 按双方改动意图逐块处理冲突,再完成当前合并或变基 |
wizard | 可自动 | 碰到只有人能完成的配置步骤 | 生成交互式 Bash 向导,引导访问页面、填写配置并保存所需值 |
wizard 适合账号开通、凭据配置、第三方后台操作这类确实需要人参与的环节。助手自己能完成的普通操作,直接执行即可。research 产出事实材料,业务取舍仍要带回需求讨论。
沟通、交接与学习
技能 | 调用方式 | 什么时候用 | 做什么、留下什么 |
|---|
grill-me | 手动 | 没有项目目录,想打磨计划或想法 | 通过追问澄清思路,本身不保存项目文档 |
grilling | 可自动 | 需要复用严密的追问方法 | 按问题依赖分轮访谈,是多个上层技能共用的追问能力 |
handoff | 手动 | 换人、换助手、换目录或中途分出旁支 | 写可携带的交接文档,引用已有产物并脱敏 |
to-questionnaire | 手动 | 关键答案在别人那里 | 先确认接收者和所需信息,再生成供对方填写的问卷 |
wait-what | 手动 | 助手刚才没讲明白 | 补足必要背景,用更易理解的表达重讲上一条消息 |
teach | 手动 | 想跨多次会话学习一个主题 | 围绕学习目标建立课程、参考材料和学习记录 |
writing-for-agents | 可自动 | 编写技能或助手工作说明 | 帮助组织步骤、参考材料和完成标准,让指令更容易被执行 |
grill-me 适合没有项目目录的想法讨论,grill-with-docs 在项目中保留共识,grilling 是它们共用的追问方法。to-questionnaire 用来收集别人掌握的答案,wait-what 则在你没听懂时立即纠正表达。
第一次试用,跑完一个小任务就够了
真正值得验证的,是这套流程能否让你的下一次工作更清楚。
安装并配置好后,挑一个范围有限、做完就能验收的需求。先用 grill-with-docs 确定行为和范围,再经过 to-spec 、 to-tickets和implement。
过程中如果发现问题不是缺代码,而是缺事实,就调研;缺一个能讨论的实物,就做原型;缺别人才能给的答案,就生成问卷。每种技能都有明确的介入理由。
第一轮结束时,对照实际结果检查:任务边界是否比开始时清楚,做完的行为是否能够验证,新会话能否根据工单接手,评审发现是否得到了处理。
这些结果,比安装了多少技能更能说明问题。
mattpocock-skills 的价值就落在这一连串具体动作里。把要做的事说清楚,把工作拆到能验证,把决定留给接手的人,再用运行结果回答是否完成。等这条短流程跑顺了,再把它扩展到更大的项目。