🟡 进阶

mattpocock/skills 到底怎么用

37 个技能、两条互斥的安装路线，和一条能跑通的最短路径

📅 更新于 2026-10-06

本文校对于 mattpocock/skills @ v1.3.1 · 官方源：github.com/mattpocock/skills

37
仓库里的技能
27
README 收录 / 插件给
22 : 15
人能点火 : 模型可自动取用
6
主流程技能

0030 秒速览：三条结论 + 按处境挑技能

读完这一篇，你能做出三个判断：这条路线该选哪条、这套东西能替你解决哪一类问题、以及为什么它给你的第一感受往往是"变慢了"（那是设计意图，不是 bug）。

🔑 先记住三句话（后面都是细节）

① 它不是"帮你写代码"的流水线，而是在你最容易偷懒的那一步插一道闸——最值钱的几个技能干的事是向你提问、把答案落成文档；② 37 个技能里模型只能自己开动 15 个，22 个必须由你敲，这道"人才能点火"的设计是整套东西的分界线（04）；③ 插件与 skills.sh 只能选一条，两条都装会让每个技能在你机器上出现两份。

按你的处境，直接用这个

你现在的状态直接用这个为什么
还没装，只想赶紧用上claude plugins install mattpocock-skills一条命令，自动更新（03）
想改它、想在 Codex 上也用npx skills@latest add mattpocock/skills文件写进你的仓库，归你（03）
装完了，不知道下一步先跑 /setup-matt-pocock-skills，再敲 /ask-matt每个仓库一次；它是路由器（06）
有个模糊想法，说不清要什么/grill-with-docs让 AI 反过来追着你问，把歧义问出来
需求聊清楚了，要落成文档/to-spec → /to-tickets不重复访谈，只把共识合成规格与票据
活儿太大，一次会话装不下/wayfinder把它变成一张可以一张张解的决策地图
开始写代码了/implement（一张票一次）或 /implement-spec（整份一次跑完）两者都驱动 /tdd，最后跑 /code-review 收尾
AI 写的代码"看着对但不对"/code-review双轴评审：代码规范 × 是否忠实于规格
一次改动做完了，想下次少踩坑/retro回头改 agent 的工作环境，而不是改代码
有个难复现的 bug/diagnosing-bugs先建能变红的反馈回路，再谈修复
会话快爆了 / 要换人接手/handoff把活线程压成一份 Markdown
AI 说的话你没看懂/wait-what用你的项目词汇重讲一遍

一条可执行的上手路径

1
选一条路装上，只装一条（约 2 分钟）

见 03。装完立刻跑一次 /setup-matt-pocock-skills——这不是可选项，缺配置时 /to-spec、/to-tickets、/triage、/code-review 会停下来让你先去跑它。

2
挑一个真实的小需求，把主流程走一遍（约 1 小时）

/grill-with-docs → /to-spec → /to-tickets → /implement → /code-review → /retro，见 06。先走通一条，再回来挑其他技能——不要一次装齐再慢慢试。

3
只保留你真会重复用的那几个（长期）

本仓库自己的说法是：这些技能的定位是"小、可改、可组合"（small, easy to adapt, and composable）。用不上的直接删掉，比留着占脑子更划算。

📌 读完你应该能

说清它和"全自动流水线"的区别；独立选对安装路线；讲出 37 / 27 / 10 这三个数字各自怎么来的；并且知道一次改动的六个技能该怎么串。本文讲的是这套技能包，不是某个技能的内部实现细节。

01这 37 个文件到底是什么（先破四个错想）

mattpocock/skills 是一套由 37 个 Markdown 技能文件组成的工程纪律包：每个技能是一个小到能一眼读完的指令文件（SKILL.md），你敲斜杠命令调用它，或者让模型在合适时机自己取用。作者 Matt Pocock 把它定位成"给真做工程的人用的技能，不是 vibe coding"（README 原话：My agent skills that I use every day to do real engineering - not vibe coding）。

先破掉四个错误印象

❌ 错想一：它是"自动帮你写代码"的流水线

以为装上以后有个开关，一开就从头跑到尾。

✅ 实际上：最值钱的技能在"踩刹车"

它没有守护进程、没有后台任务、没有"启动后自动跑完"的开关。绝大多数技能干的事是向你提问、把答案落成文档，或者在动手前逼你先建好反馈回路。真正写代码的那两个（/implement、/tdd）反而是最短的文件。

❌ 错想二：它和 BMAD / Spec-Kit 是同类

既然都是"流程框架"，那就挑一个功能最全的。

✅ 实际上：它的卖点恰恰是"不接管流程"

README 点名了那类做法的取舍：它们通过占有流程来帮忙，代价是你交出了控制权，而且流程本身的 bug 很难修（原话：they take away your control and make bugs in the process hard to resolve）。这套技能的自我定位正好相反：small, easy to adapt, and composable——小、可改、可拼。

❌ 错想三：装完得到的是一个"软件"

既然是"装"，那它应该是个程序，有自己的配置中心和卸载程序。

✅ 实际上：你得到的是一堆文本文件

