mattpocock/skills 完整使用教程

# mattpocock/skills 完整使用教程

> Skills for Real Engineers —— 把软件工程最佳实践编码成 Claude Code 可执行的斜杠命令。

---

## 目录

1. [前置要求](#前置要求)
2. [安装](#安装)
3. [初始化](#初始化)
4. [Skills 详解与使用示例](#skills-详解与使用示例)
5. [推荐工作流](#推荐工作流)
6. [常见问题](#常见问题)

---

## 前置要求

- 已安装 **Node.js**（用于运行 `npx`）
- 已安装并能正常使用 **Claude Code**
- 有一个项目目录（skills 是按项目安装的）

---

## 安装

### 第一步：在项目根目录运行安装命令

```bash
cd your-project
npx skills@latest add mattpocock/skills
```

### 第二步：选择 Agent

```
? Which coding agent do you want to install skills for?
  ○ Cursor
  ○ Windsurf
❯ ● Claude Code
  ○ Copilot
```

用方向键选中 **Claude Code**，回车确认。

### 第三步：选择要安装的 Skills

```
? Which skills do you want to install?
  ◉ setup-matt-pocock-skills    ← 必选，其他 skill 依赖它
  ◉ grill-with-docs
  ◉ tdd
  ◉ diagnose
  ◉ handoff
  ◉ zoom-out
  ◉ to-prd
  ◉ to-issues
  ○ triage
  ○ caveman
  ○ improve-codebase-architecture
  ○ prototype
  ○ grill-me
  ○ write-a-skill
  ○ git-guardrails-claude-code
```

**空格键**勾选，**回车**确认。

> ⚠️ `setup-matt-pocock-skills` 必须勾选，它是所有其他 engineering skill 的初始化入口。

### 安装结果

Skills 以 Markdown 文件的形式写入项目的 `.claude/commands/` 目录：

```
your-project/
└── .claude/
    └── commands/
        ├── setup-matt-pocock-skills.md
        ├── grill-with-docs.md
        ├── tdd.md
        ├── diagnose.md
        ├── handoff.md
        └── zoom-out.md
```

---

## 初始化

安装完成后，在 Claude Code 里运行初始化命令（**每个新项目只需运行一次**）：

```
/setup-matt-pocock-skills
```

Claude Code 会问你三个问题：

### 问题 1：Issue Tracker

```
? 你用什么 issue tracker？
❯ GitHub Issues
  Linear
  本地文件
```

根据你的项目实际情况选择。

### 问题 2：Triage 标签

```
? 你用哪些标签来分类 issue？
> bug, feature, chore
```

输入你项目中实际使用的标签，逗号分隔。

### 问题 3：文档目录

```
? 生成的文档保存在哪里？
> docs/
```

初始化完成后，项目根目录会出现：

```
your-project/
├── CONTEXT.md        ← 项目术语表，AI 的"共同语言"
└── docs/
    └── adr/          ← 架构决策记录
```

> 💡 `CONTEXT.md` 是这套 skills 的核心。它会随着每次 `/grill-with-docs` 逐渐积累项目专属词汇，让 AI 每次对话都说"同一种语言"。

---

## Skills 详解与使用示例

### `/grill-with-docs` — 需求澄清（最常用）

**适用场景**：开始任何新功能之前，先把需求问清楚。

**用法**：

```
/grill-with-docs 我要做一个用户登录功能
```

**Claude Code 会连续追问**：

```
1. 登录方式支持哪些？用户名密码、手机号、第三方 OAuth？
2. 需要"记住我"功能吗？token 有效期多长？
3. 登录失败几次后锁定账号？
4. 需要多设备同时登录吗？
5. 密码找回走邮箱还是手机？
```

**追问结束后自动做两件事**：
1. 更新 `CONTEXT.md`，把新出现的术语写进去
2. 在 `docs/adr/` 下记录关键设计决策

---

### `/tdd` — 测试驱动开发

**适用场景**：实现一个具体功能，需要可靠的测试保障。

**用法**：

```
/tdd 实现 JWT token 验证中间件
```

**Claude Code 自动走红绿重构循环**：

```javascript
// ① 红：先写失败的测试
test('过期 token 应返回 401', () => {
  const res = verifyToken('expired.token.here')
  expect(res.status).toBe(401)
})
// ❌ 测试失败（函数还没写）

// ② 绿：写最简实现让测试通过
function verifyToken(token) {
  try {
    jwt.verify(token, SECRET)
    return { status: 200 }
  } catch {
    return { status: 401 }
  }
}
// ✅ 测试通过

// ③ 重构：补充边界情况测试
test('无效签名应返回 401', ...)
test('正常 token 应返回用户信息', ...)
test('空 token 应返回 401', ...)
```

你不需要说"先写测试"，流程自动走，每步都有明确的通过/失败反馈。

---

### `/diagnose` — 系统性 Debug

**适用场景**：遇到难以定位的 Bug，需要系统性排查。

**用法**：

```
/diagnose Prisma migrate dev 报错 P3009，提示有 failed migration
```

**Claude Code 走标准五步排查**：

```
Step 1 复现
  → 用最小命令确认能稳定触发 ✓

Step 2 最小化
  → 新建空项目测试，问题消失
  → 定位到 migration 历史记录冲突

Step 3 假设（按可能性排序）
  → 假设 A：_prisma_migrations 表有 failed 标记
  → 假设 B：迁移文件被手动修改过

Step 4 验证
  → SELECT * FROM _prisma_migrations WHERE applied = 0;
  → 发现两条 failed 记录 ← 找到了

Step 5 修复 + 防止复发
  → prisma migrate resolve --rolled-back <migration_id>
  → 补充一条注释：不要手动修改已应用的迁移文件
```

---

### `/zoom-out` — 理解陌生代码

**适用场景**：接手别人的代码，或者看不懂某段逻辑在系统里的作用。

**用法**：

```
/zoom-out 解释一下 AuthMiddleware 在整个请求链路里的位置
```

**Claude Code 不只解释这一个函数**，而是给出系统级视角：

```
AuthMiddleware 在整个请求链路中的位置：

HTTP Request
  → Rate Limiter（限流）
  → AuthMiddleware（你问的这个）← 在这里
      - 取 Authorization header
      - 验证 JWT
      - 把 user 对象注入 req.user
  → Route Handler
  → Response

它的上游依赖：JWTService
它的下游消费者：所有需要鉴权的路由 Handler
如果它挂了，影响：所有需要登录的接口全部 401
```

---

### `/handoff` — 上下文交接

**适用场景**：一个 session 的 token 快用完了，但任务还没做完。

**用法**：

```
/handoff
```

**生成的交接文档示例**：

```markdown
## 当前进度
正在实现用户登录功能，JWT 验证中间件已完成并测试通过。

## 已完成
- [x] POST /auth/login 接口
- [x] JWT 生成与验证
- [x] 单元测试覆盖主要分支

## 未完成
- [ ] Refresh Token 机制
- [ ] 登录失败锁定逻辑（失败 5 次锁定 30 分钟）
- [ ] 接入邮件服务发送验证码

## 关键决策
- Token 有效期设为 24h，Refresh Token 设为 7 天
- 使用 Redis 存储黑名单 token，而不是维护白名单

## 下一步
从 Refresh Token 开始，参考 auth.service.ts 第 45 行的 generateToken 函数。
```

把这段内容粘贴到新 session 开头，AI 直接接着做，不需要重新解释背景。

---

### `/to-prd` — 生成需求文档

**适用场景**：需求澄清完了，想把对话内容整理成正式 PRD 并存档。

**用法**：在 `/grill-with-docs` 之后运行：

```
/to-prd
```

Claude Code 会把当前对话的所有需求讨论整理成标准 PRD，并自动提交为 GitHub Issue。

---

### `/to-issues` — 拆分任务

**适用场景**：有了 PRD，需要拆成可独立执行的小任务。

**用法**：

```
/to-issues
```

Claude Code 按"垂直切片"原则拆分，每个 issue 都是端到端可交付的：

```
Issue #1: 实现 POST /auth/login 接口（含单元测试）
Issue #2: 实现 JWT Refresh Token 机制
Issue #3: 实现登录失败锁定逻辑
Issue #4: 接入邮件验证码服务
```

---

### `/improve-codebase-architecture` — 架构健康检查

**适用场景**：项目跑了一段时间，代码越来越乱，定期做一次架构体检。

**用法**：

```
/improve-codebase-architecture
```

Claude Code 读取 `CONTEXT.md` 和 `docs/adr/` 后扫描整个代码库，输出优先级排序的改进建议：

```
[高] UserService 同时处理数据库操作和业务逻辑，建议拆分为
     UserRepository + UserDomainService
[中] 三处重复的日期格式化逻辑，建议提取为 DateFormatter 工具类
[低] TokenBlacklist 命名与 CONTEXT.md 术语不一致，建议统一为 RevokedToken
```

> 💡 建议每隔几天运行一次，防止代码熵增失控。

---

## 推荐工作流

### 日常开发节奏

```
开始新功能
  ↓
/grill-with-docs   需求澄清，更新 CONTEXT.md
  ↓
/to-prd            整理成 PRD，提 Issue 存档
  ↓
/to-issues         拆成独立的小任务
  ↓
/tdd               逐个实现，红绿重构
  ↓
/diagnose          遇到 Bug 时系统排查
  ↓
/handoff           Session 快满时生成交接文档
  ↓
（每隔几天）
/improve-codebase-architecture   架构健康检查
```

### 快速参考

| 场景 | 命令 |
|------|------|
| 开始新功能前 | `/grill-with-docs` |
| 写代码 | `/tdd` |
| 修 Bug | `/diagnose` |
| 看不懂代码 | `/zoom-out` |
| Session 快满 | `/handoff` |
| 生成 PRD | `/to-prd` |
| 拆分任务 | `/to-issues` |
| 定期整理 | `/improve-codebase-architecture` |

---

## 常见问题

**Q：每个项目都要重新安装吗？**

是的，skills 是按项目安装的（写入 `.claude/commands/`）。如果想全局使用，把文件放到 `~/.claude/commands/` 目录下即可对所有项目生效。

**Q：`CONTEXT.md` 需要手动维护吗？**

不需要。每次运行 `/grill-with-docs` 后 AI 会自动更新它。你只需要在初始化时通过 `/setup-matt-pocock-skills` 建立好基础结构。

**Q：Skills 文件可以自定义吗？**

完全可以。`.claude/commands/` 下的 `.md` 文件就是普通文本，直接编辑即可。作者也提供了 `/write-a-skill` 帮你从零创建新的 skill。

**Q：`/grill-with-docs` 和 `/grill-me` 有什么区别？**

`/grill-me` 是纯需求澄清，适合非代码场景。`/grill-with-docs` 在澄清结束后额外做两件事：更新 `CONTEXT.md` 术语表 + 在 `docs/adr/` 记录架构决策，适合所有代码开发场景。

---

> 项目地址：https://github.com/mattpocock/skills
> 当前 Stars：82.1k