二、快速安装（30秒）
# 方式一：使用官方安装器
npx skills@latest add mattpocock/skills
# 方式二：手动克隆
git clone https://github.com/mattpocock/skills.git ~/.claude/skills
安装后选择需要的技能，务必选择 /setup-matt-pocock-skills 进行初始化配置。
三、核心技能详解
3.1 /grill-me — 需求澄清面试
用途：在开始编码前，让 AI 对你进行"压力面试"，逐个分支理清需求。
工作流程：
用户：我要实现用户登录功能
AI：用户用什么方式登录？邮箱？手机？第三方OAuth？
用户：邮箱和手机都要支持
AI：手机登录需要验证码吗？用哪个服务商？
...（逐层深入，直到所有分支都被解决）
适用场景：
- 新功能开发前的需求梳理
- 技术方案设计评审
- 任何"我还没想清楚"的时刻
3.2 /grill-with-docs — 带文档的需求澄清
升级版 /grill-me，额外功能：
- 自动维护 CONTEXT.md — 项目领域词汇表
- 自动生成 ADR — 架构决策记录
- 检测术语冲突 — 当你说"账户"时，AI 会问："你指的是 Customer 还是 User？"
文档结构：
project/
├── CONTEXT.md # 领域词汇表
├── docs/
│ └── adr/ # 架构决策记录
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/
示例：
- 修改前："课程视频管理器里有个问题，当课程里的章节的视频变成'真实'的时候会出错"
- 修改后："materialization cascade 有问题"
这种简洁性在每次会话中都会产生复利效应。
3.3 /tdd — 测试驱动开发
核心原则：测试验证行为，而非实现细节。
正确做法（垂直切片）：
RED→GREEN: test1→impl1
RED→GREEN: test2→impl2
RED→GREEN: test3→impl3
错误做法（水平切片）：
RED: test1, test2, test3, test4, test5
GREEN: impl1, impl2, impl3, impl4, impl5
关键规则：
- 一次只写一个测试
- 只写让当前测试通过的最少代码
- 不要预判未来测试
- 测试聚焦于可观察行为
好测试 vs 坏测试：
| 好测试 | 坏测试 |
|---|---|
| 测试公共接口 | 测试私有方法 |
| 验证用户行为 | 验证内部结构 |
| 重构后仍通过 | 重构后失败 |
3.4 /diagnose — 系统化调试
六阶段诊断循环：
Phase 1: 构建反馈循环 ← 最关键！
Phase 2: 复现 Bug
Phase 3: 生成 3-5 个可证伪假设
Phase 4: 逐个验证假设
Phase 5: 修复 + 回归测试
Phase 6: 清理 + 事后分析
构建反馈循环的 10 种方式（按优先级）：
- 失败测试 — 单元/集成/E2E 测试
- Curl/HTTP 脚本 — 针对 API
- CLI 调用 + 快照对比
- 无头浏览器脚本 — Playwright/Puppeteer
- 重放捕获的请求
- 一次性测试骨架
- 属性/模糊测试
- 二分查找骨架
- 差分对比
- 人机协作脚本 — 最后手段
关键洞察：
构建正确的反馈循环，Bug 就已经解决了 90%。
3.5 /to-prd — 产品需求文档生成
流程：
- 探索代码库，理解当前状态
- 勾勒需要构建/修改的模块
- 确认测试策略
- 发布 PRD 到 Issue Tracker
PRD 模板：
## Problem Statement
用户视角的问题描述
## Solution
用户视角的解决方案
## User Stories
1. As a <actor>, I want <feature>, so that <benefit>
## Implementation Decisions
- 模块设计决策
- 接口变更
- 技术澄清
## Testing Decisions
- 测试策略
- 测试范围
## Out of Scope
不在本次范围内的事项
3.6 /improve-codebase-architecture — 架构改进
目标：发现深化机会——将浅模块转化为深模块。
核心词汇：
| 术语 | 定义 |
|---|---|
| Module | 有接口和实现的任何东西 |
| Interface | 调用者必须知道的一切 |
| Implementation | 内部代码 |
| Depth | 接口的杠杆率 |
| Seam | 接口所在的位置 |
| Adapter | 满足接口的具体实现 |
深度判断标准：
- 删除测试：想象删除模块，复杂度是消失还是转移到 N 个调用方？
- 一个适配器 = 假设缝；两个适配器 = 真缝
工作流程：
- 探索代码库，寻找摩擦点
- 呈现候选改进点
- 逐个讨论设计方案
- 更新 CONTEXT.md 和 ADR
3.7 /setup-matt-pocock-skills — 初始化配置
必须首先运行，配置三个关键设置：
- Issue Tracker — GitHub / GitLab / 本地 Markdown
- Triage Labels — 五个标准标签映射：
needs-triage— 需要评估needs-info— 等待更多信息ready-for-agent— AFK 可执行ready-for-human— 需要人工实现wontfix— 不予处理
- Domain Docs — 单一上下文或多上下文布局
四、架构图
4.1 技能系统架构
┌─────────────────────────────────────────────────────────────────┐
│ Matt Pocock Skills 架构 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Productivity │ │ Engineering │ │ Misc │ │
│ ├─────────────┤ ├─────────────┤ ├─────────────┤ │
│ │ grill-me │ │ tdd │ │ git-guardrails│ │
│ │ grill-with-docs│ │ diagnose │ │ setup-pre-commit│ │
│ │ caveman │ │ to-prd │ │ migrate-to-shoehorn│ │
│ │ handoff │ │ to-issues │ │ scaffold-exercises│ │
│ │ write-a-skill│ │ triage │ └─────────────┘ │
│ └─────────────┘ │ improve-* │ │
│ │ zoom-out │ │
│ │ prototype │ │
│ │ setup-* │ │
│ └─────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 支撑文档系统 │ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │ CONTEXT.md ─── 领域词汇表（共享语言） │ │
│ │ docs/adr/ ─── 架构决策记录 │ │
│ │ docs/agents/ ─ 技能配置文件 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
4.2 工作流程图
用户意图
│
▼
┌──────────────┐
│ /grill-me │ ←─────── 需求澄清
│ /grill-with-docs│ 更新 CONTEXT.md
└──────┬───────┘
│
▼
┌──────────────┐
│ /to-prd │ ←─────── 生成 PRD
│ /to-issues │ 拆分为 Issues
└──────┬───────┘
│
▼
┌──────────────┐
│ /tdd │ ←─────── 红-绿-重构循环
└──────┬───────┘
│
├─── Bug? ──→ /diagnose ──→ /tdd
│
▼
┌──────────────┐
│ /improve-* │ ←─────── 定期架构改进
└──────────────┘
4.3 深模块 vs 浅模块
深模块（理想状态）
┌─────────────────────────────────────┐
│ 简单接口 │
│ ┌───────────────────────┐ │
│ │ 复杂实现 │ │
│ │ ┌─────────────────┐ │ │
│ │ │ 业务逻辑 │ │ │
│ │ │ 数据处理 │ │ │
│ │ │ 边界情况 │ │ │
│ │ └─────────────────┘ │ │
│ └───────────────────────┘ │
└─────────────────────────────────────┘
杠杆率高：调用者简单，维护者集中
浅模块（需要改进）
┌─────────────────────────────────────┐
│ 复杂接口 │
│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │配置1│ │配置2│ │配置3│ │配置4│ │
│ └──┬──┘ └──┬──┘ └──┬──┘ └──┬──┘ │
│ │ │ │ │ │
│ ┌──▼──┐ ┌──▼──┐ ┌──▼──┐ ┌──▼──┐ │
│ │实现1│ │实现2│ │实现3│ │实现4│ │
│ └─────┘ └─────┘ └─────┘ └─────┘ │
└─────────────────────────────────────┘
杠杆率低：调用者复杂，维护者分散
五、最佳实践
5.1 每次开发前的检查清单
[ ] 运行 /grill-with-docs 澄清需求
[ ] 确认 CONTEXT.md 中的术语定义
[ ] 检查相关 ADR 避免重复决策
[ ] 使用 /tdd 开始开发
[ ] 完成后运行 /improve-codebase-architecture
5.2 文档维护原则
CONTEXT.md 应包含：
- 领域专家理解的术语
- 业务概念的定义
- 模块之间的边界
CONTEXT.md 不应包含：
- 实现细节
- 数据库字段
- API 端点
ADR 创建条件（三个必须同时满足）：
- 难以逆转 — 改变成本高
- 没有上下文会令人困惑
- 是真正的权衡结果
5.3 调试心态
不要问："为什么代码不工作？"
要问： "反馈循环够快吗？信号够清晰吗？"
六、与其他工具对比
| 特性 | Matt Pocock Skills | GSD/BMAD/Spec-Kit |
|---|---|---|
| 控制权 | 用户主导 | 框架主导 |
| 灵活性 | 可组合、可定制 | 固定流程 |
| 学习曲线 | 低（独立技能） | 高（完整方法论） |
| 适用规模 | 小到大型项目 | 中大型项目 |
| 过度设计风险 | 低 | 高 |
七、总结
Matt Pocock Skills 的核心理念：
软件工程基础比以往任何时候都重要。
这些技能将数十年的工程经验浓缩为可重复的实践。
推荐使用顺序：
/setup-matt-pocock-skills— 初始化/grill-with-docs— 每次新功能前/tdd— 开发过程中/diagnose— 遇到 Bug 时/improve-codebase-architecture— 定期运行
参考资源
- GitHub 仓库
- 作者 Newsletter
- skills.sh 安装器
- 《程序员修炼之道》— David Thomas & Andrew Hunt
- 《领域驱动设计》— Eric Evans
- 《软件设计哲学》— John Ousterhout