主要是 SKILL.md，外加极少量模板脚本（例如 wizard 的 template.sh、diagnosing-bugs 的 scripts/hitl-loop.template.sh）。没有二进制、没有依赖、没有配置中心——所以"卸载"就是删目录。

❌ 错想四：它是 Claude Code 专属

只支持 Claude Code 的话，我用 Codex 就只能干看着。

✅ 实际上：每个技能同时带两份元数据

一份给 Claude Code 用的 frontmatter，一份给 Codex 用的同级文件 agents/openai.yaml（每个技能都带这一个文件，里面放着技能选择器要显示的 interface.display_name / short_description，以及用户可启动技能需要的那个"禁止隐式调用"开关）。仓库里还有一条 ADR（0002-ship-as-a-claude-code-plugin.md）专门记录"为什么以 Claude Code 插件形态发布"，同时承认原生 Codex 插件还在路线图上。

一句话版本：它是什么

把作者日常在用的技能目录公开出来，按四个桶分组：engineering（20 个）、productivity（7 个）、misc（4 个）、in-progress（6 个）。每个桶把技能分成两类列出——用户可启动（user-invoked）与模型可启动（model-invoked）——这是整套设计的唯一分界线，04 专门讲它。

机制：为什么"几个 Markdown 文件"能改变工作方式

因为技能的实质不是知识，而是在你最容易偷懒的那一步插一道闸。三个真实例子：

这三件事的共同点：人在赶进度时最不会主动做，而 AI 又特别容易顺着你的话往下写。把闸做成一个斜杠命令，你才有机会在"已经写了两千行"之前把它拉下来。

📌 一句话记住它

它不是替你写代码的工具，是替你在正确的时候踩刹车的工具。所以它带来的第一个感受往往是"变慢了"——那是设计意图，不是 bug。

02它为什么存在：四条失效模式，和四句原话

这一节不是我总结的，是 README 自己写的"这些技能为什么存在"：它点名了用编码代理时最典型的四种失效，每种配一位经典作者的原话、一个"修法"、以及对应的技能。理解这四条，你就能判断自己该用哪几个——而不是把 37 个都学一遍。

失效问题（README 的说法）修法对应技能
1 · 做的不是我想要的 你和代理之间存在沟通缺口；你以为它懂了，看到成品才发现它根本没懂 开一场盘问会（grilling session），在动手前把要建的东西问细 /grill-me（非代码场景）
/grill-with-docs（代码场景，外加下文第 2 条的好东西）
2 · 它太啰嗦 代理被丢进一个项目，边干边猜行话，于是一句话能说清的事它用二十句 建一份共同语言文档，让代理能解码项目里的行话 /grill-with-docs（盘问的同时建领域模型，把难解释的决定写成 ADR）
3 · 代码跑不起来 就算对齐了要做什么，它做出来的东西还是不行——因为它不知道代码实际跑起来是什么样 补反馈回路：静态类型、浏览器、自动化测试。测试用红-绿-重构 /tdd
/diagnosing-bugs（把调试最佳实践包成有阶段闸门的循环）
4 · 我们造出了一团泥（README 的用词是 a ball of mud） 代理把写码速度拉满，于是软件熵也以前所未有的速度增长：库越来越复杂、越来越难改 把"关心设计"放进每一层：先说清你要动哪些模块，再定期勘察代码库 /to-spec（写规格前先问你要动哪些模块）
/improve-codebase-architecture（勘察加深模块的机会）

四句原话（README 的引文）

README 给每一条失效都配了一句经典作者的话。四句放在一起看，能看出这套技能的野心：它想守的是软件工程的老底子，而不是发明一套新流程。

一条"共同语言"到底能省多少：一个真实的前后对照

README 举了自己那个 course-video-manager 仓库里的例子，同一件事的两种说法：

❌ 建共同语言之前

"There's a problem when a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)"

（课程里某一节里的一课被"实体化"——也就是在文件系统里拿到一个位置——时有问题。）为了说清一件事，得先把三个对象的关系和一个动作解释一遍。

✅ 建了共同语言之后

"There's a problem with the materialization cascade"

（"实体化级联"有问题。）一个词顶掉一整句解释。README 对这件事的评价很直白：这种简洁会在一个又一个会话里持续付利息（This concision pays off session after session）。

💡 README 说这是"这个仓库里最酷的技术"

除了少说废话，共同语言还顺带带来三件事：变量、函数、文件名会用同一套词命名；于是代码库对代理更好导航；而且因为它拿到的是更简洁的语言，思考本身也花的 token 更少。这也是为什么 /grill-with-docs 值得在每次改动前跑——它一边盘问你，一边顺手把语言统一了。

03两条安装路线，先选一条别都装

官方 README 把安装压缩成三步。其中第一步有两条互斥的路线，选错会留下一个很难自查的后遗症。

① 选一条路（只能一条）
→
② /setup-matt-pocock-skills（每仓一次）
→
③ /ask-matt 问"我该用哪个"

路线 A：Claude Code 插件（订阅制，只读）

1
装
claude plugins install mattpocock-skills

