Matt Pocock Skills

Matt Pocock Skills 技能详解

「给真正做工程的工程师用的技能，不是给 vibe coding 用的。」本手册按使用频率重新排序，帮你把最常用的先练熟。

GitHub 源项目 Claude Code / Codex 按使用频率排序

0130 秒安装（先装才能用）

两个渠道任选其一，装完每个仓库跑一次 /setup-matt-pocock-skills 即可开始。

Claude Code
claude plugins install mattpocock-skills
Codex / 其他
npx skills@latest add mattpocock/skills
装完跑一次
/setup-matt-pocock-skills   # 每个仓库只跑一次，配置 issue tracker / 标签 / 文档位置

02黄金路径（标准功能开发）

按顺序走这 5 步，完成「对齐需求 → 出 spec → 拆工单 → 实现 → 审查」的完整闭环。任何一步之前都可用 grill 先对齐。

grill-with-docs 对齐 + 建文档 to-spec 对话 → spec to-tickets 拆分工单 implement tdd + 实现 code-review 双轴审查 grill-with-docs 对齐 + 建文档 to-spec 对话 → spec to-tickets 拆分工单 implement tdd + 实现 code-review 双轴审查
为什么是这个顺序：先对齐（grill）再落纸（spec / tickets），实现阶段就能全速跑 tdd，最后 code-review 双轴兜底——跳步是返工的最大来源。

03每次改动必用

高频必会 · 改代码前先打底

grill-me · 盘问式对齐（非代码） 必用

最火的技能。在动手前让 AI 连环追问你的计划/设计，把模糊想法逼成清晰方案。作者说「每次想改东西都先用它」。

用法
/grill-me 我要给 App 加一个微信授权登录
场景：你只说了「加个登录」。grill-me 会连环追问：登录方式（账号密码 / 第三方）？Token 存哪（DataStore / Keystore）？弱网和 Token 过期怎么处理？把含糊需求逼成清晰方案，再动手。
  • 作者自称「最火的两个技能」之一，每次改动前先用
  • 底层是 grilling 原语：按「设计树」分轮提问，每轮给推荐答案
  • 非代码场景用这个；涉及项目文档/术语用 grill-with-docs

grill-with-docs · 盘问 + 同步产出文档 必用

grill-me 的加强版：同样连环追问，但过程中顺手建项目的共享语言——写 CONTEXT.md 术语表、把关键决策写成 ADR。

用法
/grill-with-docs
场景：同上，但过程中它把项目术语固化进 CONTEXT.md（例如把「lesson 被真实化」统一叫 materialization cascade），关键决策落成 ADR。下次 AI 进项目直接复用这套语言，命名一致、少说废话。
  • 作者称它可能是「本仓库最酷的一项技术」
  • 会调用 grilling + domain-modeling 两个技能
  • 共享语言还能让 AI 更少 token、代码更易导航

tdd · 测试驱动开发（红-绿-重构） 必用

把红→绿循环做成可复用纪律：先写会失败的测试，再写最小实现让它变绿。一次只做一个垂直切片，绝不一次写一堆测试再写实现。

用法
/tdd
场景：写「购物车结算」：先写一个会失败的测试（assert user can checkout with valid cart），再写最小实现让它变绿。每个 seam 一个垂直切片；重构属于 review 阶段，不进红绿循环。
  • 写任何测试前先和用户确认「测哪个 seam」，不在未确认的 seam 上写
  • 好测试验证公开行为，不耦合内部实现（避免重构就挂）
  • 反模式：实现耦合测试、同义反复断言、横向切片

04功能 / PR 常用

高频 · 每个功能一轮

diagnosing-bugs · 纪律化 Bug 诊断循环 高频

硬 bug / 性能回退的诊断纪律：先建一个能稳定复现、几秒出结果的反馈循环，再复现最小化→列假设→验证→修复→加回归测试。跳到猜原因之前必须先有循环。

