用 AI 写代码这件事，我已经过了「装个工具就起飞」的阶段。真正让我留下来的，是一套能约束 agent 行为的纪律系统。最近我把 mattpocock/skills 完整装进一个项目试用了一圈，这篇指南记录它是什么、怎么装、怎么用，以及我踩到的坑。
先介绍主角：Matt Pocock 是 Total TypeScript 的作者，大概是 TypeScript 社区最有名的教育者。他把自己的 .agents 目录直接开源了——仓库简介就一句话：Skills for Real Engineers, Straight from my .agents directory。配套官网 aihero.dev/skills 上的定位也说得很直白：给「想用 AI 又不想放弃自己标准」的工程师用的 skill 系统。
它和我之前看过的 GSD、BMAD、Spec-Kit 这类重型框架是反着来的：不接管你的开发流程，不规定你从需求到上线走哪几步，只提供一批小而可组合的工程纪律件，任意模型、任意 agent 都能用。你可以只装一个 tdd，也可以装全套走 spec 驱动——都是你说了算。
25skills · 2026-09
18 + 7Engineering · Productivity
MIT协议
CC · Codex
Cursor · Pi均可使用
一、它解决什么：四种失败模式
作者把和 agent 协作的失败归纳成四种，每个 skill 都是对其中一种的修复。理解了这个框架，25 个 skill 就不用死记了。
01Agent 做的不是我想要的对齐失败：你以为它懂了，交付才见真章开工前拷问式访谈，把设计树的每个分支问透grill-me · grill-with-docs
02Agent 太啰嗦、术语混乱缺共享语言，二十个词讲一个概念领域词汇表 CONTEXT.md + ADR，一个词顶二十个词grill-with-docs · domain-modeling
03代码跑不起来缺反馈环，agent 盲飞红-绿-重构 TDD + 纪律化调试循环tdd · diagnosing-bugs
04搓成大泥球agent 在加速产出，也在加速软件熵增每天投资设计：深模块、小接口、干净接缝codebase-design · improve-codebase-architecture
展开说：
失败模式 1 是对齐失败。 你以为三句话把需求讲清楚了，agent 也「懂了」，交付出来才发现它理解的和你想的不一样。修复方式不是把 prompt 写得更长，而是让 agent 在开工前反过来面试你——直到需求里不存在没做决定的分支。
失败模式 2 是缺共享语言。 同一个概念，你叫「订单」，agent 这轮叫「工单」，下轮叫「任务」，沟通成本全部浪费在澄清上。修复方式是把领域词汇沉淀成文档，让每一轮对话都站在同一套词表上。
失败模式 3 是缺反馈环。 没有测试的 agent 是盲飞：改了代码不知道改对没有，只能靠「看起来对了」。修复方式是给它一个能变红的反馈环——先让测试红，再让测试绿。
失败模式 4 最隐蔽：agent 在加速产出，也在加速软件熵增。 它一晚上能生成三千行代码，如果没有设计纪律，这三千行就是明天的技术债。修复方式是把「深化模块」变成日常投资，而不是等烂透了再抢救。
二、先搞懂分类法：谁能触发，决定它是什么
25 个 skill 分 Engineering（18 个，日常代码工作）和 Productivity（7 个，通用工作流）两大类，但真正决定用法的是另一个维度——谁能触发它：
- User-invoked（手动触发）：只能你显式输入
/xxx 才会运行。它们的职责是编排——组织一次访谈、拆一批工单、跑一次评审。 - Model-invoked（自动触发）：模型可以根据上下文自动调用，你也可以直说「use tdd」来点名。它们承载的是可复用的纪律。
Engineering18个
手动 9 · 自动 9日常代码工作：需求对齐、spec、工单、实施、评审、架构 Productivity7个
手动 5 · 自动 2通用工作流：访谈、交接、教学、问卷、重讲 手动触发 可调 自动触发 ✓自动触发 调 手动触发 ✗—— 你是机长，负责发起和编排；agent 在被编排的流程里执行纪律
这也解释了为什么 grill-me（手动）和 grilling（自动）是两个 skill：前者是入口，后者是被五个 skill 共用的底层访谈引擎。
三、安装：两条官方通道，只选一条
Claude Code 插件只读订阅
claude plugins install mattpocock-skills
skill 文件归插件管理，随上游自动更新，你不能改。适合只用 Claude Code、不想折腾的人。
覆盖端：仅 Claude Code · 零维护
skills.sh可编辑拷贝
npx skills@latest add mattpocock/skills
交互选择装哪些 skill、装到哪些 agent（Claude Code、Codex、Cursor……），把可编辑的文件拷进你的项目，想改就改。
覆盖端：多 agent · 可定制 · 更新用 npx skills update
⚠ 双通道双装 = 每个 skill 两份README 明确警告。装之前选定一条，只走一条。
skills.sh 通道有个细节要知道：它把实体装到 ~/.agents/skills/（全局）或项目的 .agents/skills/ 里。如果你的 agent 们各自扫描各自的目录（Claude Code 扫 .claude/skills，Codex 扫 .agents/skills，Cursor 又是一套），同一个 skill 会被多个端自动发现，和你已有的同名 skill 互相遮蔽。多端用户装完后值得检查一遍各端实际加载的是哪一份。
装完第一件事：每个仓库初始化一次
工程类 skill 需要「issue tracker 在哪、文档放哪」这类仓库级信息。所以在每个要用的仓库里先跑一遍初始化，它会问你三件事：issue tracker 用哪个（GitHub / Linear / 本地文件）、triage 时打什么标签、生成的文档存在哪个目录。这一步是其他工程类 skill 的前置——to-spec 要往 tracker 发 spec，triage 要用标签，都依赖这里的配置。
我的多端做法：一份实体，软链到各端
我在 Claude Code、Codex、Cursor、pi 四个端之间切换，所以没走上面的通道，而是手动装：实体放一个统一目录（我的 single source of truth），再往各端的 skills 目录建软链。好处是四端共享一份内容、改一处全生效，升级时重拷实体即可，链不用动。
如果你也在多端环境，可以参考这个布局：.agents/skills/ 放实体（Codex、Cursor 原生就能扫到），.claude/skills/ 建软链给 Claude Code。把这些目录加进 .gitignore，skill 配置就不进业务仓库的提交历史。
四、25 个 skill 速查表
不用全装，README 自己也说「install the ones you want」。下面是全景：
Engineering18 个 · 日常代码工作
手动触发 · 9只能你 /xxx 点名，职责是编排
/ask-matt路由器：不知道用哪个 skill 时问它，它推荐合适的流程
/setup-matt-pocock-skills每仓一次的初始化：选 tracker、triage 标签、文档位置，其他工程类 skill 的前置
/grill-with-docs★拷问式访谈 + 领域建模：逼问需求的同时更新 CONTEXT.md 和 ADR，作者最推荐、每次改码前都用
/to-spec把当前对话综合成 spec 发到 tracker，不再访谈，纯合成
/to-tickets把计划拆成 tracer-bullet 工单，每张声明阻塞边（本地文件或 tracker 原生 blocking 链接）
/implement★按 spec / 工单实施：在预定接缝处驱动 tdd，收尾过 code-review 才提交
/wayfinder超大块工作的决策工单地图：单会话装不下时铺路用，逐张解决直到路径清晰
/triageissue / 外部 PR 过 triage 状态机：分类、验证、必要时 grill，产出 agent-ready 简报
/improve-codebase-architecture扫描「深化模块」机会，可视化 HTML 报告，对你选中的项深入 grill；每几天一次，是普查不是抢救
自动触发 · 9模型可自行调用，承载可复用纪律
tdd★红-绿-重构循环，一次一个垂直切片
code-review同名冲突★双轴并行评审 diff：Standards（仓库规范 + 坏味道基线）∥ Spec（是否忠实实现原始 issue），双子代理互不污染
diagnosing-bugs硬 bug / 性能回归诊断循环：造能变红的反馈环 → 最小化 → 假设 → 插桩 → 修 → 回归测试
prototype一次性原型回答设计问题：状态 / 逻辑出单 HTML 文件，UI 问题出多个截然不同的变体
research后台代理对高信源做一手调研，产出带引用的 Markdown 存进仓库
domain-modeling挑战术语 vs 词汇表、边界场景压测、就地更新 CONTEXT.md 和 ADR
codebase-design深模块设计的共享词汇：大量行为藏在小接口后、放在干净接缝处、经接口可测
resolving-merge-conflicts逐 hunk 按意图解 merge / rebase 冲突，追溯两侧一手来源，绝不 --abort
wizard给「只有人能做的步骤」生成交互式 bash 向导：开基础设施、配密钥 / CI secrets、一次性迁移
Productivity7 个 · 通用工作流
手动触发 · 5只能你 /xxx 点名
/grill-me纯拷问访谈（不带文档产出），非代码场景也能用
/handoff把当前会话压缩成交接文档，另一个 agent 无缝接手
/teach多会话教学：当前目录作有状态教学工作区，跨会话教你一个概念
/to-questionnaire把你答不了的决策变成 Markdown 问卷，交给能答的人（异步填或会上一起）
/wait-what没看懂 agent 刚说的话？立刻触发，用你项目的词汇表重新讲一遍
自动触发 · 2被其他 skill 复用的底层原语
grilling底层访谈引擎：grill-me / grill-with-docs / triage / wayfinder / improve-codebase-architecture 共用
writing-for-agents写 agent 会读的文档（skill、AGENTS.md / CLAUDE.md）的写作纪律
★ = 我优先推荐的起点；code-review 的「同名冲突」见第七节。
五、主链工作流：spec 驱动开发
这些 skill 组合出的完整主链是这样的：
/setup-matt-pocock-skills每仓一次 · tracker / 标签 / 文档位置
↓
/grill-with-docs拷问对齐 · 沉淀 CONTEXT.md + ADR
↓
/to-spec对话综合成 spec · 发到 tracker
↓
/to-ticketsspec → tracer-bullet 工单 · 声明阻塞边
↓
/implement按工单实施 · 评审通过才提交内部驱动tdd红 → 绿 → 重构收尾code-reviewStandards ∥ Spec 双轴
↓
commit
不必每次走全程，还有两条更轻的走法：聊完需求直接 /to-tickets（跳过正式 spec）；或者对话本身就是 spec，直接 /implement。重活走全程，小改动走轻链。
走一个具体例子
假设我想给这个博客加一个「阅读进度条」，主链会这样跑：
1/grill-with-docs · 反过来面试你它不是听完就开工，而是逼问你：进度条按整页算还是只按正文区算？手机上要不要显示？要不要和右侧目录的当前小节联动？滚动监听放在哪个组件、节流多少毫秒？——每个分支都问到你给出明确答案为止。同时把过程中出现的术语（「正文区」「小节高亮」）沉淀进 CONTEXT.md，下次对话直接复用。
2/to-spec · 综合成 spec不再提问，把刚才的对话综合成一份 spec：目标、行为定义、边界情况、验收标准，发到你配置的 issue tracker。
3/to-tickets · 拆成有依赖边的工单spec 被拆成一组小工单：工单一「实现滚动百分比计算」（阻塞工单二）、工单二「渲染进度条组件」、工单三「暗色模式适配」。每张声明它阻塞谁，形成一张依赖图，而不是一个含混的大任务。
4/implement · 纪律化实施按工单顺序实施，在合适的接缝处自动进入 tdd 循环——先写测试变红，再写实现变绿，然后重构。收尾跑 code-review：一个子代理按仓库规范和坏味道基线审 Standards 轴，另一个对照原始 spec 审忠实度轴，两轴并行、互不污染，评审通过才提交。
整个过程里我只做了两件事：回答问题、拍板决定。这正是设计意图——把「想清楚」的负担前置到人身上，把「做扎实」的纪律交给 agent。
六、支线工作流
主链之外，几条按场景取用的支线：
超大工程 /wayfinder
在 tracker 上铺一张决策工单地图，逐张解决直到通往目的地的路径清晰，再回主链实施
日常维护 /improve-codebase-architecture
扫报告 → 选一项 grill 深入 → 实施；每几天一次，是普查不是抢救
issue 治理 /triage
issue / 外部 PR 过分类、验证，产出 agent-ready 简报喂给 /implement
调试 · 说 "diagnose this"
进入六阶段诊断循环：先造出能变红的反馈环，再最小化、假设、插桩、修、回归测试
会话换手 /handoff
当前对话压缩成交接文档，下一个 agent 无缝接手
没看懂 /wait-what
用项目词汇表把 agent 上一条消息重新讲一遍
需求方不是你 /to-questionnaire
把你答不了的决策变成问卷，发给能答的人（异步填或会上一起）
/teach 值得单独一提：它把当前目录当作有状态的教学工作区，跨多个会话教你一个概念。我用 agent 学新东西时最头疼的就是每开一个新会话就要重新自我介绍一遍，这个 skill 解决的正是那件事。
七、避坑清单
实测下来，这些坑提前知道能省不少事：
⚠ 最大的坑 · code-review 同名冲突
很多人（包括我）本来就有一套自己定制的 code-review skill。matt 版套件里的 ask-matt、implement、tdd 会按名调用它，所以这个同名冲突是结构性的，不是改个叫法就完。我的处置：原有版本改名让位，让 matt 版占住原名，首次使用时留意实际触发的是哪一版。你也可以反过来跳过 matt 版——implement 调 code-review 时会落到你自己的版本上，功能等价。
R2安装位置与多端遮蔽。skills.sh 把实体装到 .agents/skills 一类公共位置，多个 agent 端都会自动扫到。如果你有自己的 skill 管理体系，装完检查各端实际加载的版本，避免脱管副本或死链。
R3只读插件 vs 可编辑拷贝的取舍。插件通道自动跟随上游更新，但你一个字都改不了；skills.sh 拷贝的文件完全归你，但上游更新要手动拉。想深度定制（比如把 grilling 的访谈风格改成中文语境），必须走拷贝通道。
R4per-repo setup 是硬依赖。工程类 skill 建立在「有 issue tracker、有文档目录」的假设上，适合业务代码仓库。在纯配置仓库或文档仓库里，只有 productivity 类有意义，别指望 to-spec 在没有 tracker 的地方工作。
R5它不会替你接管流程。如果你想要的是「一句话从需求干到上线」的全自动流水线，这个仓库给的是反方向的东西：更多的人工检查点、更严的纪律。它提高的是交付质量的下限，不是省掉你参与的程度。
八、值不值得装
我的结论：值得，但要按需。
它最适合的人，是已经受过 agent 之害——需求跑偏、术语混乱、测试缺失、架构滑坡——并且愿意在流程里保留「人拍板」位置的工程师。如果你还在 vibe coding 的蜜月期，先装一个 tdd 感受纪律件是什么，比直接上全套主链更实际。
我的用法是渐进式的：先在一个项目里完整试用 25 个，跑一段时间，把真正进入肌肉记忆的那些转正为全局。目前看 /grill-with-docs 和 tdd 大概率会留下——前者治好了我「三句话布置任务」的旧习惯，后者让 agent 的每一行代码都有测试兜底。
▸第一步 选一条通道装好→第二步 仓库里跑 /setup-matt-pocock-skills→第三步 下个功能开工前，先 /grill-with-docs
被它拷问一轮之后，你对「自己到底想要什么」的了解，会比读任何教程都深。
评论
欢迎交流。阅读无需登录，发表评论需要登录 GitHub；评论会公开保存在 GitHub Discussions。
在 GitHub 中查看讨论 ↗ · 加载不出来时也可以从这里参与。