会话内也可以敲 /plugin install mattpocock-skills。

2
升级不用管

它挂在 Claude Code 的官方 marketplace 上，所以不需要先添加市场，更新会自动到达。官方原话是 updates arrive automatically。

路线 B：skills.sh（把文件写进你的仓库）

1
装
npx skills@latest add mattpocock/skills

安装器会让你勾选要哪些技能、装给哪些编码代理。README 特意加粗提醒：确保 setup-matt-pocock-skills 在里面。

2
升级要自己动手
npx skills update

没人会在背后替你更新——文件是你的，什么时候拉新版由你决定。这正是它相对插件的全部卖点。

装完你得到的是一堆可编辑的 SKILL.md（以及每个技能旁边的 Codex 元数据文件），直接躺在你的机器 / 仓库里。

❌ 错误：两条路都试试

先用插件装一遍，又觉得"还是能改文件爽"，再 npx skills add 一遍。结果：每个技能在你机器上出现两份，斜杠命令列表里同名项重复，模型自动触发时命中哪一份不确定。README 的原话毫不含糊：Pick one: installing both leaves you with every skill twice.

✅ 正确：按需求选一条，然后固定下来

只想用、不想维护 → 插件一条命令收工。想改、想跨代理、想自己控版本 → skills.sh，然后用 npx skills update 手动升级。

两条路的区别，一张表看完

维度路线 A：Claude Code 插件路线 B：skills.sh
文件归谁只读的托管包，你不直接编辑它写进你的仓库，是可编辑的普通文件
更新随官方市场自动更新你自己 npx skills update
能不能改不能改（要改就 fork）能改，改成你自己团队的习惯
可用代理仅 Claude Code任何代理（含 Claude Code）
拿到几个技能27 个（engineering 20 + productivity 7）你勾选的那些；misc 与 in-progress 共 10 个只能走这条路
拿到几分一份一份
装到哪由插件系统托管写进你的机器 / 项目目录，是可编辑的普通文件
⚠️ 边界：这两条路都不是"装完就能用"

无论哪条路，每个仓库都要单独跑一次 /setup-matt-pocock-skills。它不是可选项：/to-spec、/to-tickets、/triage、/code-review 都会在缺少配置时停下来，让你先去跑它。misc 里的四个工具型技能是唯一例外——它们不依赖这套仓库配置。
（本文没有逐一验证各代理的默认安装目录——那随版本会变，请以你装完后 agent 实际报出的路径为准。）

04整套设计的唯一分界线：谁能启动它

如果这篇只能留一节，就留这一节。整套技能的其它设计几乎都是从这条分界线推出来的。

什么叫"谁能启动它"

仓库自己的文档 .agents/invocation.md 把它写得很直白：每个 SKILL.md 都是一个技能，唯一的分割轴是"调用"——谁能碰到它。做法是在元数据里关掉模型的权限：Claude Code 侧写 disable-model-invocation: true，Codex 侧写 policy.allow_implicit_invocation: false。

类型谁能启动它它的 description 写给谁看它负责什么
用户可启动
（user-invoked）		 只有人敲名字。模型碰不到它——包括别的技能也调不动它 写给人看：你浏览斜杠命令时读的一行摘要。官方要求把触发词列表（"Use when the user says…"）删掉 编排（orchestrate）：把流程串起来
模型可启动
（model-invoked）		 人和模型都能：任务合适时模型自己会用 写给模型看：保留丰富的触发措辞（"Use when the user wants…, mentions…"），好让自动触发命中 沉淀可复用的纪律（reusable discipline）

三条硬规则

1
用户可启动的技能，模型永远碰不到

官方原话是 a user-invoked skill can never be reached this way, full stop（完整地说：它绝不可能被这种方式碰到）。所以当一个步骤的前置条件是某个用户可启动技能（比如 setup-matt-pocock-skills），技能内部不能"调用"它，只能提示人去敲。这就是为什么 /to-spec 缺配置时会停下来让你去跑 /setup-…，而不是自己跑掉。

2
用户可启动的技能可以调用模型可启动的，反过来不行

所以 /grill-with-docs 内部可以调用 grilling 和 domain-modeling（两个都是模型可启动），但两个用户可启动技能之间永远不会互相调用。这条规则让"编排"永远只发生在人能看见的那一层。

3
依赖要靠"点名工具"，不能靠斜杠

技能之间表达依赖的写法，官方规定为明确指示调用 Skill 工具并写出技能名（例如 Call the Skill tool with "grilling"），而不是深层的相对路径引用，也不是在散文里丢一个 /名字 让模型自己领会。理由很实在：把工具名点出来，命中率高于"希望它把 /名字 读成命令"。

🧠 为什么这个设计值得单独学

它把"谁有权点火"变成了一个可以写进文件、并且跨两个代理保持一致的开关。你自己写技能时最该抄的就是这一条：会改变状态、会连续跑很多步、或者需要人为判断才能开动的流程，把它设成用户可启动；可复用的纪律、审查、领域建模这类"随时被叫来帮忙"的，设成模型可启动。

0537 个技能全景：22 个你能敲，15 个模型自己会用

