mattpocock/skills 详解：给"真工程师"的 Agent 技能集
用 AI 写代码的两大流派之争已久：要么交给 GSD、BMAD、Spec-Kit 这类"全流程接管"框架，省心但失去控制权；要么裸奔，全靠手感。TypeScript 圈知名教育者 Matt Pocock（Total TypeScript 作者）开源的 mattpocock/skills 选了第三条路：一小组小而美、可自由魔改、可组合的 Agent 技能——Skills For Real Engineers, not vibe coding。核心的 /grill-me（拷问式需求对齐）、/tdd（红绿重构）、/improve-codebase-architecture（架构巡检）等技能直指 AI 编码四大失败模式。本文从设计哲学、四大痛点解法、技能清单到安装使用，完整拆解。
1、项目概述
这是 Matt Pocock 的日常自用技能集：基于数十年工程经验沉淀，强调小、易改、可组合、任意模型可用。与全流程框架相反，它不接管过程——技能只解决具体失败模式，过程控制权留给工程师。配套订阅渠道是作者约 6 万读者的 AI Hero newsletter。
基本形态与生态：
- 双分发通道：Claude Code 官方插件市场（订阅式只读）+ skills.sh（拷贝式可编辑）
- 两类技能：User-invoked（用户敲命令触发，做编排）与 Model-invoked（模型自动择机使用，承载纪律）
- 覆盖宿主：Claude Code 原生，Codex 等其他 Agent 走 skills.sh 安装器
- 原生 Codex 插件在 Roadmap（ADR 0002 记录决策过程）
2、设计哲学：与全流程框架的分野
README 开篇即立场鲜明：GSD、BMAD、Spec-Kit 试图拥有整个流程，但代价是夺走控制权、流程出 bug 难排查。本仓库反其道而行。
哲学要点：
- 小：每个技能只解决一个失败模式，不做平台
- 易改：技能就是普通文件，欢迎 hack，"Make them your own"
- 可组合：User-invoked 技能可调用 Model-invoked 技能，反向不行
- 模型无关：基于工程共识而非某家模型的特性
引用的思想底座：
- The Pragmatic Programmer：没人确切知道自己要什么；反馈速率是速度上限
- Eric Evans《领域驱动设计》：统一语言让沟通与代码同源
- Kent Beck《解析极限编程》：每天投资于设计
- John Ousterhout《软件设计哲学》：深模块——小接口大功能
3、四大失败模式与对应技能
整个仓库围绕四个 AI 编码高频翻车点组织，每个痛点一个解法技能。
痛点一：Agent 没做我想要的（错位）：
- 解法是"拷问会话"：动手前让 Agent 连环追问细节
- /grill-me：通用拷问；/grill-with-docs：拷问 + 沉淀文档
- 作者评价：最受欢迎的技能，每次改动前都该用
痛点二：Agent 太啰嗦（缺统一语言）：
- 解法是 CONTEXT.md 共享语言文档 + ADR 记录难解释的决策
- 实例：问题"课程某节被'实化'到文件系统" → "materialization cascade 出了问题"
- 附带收益：命名一致、代码库更易导航、思考 token 更省
痛点三：代码跑不起来（反馈回路缺失）：
- 解法三件套：静态类型、浏览器访问、自动化测试
- /tdd：红绿重构循环，一次一个垂直切片
- /diagnosing-bugs：分阶段门控的纪律化调试循环
痛点四：攒出一个泥球（熵增失控）：
- Agent 提速编码的同时也加速软件熵增，代码库复杂度空前膨胀
- /to-spec：写 spec 前先拷问你动了哪些模块
- /improve-codebase-architecture：扫描"加深模块"机会并出 HTML 报告，建议每几天跑一次
- 注意：它是巡查不是救援——老泥球能给候选，不会替你解开
4、技能全景清单
技能按"谁能调用"一条轴切分，Engineering 与 Productivity 两组共二十余个。
Engineering 组（User-invoked 节选）：
- ask-matt：技能路由器，问"我的场景该用哪个技能"
- to-spec / to-tickets：对话转 spec、spec 转带阻塞边的示踪弹票
- implement：按 spec/tickets 实施驱动 /tdd 并以 /code-review 收尾
- wayfinder：超大块工作拆成决策票地图，逐张解决直到路线清晰
- triage：issue 按状态机流转分诊
Engineering 组（Model-invoked 节选）：
- prototype：一次性原型回答设计问题（单 HTML 文件或多 UI 变体）
- research：对着高信任一手资料调研，产出带引用的 Markdown，后台运行
- code-review：双轴评审（仓库规范 + spec 忠实度），并行子代理互不污染
- resolving-merge-conflicts：按双方原始意图逐块解冲突，绝不 --abort
- wizard：生成交互式 bash 向导，带人走过只有人能做的步骤
Productivity 组亮点：
- grill-me / handoff / teach / wait-what（用户调用）
- grilling（拷问原语，多个技能的底层）与 writing-for-agents（模型调用）
5、安装与初始化
两条安装路对应两种哲学：订阅式托管 vs 拷贝式所有，二选一，装两份会技能重复。
# 方式一：Claude Code 官方插件市场（订阅式，随作者更新）
claude plugins install mattpocock-skills
# 或会话内：
/plugin install mattpocock-skills
# 方式二：skills.sh 安装器（拷贝式，可自由编辑）
npx skills@latest add mattpocock/skills
# 交互选择要哪些技能、装到哪些 Agent
# 务必勾选 setup-matt-pocock-skills
# 之后拉更新：npx skills update
# 初始化（每个仓库一次）
/setup-matt-pocock-skills
# - 选 issue 跟踪 器（GitHub / Linear / 本地文件）
# - 配分诊标签（供 /triage 使用）
# - 定文档存放位置安装要点：
1. 只读托管选插件，想魔改选 skills.sh，两者勿混装
2. setup 技能是其余工程技能的前置，装完先跑它
3. Codex 用户暂走 skills.sh，原生插件在 Roadmap
4. 动手改技能是作者鼓励的用法，别当黑盒供着
6、典型应用场景
这套技能的适用画像是"每天真刀真枪写代码、又要与 Agent 协作"的工程师。
常见场景：
- 需求对齐：任何改动前先 /grill-me，把设计树问透再动手
- 大工程规划：/wayfinder 把放不进单个会话的工作拆成决策地图
- 日常保健：定期 /improve-codebase-architecture 巡检架构熵
- 调试硬骨头：/diagnosing-bugs 分阶段门控，防瞎改
- 跨会话接力：/handoff 压缩上下文成移交文档给下一个 Agent
使用提醒：
1. 技能治的是失败模式，不是替你思考：设计判断仍是人的事
2. CONTEXT.md 需要持续维护，荒废的共享语言会失效
3. 架构巡检只找候选不施救，重构决策与执行仍靠人
7、定位对比：Agent 纪律方案三选一
把 mattpocock/skills、obra/superpowers 与 Spec-Kit 类全流程框架放在一张桌上，各自的位置清晰起来。
三者对比：
- mattpocock/skills：小而可改的技能集，治失败模式，控制权在工程师
- superpowers：完整方法论，七步工作流强制接管全流程
- GSD / BMAD / Spec-Kit：重型流程框架，上手快但黑盒程度高
选型建议：
1. 想保留完全控制、按痛点点菜 → mattpocock/skills
2. 想要现成端到端纪律、接受流程接管 → superpowers
3. 团队要标准化 spec 驱动交付 → Spec-Kit 类框架
4. 组合玩法：skills.sh 拷贝后融合自家规范，与 superpowers 按项目混用
8、总结
mattpocock/skills 是 Matt Pocock 的日常实战技能集：围绕"错位、啰嗦、跑不起来、泥球"四大 AI 编码失败模式组织，/grill-me 拷问对齐、CONTEXT.md 共享语言、/tdd 红绿重构、/improve-codebase-architecture 架构巡检各司其职；二十余技能按 User-invoked / Model-invoked 双轴分层，可组合可魔改、模型无关；Claude Code 插件市场订阅与 skills.sh 拷贝两种分发，30 秒安装。思想根基直引《程序员修炼之道》《DDD》《XP 解释》与《软件设计哲学》。
典型用法：/grill-me 与 /tdd 是最高频的两个技能，覆盖"动手前问透、动手后小步"的核心节奏；项目黑话沉淀进 CONTEXT.md，用 /grill-with-docs 边拷问边建语言；架构巡检每几天跑一次，只输出候选不做救援。技能治失败模式，设计判断仍在工程师手中。