用法
/diagnosing-bugs 点登录按钮崩溃，logcat 报 NullPointerException
场景：第一步不让你瞎猜，而是先建反馈循环：一个 failing test、或 Playwright 脚本、或 CLI+快照 diff。循环建好后复现并最小化到「去掉任一行就变绿」，再列 3-5 个可证伪假设逐个验证。
  • Phase 1 是核心：没有红得起来的循环，就别进 Phase 2 猜原因
  • 能建 2 秒确定性循环，就是调试外挂
  • 非确定性 bug 目标是提高复现率，不是追求干净 repro

implement · 按 spec / 工单实现 高频

照着 spec 或一组 tickets 把活干完：在约定的 seam 上跑 /tdd，定期 typecheck、跑单测，全做完用 /code-review 审一遍，最后提交当前分支。

用法
/implement
场景：拿到 to-tickets 拆好的票，implement 照着实现：在预同意的 seam 驱动 /tdd，单文件测试常跑、整套测试最后跑一次，结束后自动触发 /code-review，再 commit。
  • 前提是有 spec 或 tickets（先 grill / to-spec / to-tickets）
  • 它自己会串起 tdd 和 code-review，你只 review 结果
  • 禁止 model 调用，只能你主动触发

code-review · 双轴代码审查（Standards + Spec） 高频

对固定点（commit / branch / tag）到 HEAD 的 diff 做两轴审查：Standards 查编码规范 + 12 种代码坏味道；Spec 核对是否对齐需求。两个子代理并行，并排报告。

用法
/code-review main
场景：/code-review main 审从 main 到 HEAD 的 diff：Standards 轴带「坏味道基线」（Feature Envy、重复代码、Shotgun Surgery 等 12 种 Fowler 坏味道）；Spec 轴查需求遗漏 / 范围蔓延。两轴并行互不污染。
  • 固定点没指定会问你（如 main、HEAD~5、某 SHA）
  • 仓库自己的 CODING_STANDARDS.md 优先于基线
  • 提交前必跑，比单人 review 更全

to-tickets · 计划拆成工单 高频

把计划 / spec / 对话拆成一堆 tracer-bullet 工单，每张声明自己被哪些票 block。本地写进文件，或在真实 tracker 上建原生依赖链接。

用法
/to-tickets
场景：一份登录功能计划，to-tickets 拆成一堆垂直切片工单，每张写明「我被 #12、#13 block」。本地写进一个文件，或在 GitHub/Linear 上建真实 blocking 链接。
  • 依赖 /setup-matt-pocock-skills 提供的 tracker 与标签
  • tracer-bullet：每张都是能跑通的小切片，而非大块任务
  • 是 implement 的理想输入

triage · Issue / PR 状态机分流 高频

把 issue（和外部 PR）推过一套小的 triage 角色状态机：分类（bug / enhancement）、验证、必要时 grill，最后写出 AI 可直接接手的 brief。

用法
/triage 42
场景：收到 issue #42：triage 把它推过状态机（needs-triage → bug/enhancement → verified → …），分类、验证、必要时 grill，最后写出带免责声明的 agent-ready brief。外部 PR 当作「带代码的 issue」同样处理。
  • 每个 triage 评论都要带「This was generated by AI during triage.」
  • 依赖 /setup 配置的 tracker 与标签词汇
  • 禁止 model 调用，只能你主动触发

05周期 / 按需

中频 · 几天一次或按需

improve-codebase-architecture · 扫描架构深化机会 中频

扫描整个代码库，找出「把浅模块变深模块」的重构机会（提升可测性与 AI 可导航性），生成可视化 HTML 报告，你挑一个就用 grill 陪你深入改。作者建议每隔几天跑一次。

用法
/improve-codebase-architecture
场景：跑一次扫描整个仓库，列出深化候选（比如某模块接口太宽、职责散落），输出一份可视化 HTML 报告。你挑中一个，它就用 grill 陪你把它改深。
  • 它是「调研」不是「救援」：老代码库会找到真候选，但不会替你解 mud
  • 建立在项目的 domain model 与共享设计词汇之上
  • 每隔几天跑一次，防软件熵加速

to-spec · 对话 → spec 中频

把当前对话综合成一份 spec 发到 issue tracker。不做访谈，只综合你已经聊过的内容。

用法
/to-spec
场景：聊了半天需求后直接 /to-spec，它把当前对话与代码理解综合成 spec 发布到 tracker，不再重复访谈你。
  • 和 grill-with-docs 搭配：先对齐再出 spec 最顺
  • 依赖 /setup 提供的 tracker 与标签
  • 禁止 model 调用