先认路，再记命令。下面按桶（功能分组）排、在每个桶里再按类型（谁能启动）分。描述逐字取自上游 README 的 Reference 段（未公开的 10 个取自它们各自的 SKILL.md 元数据）。

Engineering（20 个）：日常写代码用的

技能类型它是什么 / 怎么用（官方描述）
用户可启动（你能敲，模型不会自己开动）
ask-matt用户可启动问你该用哪个技能或哪条流程。它是本仓库里「用户可启动」技能的路由器。
grill-with-docs用户可启动一边盘问，一边建设你的领域模型：打磨术语，顺手更新 GLOSSARY.md 和 ADR。
triage用户可启动让 issue 在「分诊角色」构成的状态机里往前走。
improve-codebase-architecture用户可启动扫一遍代码库找「加深模块」的机会，给出一份可视化 HTML 报告，再挑一个继续盘问。
setup-matt-pocock-skills用户可启动把一个仓库配置好（issue 跟踪器、分诊标签、领域文档布局）。每个仓库用其他工程类技能之前跑一次。
to-spec用户可启动把当前这段对话整理成一份规格并发布到 issue 跟踪器。不再访谈，只合成你们已经聊出来的共识。
to-tickets用户可启动把任何计划、规格或对话切成一组「曳光弹」票据，每张票声明自己的阻塞边（谁必须先完成），写成本地文件或跟踪器上的原生阻塞链接。
implement用户可启动按规格或票据实现：在事先约定的接缝处驱动 /tdd，提交前用 /code-review 收尾。
implement-spec用户可启动把整份规格一次实现掉：把票据当一张任务图（阻塞边就是图上的箭头），在可以开工的「前沿」（阻塞边都已清掉的那批票）上并行跑几个子 agent（各自独立干一段活的小助手），最后全部汇到同一条集成分支（大家最后合并进去的那条分支）上，用 /code-review 收尾。
wayfinder用户可启动把大过单个 agent 会话的一坨活儿规划成跟踪器上的一批「决策票据」，一次解一张，直到去目的地的路清楚为止。
retro用户可启动一次会话结束后，回头建议改进编码 agent 的环境（指路用的导航指针、自动化检查、编码规范、AGENTS.md 这类引导文件、工具链），最严重的排前面。
模型可启动（你敲它也行，任务合适时模型自己会用）
prototype模型可启动写一次性原型回答一个设计问题：要么一个可分享的单页 HTML 回答状态/逻辑问题，要么几条差异极大的 UI 变体用一个路由切换着看。
diagnosing-bugs模型可启动针对难缠 bug 与性能退化的诊断循环：先建一个能对这个 bug 变红的反馈回路 → 最小化 → 提假设 → 加观测 → 修 → 加回归测试。
research模型可启动拿一个问题上高可信的一手来源做调查，把发现写成带引用的 Markdown 放进仓库，作为后台 agent 跑。
tdd模型可启动红-绿-重构的测试驱动开发。一次一个垂直切片地做功能或修 bug。
domain-modeling模型可启动主动建设和打磨项目的领域模型：拿术语表挑战用词、用边界场景压测，顺手更新 GLOSSARY.md 和 ADR。
codebase-design模型可启动设计「深模块」的共享纪律与词汇：小接口后面藏很多行为，放在干净的接缝上，并能透过这个接口测试。
code-review模型可启动对「自某个固定点以来的 diff」做双轴评审：规范轴（是否符合本仓编码规范 + Fowler 坏味道基线）与规格轴（是否忠实实现了那个 issue/spec），两条轴并行跑子 agent，互不污染。
pr模型可启动一个 pull request（PR，把一串改动交出去请人合入的那份请求）的正文该长什么样：用能把改动说清的最小可视化做摘要，配上"改前 / 改后"能跑的证据，再给一句"合进去有多险"的判断（双向门＝能轻松回退，单向门＝回不去，外加波及面多大）。
wizard模型可启动生成一个交互式 bash 向导，把只有人能做的那几步领着走：开通基础设施、配置凭据或 CI secret、走一遍陌生的第三方后台、跑一次性迁移或切换。

Productivity（7 个）：与代码无关的通用工作流

技能类型它是什么 / 怎么用（官方描述）
用户可启动
grill-me用户可启动就一个计划或设计被 relentlessly（不依不饶地）访谈，直到设计树上的每个分支都被解决。
handoff用户可启动把当前对话压缩成一份交接文档，让另一个 agent 能接着干。
teach用户可启动跨多次会话教你一个新技能或概念，把当前目录当作有状态的教学工作区。
to-questionnaire用户可启动把一个你自己答不了的决策变成一份给「唯一能答的人」的 Markdown 问卷，可以异步填，也可以会上一起填。它盘问的是「怎么发出去」（给谁、要拿回什么），不是主题本身。
wait-what用户可启动消息没听懂的那一刻就敲它。agent 会用你缺的那点上下文重讲一遍，用大白话，用你 GLOSSARY.md 里的词汇。
模型可启动
grilling模型可启动就一个计划、决策或想法不依不饶地访谈用户，直到设计树上每个分支都被解决。它是 grill-me、grill-with-docs、triage、wayfinder 和 improve-codebase-architecture 背后那个可复用的访谈原语。
writing-for-agents模型可启动写给 agent 看的文档：技能、AGENTS.md / CLAUDE.md，以及任何 agent 顺着指针读到的文档。

