Skills教程
markdown
2026年7月17日10 min read1,824 words
Updated 2026年7月17日
Skills For Real Engineers：AI 工程实践技能库
目录
1. 痛点导入：我们遇到了什么问题？
1.1 AI 编码的四大失败模式
Matt Pocock（TypeScript 培训领域知名专家）在开发 Skills 技能库时，总结了 AI 编程代理的 四大经典失败模式：
| 失败模式 | 表现 | 本质问题 |
|---|---|---|
| #1 不对齐 | "这不是我想要的" | AI 不知道你真正想要什么 |
| #2 太啰嗦 | 回复 500 字，1 个词能说清 | 缺乏共享语言 |
| #3 代码不工作 | 能跑但质量差、测试挂 | 缺乏反馈循环 |
| #4 球状泥球 | 代码越来越乱，无法维护 | 缺乏架构设计意识 |
1.2 根本原因
大多数 AI 编程工具缺少工程 discipline。
AI 擅长生成代码，但不擅长：
- 提问澄清需求
- 建立共享术语
- 构建反馈循环
- 维护代码架构
1.3 Skills 的答案
"These skills are designed to be small, easy to adapt, and composable. They work with any model. They're based on decades of engineering experience."
— Matt Pocock
Skills 不是另一个 AI 工具，而是一套让 AI 遵循软件工程最佳实践的技能库。
2. Skills 是什么？
2.1 一句话定义
Skills 是一个由 Matt Pocock 维护的 AI 编程技能库，基于数十年软件工程经验，专为真实工程师设计。
2.2 与 Superpowers 的对比
2.3 核心定位
Skills 的核心价值：让 AI 做「对」的事，而不是做「多」的事。
3. 核心理念：为什么这样做？
3.1 哲学基础
Skills 的设计基于三本软件工程经典著作的核心理念：
┌─────────────────────────────────────────────────────────────────┐
│ Skills 哲学三角 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ │
│ │ Pragmatic │ │
│ │ Programmer │ │
│ │ "小步前进， │ │
│ │ 快速反馈" │ │
│ └────────┬────────┘ │
│ │ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │Domain-DDD │ │Extreme XP │ │Philosophy │ │
│ │ "共享 │ │ "每日 │ │ of SW │ │
│ │ 语言" │ │ 投资架构"│ │ "深模块" │ │
│ └───────────┘ └───────────┘ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
3.2 四大核心原则
原则一：先对齐，再动手
"No-one knows exactly what they want."
— The Pragmatic Programmer
问题：AI 和用户之间存在沟通鸿沟。
解法：/grill-me、/grill-with-docs — 苏格拉底式追问，直到完全对齐。
原则二：建立共享语言
"With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model."
— Eric Evans, DDD
问题：项目术语不统一，AI 用 20 个词表达 1 个概念。
解法：通过 /grill-with-docs 建立 CONTEXT.md 术语表和 ADRs 决策记录。
原则三：小步前进，快速反馈
"Always take small, deliberate steps. The rate of feedback is your speed limit."
— The Pragmatic Programmer
问题：大任务一次性完成，没有反馈循环。
解法：/tdd — 红-绿-重构循环，每个循环只做一件事。
原则四：每日投资架构
"Invest in the design of the system every day."
— Kent Beck, XP
问题：代码快速累积，架构快速腐化。
解法：/improve-codebase-architecture — 定期扫描重构机会，保持代码可维护性。
4. 技能体系全解
4.1 技能分类概览
Skills 技能库
├── Engineering（工程技能）—— 日常代码工作
│ ├── User-invoked（用户触发）
│ │ ├── ask-matt → 路由：告诉你该用哪个技能
│ │ ├── grill-with-docs → 需求澄清 + 建立领域模型
│ │ ├── triage → 问题分类流转
│ │ ├── improve-codebase-architecture → 架构改进
│ │ ├── setup-matt-pocock-skills → 初始化配置
│ │ ├── to-issues → 计划/PRD 拆解为 Issues
│ │ └── to-prd → 会话转为 PRD
│ └── Model-invoked（模型触发）
│ ├── prototype → 原型验证
│ ├── diagnosing-bugs → 系统化调试
│ ├── tdd → 测试驱动开发
│ ├── domain-modeling → 领域建模
│ └── codebase-design → 模块设计
│
├── Productivity（生产力技能）—— 非代码工作流
│ ├── User-invoked
│ │ ├── grill-me → 需求澄清（无文档）
│ │ ├── handoff → 会话摘要handoff
│ │ ├── teach → 跨会话教学
│ │ └── writing-great-skills → 技能编写指南
│ └── Model-invoked
│ └── grilling → 追问循环（可复用）
│
└── Misc（杂项）—— 偶尔使用
├── git-guardrails-claude-code
├── migrate-to-shoehorn
├── scaffold-exercises
└── setup-pre-commit
4.2 核心技能详解
4.2.1 /grill-me — 需求澄清（无文档）
一句话：对计划或设计进行无情追问，直到每个决策分支都被解决。
使用场景：
- 开始新任务前
- 方案有多个分支不确定
- 需要理清思路
工作原理：
用户: /grill-me "实现支付功能"
AI 追问循环:
├── 支付方式有哪些？（支付宝/微信/银行卡/...）
├── 需要支持退款吗？
├── 资金怎么处理？（先收后付/担保交易/...）
├── 失败重试策略？
├── 幂等性如何保证？
└── ... 直到用户说"够了"或所有分支清晰
关键原则：
- 每个问题必须有多个分支选项
- 追问直到决策树清晰
- 不假设任何未明确的需求
4.2.2 /grill-with-docs — 需求澄清 + 领域建模
一句话：/grill-me 的增强版，同时建立项目共享语言。
与 /grill-me 的区别：
| 维度 | /grill-me |
/grill-with-docs |
|---|---|---|
| 输出 | 对话 | 对话 + CONTEXT.md + ADRs |
| 术语表 | ❌ | ✅ |
| 决策记录 | ❌ | ✅ |
| 适用场景 | 简单任务 | 复杂项目 |
工作流程：
1. 追问需求（与 /grill-me 相同）
2. 发现新术语 → 写入 CONTEXT.md
3. 关键决策 → 写入 docs/adr/ADR-xxx.md
4. 持续维护领域模型
示例：
BEFORE（没有共享语言）:
"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)"
AFTER（共享语言）:
"There's a problem with the materialization cascade"
4.2.3 /tdd — 测试驱动开发
一句话：红-绿-重构循环，一次只做一件事。
核心哲学：
"Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't."
反模式：水平切片
❌ 错误做法：
RED: test1, test2, test3, test4, test5 （一次写完所有测试）
GREEN: impl1, impl2, impl3, impl4, impl5 （一次写完所有实现）
✅ 正确做法：垂直切片（追踪弹）
RED→GREEN: test1 → impl1
RED→GREEN: test2 → impl2
RED→GREEN: test3 → impl3
...
为什么水平切片是错的：
- 测试是「想象」的行为，不是实际行为
- 测试「形状」而非用户可见行为
- 在理解实现前就锁定测试结构
工作流程：
┌──────────────────────────────────────────────────────────────┐
│ TDD 循环 │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ 写一个测试 ┌─────────┐ │
│ │ RED │ ────────────────→ │ 失败 │ │
│ └─────────┘ └────┬────┘ │
│ ↑ │ │
│ │ ▼ │
│ │ ┌─────────┐ │
│ │ │ 写最小 │ │
│ │ │ 代码 │ │
│ │ └────┬────┘ │
│ │ │ │
│ │ 测试通过 ▼ │
│ │ ←──────────────────── ┌─────────┐ │
│ │ │ GREEN │ │
│ │ └────┬────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌─────────┐ │
│ └────────────────────── │ 重构 │ │
│ └─────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
每个循环的检查清单：
[ ] 测试描述行为，不描述实现
[ ] 测试只通过公共接口
[ ] 测试在内部重构后仍能存活
[ ] 期望值来自独立真值，不是从代码计算的
[ ] 代码对该测试最小化
[ ] 没有投机性功能
4.2.4 /diagnosing-bugs — 系统化调试
一句话：构建反馈循环是调试的关键。
六阶段流程：
┌────────────────────────────────────────────────────────────┐
│ 调试六阶段 │
├────────────────────────────────────────────────────────────┤
│ │
│ Phase 1: 构建反馈循环 │
│ ├── 失败测试 → HTTP 脚本 → CLI 调用 → 浏览器脚本 │
│ ├── 目标是找到「能变红」的命令 │
│ └── "没有红-capable 命令，不进 Phase 2" │
│ │
│ Phase 2: 复现 + 最小化 │
│ ├── 让 bug 出现 │
│ ├── 最小化复现场景（每次移除一个元素） │
│ └── 目标：每个剩余元素都是必需的 │
│ │
│ Phase 3: 假设 │
│ ├── 生成 3-5 个假设 │
│ ├── 每个假设必须可证伪 │
│ └── 格式："如果 X 是原因，那么 Y 会让 bug 消失" │
│ │
│ Phase 4: 探测 │
│ ├── 每个探测对应一个假设的预测 │
│ ├── 一次只改一个变量 │
│ └── 优先调试器 > 日志 │
│ │
│ Phase 5: 修复 + 回归测试 │
│ ├── 修复前先写回归测试 │
│ ├── 在正确的「接缝」处写测试 │
│ └── 验证修复 + 运行原始场景 │
│ │
│ Phase 6: 清理 + 复盘 │
│ ├── DEBUG 标签日志全部删除 │
│ ├── 清理临时原型 │
│ └── 问："什么能防止这个 bug？" │
│ │
└────────────────────────────────────────────────────────────┘
核心洞察：
"This is the skill. Everything else is mechanical. If you have a tight pass/fail signal for the bug — one that goes red on this bug — you will find the cause."
4.2.5 /improve-codebase-architecture — 架构改进
一句话：扫描代码库寻找「深化」机会，生成可视化报告。
深化（Deepening）：将浅层模块变成深层模块。
什么是浅层模块？
┌─────────────────────────────────────────────────────┐
│ 浅层模块：接口复杂度和实现复杂度相近 │
├─────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Interface │ │ Implementation │ │
│ │ (100行) │ ≈ │ (120行) │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
│ 价值 ≈ 0，因为你直接用实现也一样 │
│ │
└─────────────────────────────────────────────────────┘
什么是深层模块？
┌─────────────────────────────────────────────────────┐
│ 深层模块：小接口，大实现 │
├─────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Interface │ │ Implementation │ │
│ │ (20行) │ << │ (2000行) │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
│ 高价值：简单接口隐藏复杂逻辑 │
│ │
└─────────────────────────────────────────────────────┘
工作流程：
1. 探索代码库（使用 Explore 子代理）
2. 寻找深化机会
3. 生成 HTML 报告（Mermaid 图表 + 自定义可视化）
4. 用户选择候选
5. /grilling 循环深入设计
6. 侧效应：更新 CONTEXT.md 和 ADRs
4.2.6 /handoff — 会话交接
一句话：将会话压缩成handoff文档，让另一个代理继续。
使用场景：
- 今天做不完，需要明天继续
- 交接给队友
- 另一个项目需要知道当前进度
输出内容：
├── 当前状态
├── 已完成的工作
├── 下一步计划
├── 关键决策（引用 ADRs）
├── 建议的技能（下次应该用哪些）
└── 敏感信息已脱敏
4.3 用户触发 vs 模型触发
关键区别：
| 类型 | 触发方式 | 典型用途 |
|---|---|---|
| User-invoked | 你输入 /xxx |
编排型：澄清需求、任务规划 |
| Model-invoked | AI 自动调用 | 纪律型：TDD、调试、领域建模 |
规则：
- 用户触发技能可以调用模型触发技能
- 模型触发技能不能调用另一个用户触发技能
为什么这样设计？
- 用户触发 = 你想要 AI 做 X
- 模型触发 = AI 需要纪律来做好 X
5. 快速入门：30 秒安装
5.1 前置要求
- Node.js 18+
- 一个支持的 AI 编程工具（Claude Code、Cursor、Codex 等）
5.2 安装步骤
Step 1: 运行安装脚本
npx skills@latest add mattpocock/skills
Step 2: 选择目标工具和技能
安装器会询问：
- 你想安装到哪个 AI 编程工具？
- 你想安装哪些技能？（建议全选）
Step 3: 初始化配置
# 在你的项目中运行
/setup-matt-pocock-skills
这会问你：
- 使用哪个 Issue 追踪器？（GitHub / Linear / 本地文件）
- Triage 时用什么标签？
- 文档保存在哪里？
5.3 快速验证
# 查看可用技能列表
/help
# 测试 grill-me
/grill-me "实现一个待办事项应用"
# 测试 tdd
/tdd
6. 实战演示：典型工作流
场景：开发用户认证模块
典型场景：开发用户认证模块
┌─────────────────────────────────────────────────────────────────────┐
│ Skills 工作流 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Step 1: 需求澄清 ──────────────────────────────────────────────── │
│ │ │ │
│ ├─ 你输入: /grill-with-docs "实现 JWT 认证" │ │
│ │ │ │
│ └─ AI 追问: │ │
│ ├── 认证方式？（JWT / Session） │ │
│ ├── Token 刷新策略？ │ │
│ ├── 密码加密？（bcrypt / argon2） │ │
│ ├── 第三方登录需要吗？ │ │
│ └── 输出: CONTEXT.md + ADR-001.md │ │
│ │
│ Step 2: 任务分解 ──────────────────────────────────────────────── │
│ │ │ │
│ ├─ 你输入: /to-issues │ │
│ │ │ │
│ └─ AI 输出: │ │
│ ├── Issue #1: 用户注册 API │ │
│ ├── Issue #2: JWT 签发与验证 │ │
│ ├── Issue #3: 登录接口 │ │
│ └── Issue #4: Token 刷新机制 │ │
│ │
│ Step 3: 逐个实现 ──────────────────────────────────────────────── │
│ │ │ │
│ ├─ Issue #1 实现: /tdd │ │
│ │ ├── RED: 写失败测试 │ │
│ │ ├── GREEN: 写最小实现 │ │
│ │ └── REFACTOR: 优化 │ │
│ │ │ │
│ └─ 重复 Issue #2, #3, #4... │ │
│ │
│ Step 4: 架构检查 ──────────────────────────────────────────────── │
│ │ │ │
│ └─ /improve-codebase-architecture │ │
│ ├── 扫描模块深度 │ │
│ ├── 生成 HTML 报告 │ │
│ └── 发现深化机会 │ │
│ │
└─────────────────────────────────────────────────────────────────────┘
7. 最佳实践与避坑指南
7.1 使用建议
建议 1：每次任务前先 /grill-me
❌ 不要：直接说"实现 X功能"
✅ 要说：/grill-me "实现 X功能"
为什么：澄清需求的时间永远比返工的时间少。
建议 2：善用 /ask-matt
❌ 不确定用哪个技能？
✅ 输入：/ask-matt "我想做 X，应该用哪个技能？"
建议 3：定期运行架构检查
建议频率：每 1-2 周运行一次 /improve-codebase-architecture
为什么：AI 加速编码的同时也加速代码腐化。
建议 4：维护好 CONTEXT.md
CONTEXT.md 是你和 AI 的共享语言，越丰富越高效。
7.2 常见问题
| 问题 | 解决方案 |
|---|---|
| AI 太啰嗦 | 使用 /grill-with-docs 建立共享语言 |
| 测试写太多 | TDD 只做垂直切片，不要水平切片 |
| 调试太慢 | 先构建「能变红」的命令 |
| 代码越来越乱 | 定期运行 /improve-codebase-architecture |
8. 方法论总结：教程编写范式
8.1 教程结构模板
基于对 Skills 和 Superpowers 的分析，总结出一套教程编写范式：
教程结构：
├── 1. 痛点导入（Why）—— 这个问题为什么重要
├── 2. 工具定位（What）—— 一句话定义 + 与同类对比
├── 3. 核心理念（Why Deep）—— 方法论背后的哲学
├── 4. 技能体系（How）—— 分类讲解 + 核心技能详解
├── 5. 快速上手（Start）—— 5 分钟安装
├── 6. 实战演示（Practice）—— 典型工作流
├── 7. 最佳实践（Tips）—— 经验总结
└── 8. 方法论提炼（Meta）—— 这个教程本身的方法论
8.2 写作原则
原则 1：先痛点，后方案
❌ "这个工具可以 X、Y、Z..."
✅ "你是否遇到过 A 问题？这个工具就是来解决它的。"
原则 2：用类比降低理解门槛
❌ "TDD 是红-绿-重构循环"
✅ "TDD 就像先写考题再写答案——你得先知道『考什么』才知道『怎么答』"
原则 3：图表胜于文字
用图说明：
- 工作流程（流程图）
- 概念关系（图的关系）
- 对比差异（表格 + 图）
原则 4：代码示例要「可运行」
❌ 伪代码
✅ 实际可运行的代码片段
原则 5：引用权威来源
引用经典著作、论文、知名专家的话
→ 增加可信度
→ 提供深入学习的路径
8.3 格式规范
| 元素 | 规范 |
|---|---|
| 标题 | H1 一级标题，H2 二级标题 |
| 代码块 | 指定语言（bash, typescript, json...） |
| 表格 | 清晰对齐，表头加粗 |
| 图表 | 使用 Excalidraw/ASCII 图 |
| 引用 | 使用 > 引用块，标注来源 |
| 检查清单 | 使用 [ ] 格式 |
8.4 内容深度分层
基础层：是什么、怎么用（80% 的读者）
├── 一句话定义
├── 安装步骤
├── 基础用法
└── 典型场景
进阶层：为什么、怎么做好（15% 的读者）
├── 方法论原理
├── 最佳实践
├── 常见问题
└── 与其他工具对比
深度层：方法论提炼（5% 的读者）
├── 这个工具背后的哲学
├── 如何用这个范式写其他教程
└── 如何扩展和定制
8.5 后续教程模板
当你要写其他工具的教程时，可以直接套用这个模板：
# [工具名]：一句话描述
## 目录
[按上述结构]
## 1. 痛点导入
- 这个工具解决什么问题？
- 为什么这个问题重要？
## 2. 工具定位
- 一句话定义
- 与同类工具对比表
## 3. 核心理念
- 方法论哲学
- 引用权威来源
## 4. 技能体系全解
- 分类图
- 核心技能详解（每个技能：场景 + 原理 + 示例）
## 5. 快速入门
- 安装步骤
- 验证命令
## 6. 实战演示
- 典型工作流图
- 完整示例
## 7. 最佳实践
- 使用建议
- 常见问题
## 8. 方法论总结
- 这个教程的写作方法论
- 如何用于后续教程
参考资源
本教程由 Claude Code 生成，基于「痛点-方案-方法论」三层结构编写。