research · 后台研究 + 引用归档 中频

起一个后台 agent 去查问题：只认高可信一手来源（官方文档 / 源码 / spec），把带引用的结论写成 MD 存回仓库。你继续干别的。

用法
/research Play App Signing 对 SHA-1 指纹的影响
场景：让后台 agent 去查「Play App Signing 对签名指纹的影响」，每条结论追到源头（官方文档/源码），写成带引用的 MD 存回仓库约定位置，你不阻塞。
  • 跑在后台 agent 上，你这边不等待
  • 严禁二手转述，每条 claim 都要追到源头
  • 找不到既有约定就放到合理位置并说明

prototype · 一次性原型验证 中频

为回答某个设计问题造一个扔掉的原型：状态/逻辑类问题 → 单个可分享 HTML 文件；UI 类 → 从一个路由切换的多版不同 UI 变体。

用法
/prototype 这个状态机对不对？给个能点着试的
场景：拿不准某个状态模型：prototype 生成一个一次性 HTML 让你点着试；或针对 UI 生成几版不同风格，从同一路由切换对比。答案一清楚，原型就扔。
  • 原型是「扔掉代码，只为回答问题」
  • 先想清楚要回答哪个问题，再决定走逻辑分支还是 UI 分支
  • 禁止 model 调用

domain-modeling · 建立 / 打磨领域模型 中频

主动构建并打磨项目领域模型：挑战术语、想边界场景，术语一成型就立刻写进 glossary 和 ADR。用于讨论术语、写 CONTEXT.md、记 ADR 时。

用法
/domain-modeling
场景：设计新模块时，domain-modeling 逼你把术语定清楚、想边界场景，术语一成型就立刻写进 glossary 和 ADR。注意：只读 CONTEXT.md 借词汇不算这个技能，这是「改模型」时才用。
  • 和 grill-with-docs 同源，是共享语言的活动纪律
  • 术语固化得越早，后续 AI 越省 token、命名越一致
  • 禁止 model 调用

codebase-design · 深模块共享词汇 中频

设计深模块的共享词汇表：seam / depth / leverage / locality 等术语的精确定义，用于设计或改进模块接口、决定 seam 放哪、让代码更易测更 AI 可导航。

用法
/codebase-design
场景：要设计一个深模块：用它的词汇讨论「接口该多深、seam 放哪、调用方 leverage 多大、维护方 locality 多好」。别的技能（如 tdd）需要深模块词汇时也会引它。
  • 术语要精确：别用 component/service/API/boundary 混用
  • 目标是「小接口后面藏大量行为」的深模块
  • 是参考型词汇，不是一次会话

wayfinder · 超大任务的决策地图 中频

把大到一次会话装不下的工作，在 issue tracker 上画成一张「决策工单地图」，一次解一个决策，直到通往终点的路清晰。重「找路」而非「冲终点」。

用法
/wayfinder
场景：一个模糊的大需求，wayfinder 先在 tracker 上命名「目的地」，再拆成一张决策工单地图（每个工单是「一个待决的决策」而非构建切片），逐张解，直到路线清晰。
  • 先给目的地命名，它决定每张工单的形状
  • 解的是「决策」不是「构建切片」
  • 禁止 model 调用

ask-matt · 技能路由器 中频

你记不住所有技能时来问它：根据当前情况指向合适的技能或流程（主流程 + 两个 on-ramp），其余大多是独立技能或底层词汇层。

用法
/ask-matt 我想给老模块加新功能，该用哪个？
场景：忘了用哪个技能？/ask-matt 当路由器，问清你的情况后指向合适技能或 flow（如先 grill-with-docs 再 to-spec）。
  • 记不住清单时的入口
  • 本质是「flow 路由器」，不是具体干活
  • 禁止 model 调用

06效率 / 协作

低频 · 偶尔用到

handoff · 会话交接文档 低频

把当前会话压缩成一份交接文档，让另一个（或下次的）agent 能直接续上。存到系统临时目录而非当前工作区。