另外 10 个：仓库里有，但插件不给（misc 4 + in-progress 6）

这四个 misc 技能和六个 in-progress 技能都在仓库的 skills/ 目录里，但不在 Claude Code 插件里，README 的 Reference 段也没收它们。要用只能走路线 B 单装（见 03）。

技能桶 / 类型它是什么（取自各自 SKILL.md 的元数据）
git-guardrails-claude-codemisc · 模型可启动配置 Claude Code 的钩子，在危险 git 命令（push、reset --hard、clean、branch -D 等）执行前拦下它们。
migrate-to-shoehornmisc · 模型可启动把测试文件里的 as 类型断言迁移到 @total-typescript/shoehorn。
scaffold-exercisesmisc · 模型可启动创建练习目录结构：章节、题目、答案、讲解，并且能过 lint。
setup-pre-commitmisc · 模型可启动给当前仓库配上 Husky 提交前钩子：lint-staged（Prettier）、类型检查、测试。
claude-handoffin-progress · 用户可启动把当前对话交接给一个新的后台 agent，让它立刻接手继续干。
loop-mein-progress · 用户可启动就你想在这个工作区里搭的那套工作流，盘问你对规格的想法。
setup-ts-deep-modulesin-progress · 用户可启动把 dependency-cruiser 接进一个 TypeScript 仓库，让每个包都是深模块：实现藏在子目录里，只能从入口文件到达。
writing-beatsin-progress · 用户可启动写作的「利用」阶段：把素材组装成一段段推进的节拍，每个术语在被节拍依赖之前先打好地基。
writing-fragmentsin-progress · 用户可启动写作的「探索」阶段：先把零散素材挖出来，还不谈结构。
writing-shapein-progress · 用户可启动写作的「利用」阶段：把素材一段一段地塑形成一篇文章。
⚠️ 三条关于这份清单的实话
  • 你看到的数字取决于你在哪看。GitHub 仓库的 skills/ 下是 37 个 SKILL.md；README 的 Reference 段只收 27 个（engineering 20 + productivity 7）；Claude Code 插件给的就是这 27 个。差异的来源就是上面这 10 个（misc 4 + in-progress 6）。
  • in-progress 是会变的。这个桶的意思就是"还在长"，命令名和行为都可能改。
  • 光看清单没用。决定成败的是顺序（06），不是命令表。

06主流程：六个技能串起一次改动

清单是地图，这一节是路线。一次典型的改动，官方推荐的走法是六个技能首尾相接——每一步都产出一个下游能用的东西，这正是它和"想到哪写到哪"的区别。

/grill-with-docs
→
/to-spec
→
/to-tickets
→
/implement
→
/code-review
→
/retro
步骤它问你什么 / 做什么它的产出是什么缺了它会怎样
/grill-with-docs 就这个改动不依不饶地盘问你，直到每个分支都被决定；同时顺手打磨术语 一份被问清楚的共识 + 更新过的 GLOSSARY.md / ADR 你会在"其实没想清楚"的状态下直接开写，返工在最后暴露
/to-spec 不再访谈，只把已经聊出来的东西合成规格 发布到 issue 跟踪器的一份规格 共识只活在这一段聊天记录里，换会话就没了
/to-tickets 把规格切成"垂直切片"，给每张票标阻塞边 一组能独立验收的票据（本地文件或跟踪器原生阻塞链接） 活儿太大，一次会话装不下，进度无法交接
/implement 按规格/票据实现，在事先约定的接缝处驱动 /tdd 能跑的代码 + 测试；提交前用 /code-review 收尾 实现与规格分家，评审时才发现做的不是要的
/code-review 双轴并行评审：规范轴（编码规范 + Fowler 坏味道）× 规格轴（是否忠实实现） 两条轴各自的结论（刻意不合并成一个总名次） 你只拿到"看着还行"，拿不到"哪里不符合本仓规范 / 哪里偏离了规格"
/retro 回头看这次会话，问的是"环境该改什么"而不是"代码该怎么改"：指路用的导航指针、自动化检查、编码规范、AGENTS.md 这类引导文件、工具链 一组对 agent 工作环境的改进建议（能用机器判的机械性错误变成确定性检查——lint 规则、提交前钩子、CI 任务；只能靠人判的变成编码规范） 下次同一个坑再踩一遍，环境一点没变好
🔀 到 /to-tickets 之后有个岔口：一次做一张，还是整份一次跑完

官方给了两条并行走法：/implement 是一张票一次，每张票之间清一次上下文（票据自带全部信息，上一张的记忆可以丢）；/implement-spec 是整份规格一次跑完——把票据当一张任务图（阻塞边就是图上的箭头），在可开工的「前沿」上并行跑几个子 agent，最后全汇到同一条集成分支上。官方路由器 /ask-matt 给的选择标准是：想自己一张张驱动就用前者，想交给它编排就用后者。活儿要变成 pull request 时，/pr 负责 PR 正文的形状。

⚠️ 别把它当"必须按顺序打完的一套命令"

这是这套技能最容易被误读的地方。实际用法是按处境挑：活不是从"我想做个功能"开始的——可能是 issue 涌进来（/triage）、可能是一坨大过会话的活（/wayfinder）、也可能是一开始就说不清要什么（/grill-with-docs）。/ask-matt 就是为这件事准备的：它不干活，只告诉你"你这种情况该用哪个"。

07两个跑在所有技能底下的技能

有两个技能不在主流程上，但几乎跑在所有其它技能底下。理解它们，你就理解了这套东西为什么强调"文档"。

grilling：那个"问到你烦"的原语

官方把它定位成可复用的访谈原语——grill-me、grill-with-docs、triage、wayfinder、improve-codebase-architecture 背后都是它。它的行为很简单：就一个计划或决策不停地问，直到设计树上的每个分支都被解决。

它的价值恰恰在于"烦"：人在赶进度时最不会主动做这件事，所以交给一个不许你跳过的流程。

domain-modeling / GLOSSARY.md：让术语不再漂移

domain-modeling 干的是主动建设和打磨项目的领域模型：拿术语表挑战你的用词、用边界场景压测、更新 GLOSSARY.md 和 ADR。

这里有个细节值得学：官方文档特意区分了"读"和"建"——仅仅为了取词汇而读一眼 GLOSSARY.md，那是一行散文指针，不等于执行 domain-modeling；只有主动的挑战术语、压测、写 ADR、就地更新 GLOSSARY.md 才算。

🧠 为什么这两个"底层技能"值得先学

它们解释了这套技能对"文档"的态度：文档不是交付物，是让下一轮对话不用重新解释的缓存。GLOSSARY.md 存的是你这个项目的通用语言，ADR 存的是"为什么这么做"的决定——两者都是为了让下一次的 AI（以及下一个人）不必从零开始。

08最小例子：一句「导出当前筛选结果」

抽象讲了六节，来看一个具体到能想象的改动。

需求：后台列表页的"导出"按钮，现在导出全部数据，你想让它导出当前筛选结果。

1
/grill-with-docs 会先拦住你

它不会马上写代码，而是问一些你还没决定的事。典型的几个：

  • "当前筛选"在服务端和前端哪一边生效？两边不一致时以谁为准？
  • 导出的是这一刻的结果，还是重新按条件查一遍？（数据在两次点击之间变了怎么办）
  • 导出列要不要跟着筛选走——比如按"状态"筛选时，还要不要导出状态这一列？
  • "筛选结果为空"时是给一个空文件、还是报错、还是禁用按钮？

顺手它会把"筛选""导出""当前结果"这些词在 GLOSSARY.md 里的说法对齐——如果你们团队管这个叫"视图"而不是"筛选"，这里就会被纠正过来。

2
/to-spec 把这轮问答变成文档

它不再问你第二遍，只把刚刚的共识合成一份规格：范围（改哪个接口）、行为（服务端为准 / 重新查询）、边界（空结果禁用按钮）、以及明确的"这次不做"。

3
/to-tickets 切成能独立验收的小块

比如三张票：① 接口支持按筛选条件导出；② 前端把当前筛选传下去；③ 空结果时的按钮状态。每张票标出阻塞边（②依赖①）。

4
/implement 一次做一张，先写测试

它在事先约定的接缝处驱动 /tdd：先写一个会失败的测试（比如"传了筛选条件时只返回匹配行"），再让它变绿，再重构。做完一张票再动下一张。

5
/code-review 最后做双轴体检

它从某个固定点（比如主干）开始看 diff，两条轴并行跑：规范轴问"这符合本仓的编码习惯吗、有没有坏味道"，规格轴问"这忠实实现了那份规格吗"。两条轴的结论刻意不合并——由你来判断"规格对但代码烂"和"代码漂亮但做错了事"哪个更急。

🎯 这个例子里最值钱的一步

是第 1 步。那四个问题里，至少有一个（"数据在两次点击之间变了怎么办"）是你在写代码时几乎一定会漏掉、而在上线后一定会被问到的。整套技能的价值密度就集中在这种地方。

09七个常见坑

下面七条，是从这套技能的文档与设计里能直接读出来的失败模式。每条都给出"怎么避免"。