用法
/handoff 下一步要接着做 OAuth 参数对齐
场景：下班前 /handoff 把进度、未完成任务、关键决策背景压成文档，存到系统临时目录，下一个 agent 通过「suggested skills」字段知道该调哪些技能。
  • 不重复 specs/plans/ADRs 已有内容，只引用路径
  • 适合休假 / 转交需求
  • 禁止 model 调用

teach · 跨会话渐进教学 低频

教用户一个新技能/概念，且是有状态的：把学习状态存进工作区多个文件，跨多次会话渐进推进。

用法
/teach 我想系统学 TDD
场景：/teach 我想系统学 TDD，它会把教学状态存进工作区多个文件，下次继续从上次进度教，而不是一次性倒给你。
  • 把当前目录当教学 workspace
  • 适合长期、分主题的学习
  • 禁止 model 调用

wait-what · 没跟上？重新讲一遍 低频

上一条消息没听懂时立刻触发：让 AI 用 CONTEXT.md 的共享语言、Simplified Technical English 重新讲一遍，补齐你缺的上下文。

用法
/wait-what
场景：AI 说的你没跟上：/wait-what 让它停下，用项目共享词汇、简化英语把刚才那点重新 pitch 一遍。
  • 对话中随时可打断重讲
  • 依赖 CONTEXT.md 的共享语言（没有就先 grill-with-docs）
  • 禁止 model 调用

to-questionnaire · 把决策变成问卷 低频

把你独自答不了的决定，变成一份问卷交给那个能答的人（异步填，或一起开会填）。它先 grill 你「发给谁、要回什么」，问题再针对知识缺口。

用法
/to-questionnaire 后端 OAuth 参数该怎么填？
场景：有个决策你答不了（比如后端 OAuth 参数）：to-questionnaire 先问你「发给谁、要回什么」，再据此生成问卷，把对方知道、你缺的那块挖出来。
  • grill 的是「发送」不是「主题」——发送你总能答
  • 适合跨角色 / 问专家
  • 禁止 model 调用

writing-for-agents · 给 agent 写文档的参考 低频

写任何 agent 消费的文档（skill、AGENTS.md / CLAUDE.md、被指针引用的 doc）时的写作参考：context pointer、可预测性等杠杆。

用法
/writing-for-agents
场景：你要写 / 改 skill 或 AGENTS.md：writing-for-agents 是写作参考——强调「context pointer 的措辞决定 agent 何时去读」，弱措辞的指针是方差 bug。
  • 写 skill 时配合读 SKILL-MECHANICS.md（frontmatter / 调用方式 / 路由）
  • 包装不同，写法一致：让 agent 每轮吃同样的 process
  • 可 model 调用（作为参考被引用）

07一次性配置

每个仓库只跑一次

setup-matt-pocock-skills · 每仓库一次性配置 低频

配置本仓库的工程技能：选 issue tracker（GitHub / Linear / 本地文件）、triage 标签词汇、领域文档布局。每个仓库只跑一次，之后别的工程技能才能用。

用法
/setup-matt-pocock-skills
场景：新仓库第一次用：运行它配置 issue tracker、triage 标签、文档存放位置。不跑这一步，/triage、/to-tickets、/code-review 都会提示你先 setup。
  • 安装后第一件事就是跑它
  • 配置会写进 docs/agents/issue-tracker.md 等处
  • 换仓库要重新跑

08最佳实践 · 三条高频路径

① 标准功能开发
/grill-with-docs   对齐 + 建 CONTEXT.md
/to-spec          对话 → spec
/to-tickets       拆成 tracer-bullet 工单
/implement        实现（自动驱动 /tdd + /code-review）
② 修复 Bug
/diagnosing-bugs
  ① 建反馈循环（先别猜）
  ② 复现 + 最小化
  ③ 列 3-5 个假设
  ④ 验证 + 修复
  ⑤ 加回归测试
③ 架构健康（每几天）
/improve-codebase-architecture
  → 扫描浅模块变深模块的机会
  → 输出可视化 HTML 报告
  → 挑一个 grill 深入改

本文档由 WorkBuddy 基于 mattpocock/skills 公开内容重新梳理 · 按使用频率排序 · 支持深色 / 浅色主题