坑 1：两条安装路线都装了
症状：同一个技能在你机器上出现两份，斜杠命令列表里重名，模型自动触发命中哪份不确定。
避免：README 说得毫不含糊——Pick one。想清楚你要的是"订阅"还是"拥有"，然后固定下来。
坑 2：跳过了 /setup-matt-pocock-skills
症状：/to-spec、/to-tickets、/triage、/code-review 一敲就停下来让你先去配置。
避免：把它当成"安装的第 1.5 步"。每个仓库一次，别指望它只跑一次就全局生效。
坑 3：把 37 个当 27 个（或反过来）
症状：明明装了插件，斜杠命令列表里却找不到 /scaffold-exercises 或 /writing-shape；或者以为自己装了全部 37 个。
避免：记住三个数字——仓库 37、README 收录 27、插件给 27；差的 10 个（misc 4 + in-progress 6）只能走路线 B 单装。
坑 4：做完了整条主流程，却忘了它可以拆开用
症状：活根本不该从"我想做个功能"开始，你却硬套 grill → spec → tickets → implement → review → retro，于是一堆空转的文档。
避免：先问一句"我现在的处境是什么"。issue 涌进来用 /triage，活太大用 /wayfinder，说不清要什么才用 /grill-with-docs。不确定就敲 /ask-matt。
坑 5：指望它自动跑
症状：等模型自己想起 /to-spec，结果一直没动静。
避免：它有 22 个技能是"人才能点火"的（04）。这不是配置问题，是设计——模型碰不到它们，包括别的技能也调不动。
坑 6：把它当"代码质量保险"
症状：以为跑了 /code-review 或者 /improve-codebase-architecture 就等于质量有保障。
避免：作者自己就给了反面说法——improve-codebase-architecture 在 README 里被描述成 a survey, not a rescue（它是勘察报告，不是救援队）。它会在真正年久失修的代码库上找到真问题，但不会替你把泥解开（README 给的用法是每隔几天跑一次）。
坑 7：指望 description 写给人看也写给模型看
症状：自己写技能时，把触发词堆在描述里，又希望界面上读起来好看；两边都不满意。
避免：官方把这件事分得很清——用户可启动的技能，描述写给人看（要删掉触发词列表）；模型可启动的，描述写给模型看（要保留丰富触发措辞）。两个用途不要混在一句里。

10排错：六个最常见的问题

这一节留给"回来查"。每个问题都给出先怀疑哪一层——排查顺序比结论更重要。

1 · 敲了斜杠命令，agent 说没有这个技能

2 · 模型没有自己用那些技能

3 · /to-spec 一敲就中止，让我先去配置

4 · 我按 README 找某个技能，但它不在 Reference 清单里

5 · 用完感觉更慢了，是不是装错了

6 · 它说的问题我不认同，能不能让它别问那么多

📌 排查顺序口诀

装在哪 → 什么桶 / 什么类型 → 配置跑没跑 → 是不是本来就这样设计。前三层你能立刻查，最后一层要回去读一眼 04。

11术语对照表

这张表的第三列不是翻译，而是"为什么重要 / 什么时候用 · 别当什么用"。

术语定义为什么重要 / 何时用 · 别当什么用
skill（技能） 一个带 SKILL.md 的目录；文件里是给 agent 看的指令 它是这套东西的最小单位。别把它当插件或程序——它就是文本，看不懂就打开读，不认同就改。
user-invoked
（用户可启动）		 只有人能敲名字来启动的技能 用来放编排：会连跑多步、会改状态的流程。别指望模型自动用它们——它碰不到。
model-invoked
（模型可启动）		 人和模型都能启动的技能 用来放可复用的纪律（审查、诊断、领域建模）。别把"必须由人决定"的流程放进这一类。
frontmatter Markdown 文件顶部用两行 --- 夹起来的元数据区 技能的"身份证"：名字、描述、以及"模型能不能自动启动"。别把它当注释——它是被程序读的，而且两个代理各有一份（Claude Code 写在 frontmatter，Codex 写在旁边的 agents/openai.yaml），两份要手动同步。
call the Skill tool 技能之间表达依赖的官方写法：明确说"调用 Skill 工具并写出技能名" 决定一个技能能不能被另一个可靠地带动。别写成相对路径引用或在散文里丢一个 /名字 指望模型领会。
GLOSSARY.md 存你这个项目"通用语言"的文档（术语、约定）。v1.3.0 起由 CONTEXT.md 改名而来 让下一轮对话不必重新解释同一个词。别当交付物——它是缓存，不是成果。若你仓库里还叫 CONTEXT.md，技能现在只认 GLOSSARY.md，要 git mv 过去。
ADR Architecture Decision Record：记录"为什么这么决定"的短文档 防止同一个决定被反复推翻。别把每个改动都写成 ADR——它只装那种"以后有人会问为什么"的决定。
tracer bullet
（曳光弹）		 一条贯穿全链路的极小切片：先打通"从输入到输出"的完整路径 用来把大活切成能独立验收的小块（/to-tickets 的产出单位）。别把它当成"按层切"（先写完所有数据库再写所有界面）——那正是它要避免的。
blocking edge
（阻塞边）		 票据之间的"谁必须先完成"关系 让并行和排队有依据。别省掉它——那样票据就退化成一张待办清单。
grilling 就一个计划不停地追问、直到设计树上每个分支都被解决的访谈原语 多个技能的底座。别把它当"AI 在找麻烦"——它替代的是你本来会漏掉的那轮思考。
plugin（插件） Claude Code 的托管分发包 安装路线 A：省心、自动更新、只读。别指望改它——要改就走路线 B。
skills.sh 把技能文件复制进你仓库的安装器 安装路线 B：文件归你、可改、可跨代理。别指望自动更新——升级要你自己敲。

12成对示例：同一件事的两种装法

同一个目标——"我要用上这套技能"——两种做法。

❌ 错误做法：先都装上，回头再挑

动作：先用 Claude Code 插件装一遍，再 npx skills@latest add mattpocock/skills 装一遍，想着"反正多装点不亏"。
结果：

  • 每个技能在你机器上两份，斜杠命令列表里同名项重复；
  • 模型自动触发时命中哪一份不确定——你改了 A 份，生效的可能是 B 份；
  • 升级变成两套机制并行：一套自动（插件）一套手动，你自己也说不清现在跑的是哪版；
  • README 对这件事只有一句：installing both leaves you with every skill twice。
✅ 正确做法：按需求选一条，再固定下来

动作：先回答一个问题——我要不要改它、要不要跨代理？

  • 不要 → 插件：claude plugins install mattpocock-skills，此后不管理版本。
  • 要 → skills.sh：npx skills@latest add mattpocock/skills，勾选时务必含 setup-matt-pocock-skills，之后用 npx skills update 自己控节奏。

然后：每个仓库跑一次 /setup-matt-pocock-skills，再敲 /ask-matt 确认下一步。

❌ 错误做法：把 37 个技能一次学完

从第一个技能开始逐个读文档、背命令，想着"学全了再用"。
结果：读到一半就放弃；真开始用时还是不知道从哪下手，因为决定成败的是顺序，不是命令表。

✅ 正确做法：先跑通一条主流程，再回来加

挑一个真实的小需求，把 grill-with-docs → to-spec → to-tickets → implement → code-review → retro 走一遍（06 的例子里那个"导出当前筛选"就很合适）。走通之后再回来挑：你会自己发现"我这里缺的是 /handoff"或者"我这个 bug 该用 /diagnosing-bugs"——那时的选择比看清单准得多。

13一页纸：装完到用顺的检查清单

从"装完"到"用顺"，这张表按顺序走一遍。

装的时候

#做这件事怎么知道做对了
1只选一条安装路线你清楚自己装的是插件还是文件；没有第二份同名技能
2确认拿到了 setup-matt-pocock-skills斜杠命令列表里能看到它（路线 B 勾选时最容易漏）
3在目标仓库跑一次 /setup-matt-pocock-skills它能问出三个问题：跟踪器 / 标签 / 文档位置；跑完后 /to-spec 不再中止
4敲一次 /ask-matt它给出"你这种情况该用哪个"的建议，而不是直接干活

用的时候

#做这件事怎么知道做对了
5先判断处境，再选技能不是每次都从头套主流程；说不清要什么才用 /grill-with-docs
6让每一步都留下产物规格在跟踪器里、票据有阻塞边、ADR 记了"为什么"
7换会话前先 /handoff新会话能靠那份文档接着干，不用重讲一遍背景
8看不懂就 /wait-what它用你 GLOSSARY.md 里的词汇重讲，而不是再堆一遍术语
9把用不上的技能删掉留下的都是你真会重复用的那几个
📎 如果只能记一条

记这句：22 个技能要你点火，15 个可被自动取用；装只选一条路，用只跑通一条流程。

99一句话总结

🎯 核心要点

mattpocock/skills 是作者公开的 37 个 Markdown 技能文件（engineering 20 / productivity 7 / misc 4 / in-progress 6）：它的定位不是"自动帮你写代码"，而是在你最容易偷懒的那一步插一道闸——最值钱的几个干的事是向你提问、把答案落成文档，所以第一个感受常是"变慢了"，那是设计意图。整套设计只有一条分界线：谁能启动它——你敲着用的 22 个是用户可启动（模型碰不到，连别的技能也调不动；描述写给人看，要删掉触发词），任务合适时自动出现的 15 个是模型可启动（描述写给模型看，要保留触发措辞）；用户可启动的可以调用模型可启动的，反过来不行。安装有两条互斥路线：Claude Code 插件（只读、自动更新、给 27 个技能）或 skills.sh（文件归你、手动升级、能拿到 misc 与 in-progress 那 10 个）——README 的原话是两条都装等于每个技能两份。装完每个仓库都要跑一次 /setup-matt-pocock-skills，否则 /to-spec、/to-tickets、/triage、/code-review 会停下来。典型用法是先跑通一条 grill-with-docs → to-spec → to-tickets → implement → code-review → retro 的主流程（每一步都留下下游能用的产物），再按处境补 /triage、/wayfinder、/handoff、/wait-what；不确定就用路由器 /ask-matt。最后两条实话：三个数字别记混（仓库 37 / README 收录 27 / 插件给 27），以及 improve-codebase-architecture 是勘察报告不是救援队——它找真问题，但不替你解泥。

98参考来源与证据边界

这是一篇"读别人仓库"的文章，所以来源比结论更重要。本文所有事实性陈述都来自下面这些文件，我没有凭记忆写任何一个技能的行为。

一手来源（全部逐字读取）

本文自己做的核对

证据边界与时效

⌂