Matt Pocock的skills介绍

关于本笔记

本笔记用于沉淀 mattpocock/skills 的使用方法与适用场景，目标是把它当作一套可执行的工作流，而不是只记命令。

仓库地址：https://github.com/mattpocock/skills

目录

项目简介

mattpocock/skills 是一组面向 AI 编程助手的工程技能集合，强调：

  • 用结构化流程降低“需求理解偏差”
  • 用反馈回路（TDD、诊断、分诊）提高可交付质量
  • 用可组合的小技能替代一体化大流程

一句话：让 AI 写得快，也写得稳。

项目结构树

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
skills/
├── CLAUDE.md                          # 技能目录规范说明
├── README.md                          # 总览与使用文档
├── skills/
│   ├── engineering/
│   │   ├── diagnose/
│   │   │   └── SKILL.md               # 结构化调试流程
│   │   ├── grill-with-docs/
│   │   │   └── SKILL.md               # 附文档的深度访谈
│   │   ├── improve-codebase-architecture/
│   │   │   └── SKILL.md               # 架构改进诊断
│   │   ├── setup-matt-pocock-skills/
│   │   │   └── SKILL.md               # 初始化配置入口
│   │   ├── tdd/
│   │   │   ├── SKILL.md               # TDD 垂直切片工作流
│   │   │   ├── tests.md               # 好 / 坏测试示例
│   │   │   ├── mocking.md             # Mock 最佳实践
│   │   │   ├── refactoring.md         # 重构时机判断
│   │   │   ├── deep-modules.md        # 深模块设计原则
│   │   │   └── interface-design.md    # 可测试接口设计
│   │   ├── to-issues/
│   │   │   └── SKILL.md               # 需求拆分到 GitHub Issues
│   │   ├── to-prd/
│   │   │   └── SKILL.md               # PRD 生成
│   │   ├── triage/
│   │   │   └── SKILL.md               # Issue 分诊状态机
│   │   └── zoom-out/
│   │       └── SKILL.md               # 代码全局视角解读
│   ├── productivity/
│   │   ├── caveman/
│   │   │   └── SKILL.md               # 压缩通信模式，省 75% token
│   │   ├── grill-me/
│   │   │   └── SKILL.md               # 需求深度访谈
│   │   └── write-a-skill/
│   │       └── SKILL.md               # 自定义技能编写指南
│   └── misc/
│       ├── git-guardrails-claude-code/
│       │   └── SKILL.md               # Git 安全护栏
│       └── scaffold-exercises/
│           └── SKILL.md               # 练习目录脚手架
└── .claude-plugin/
    └── plugin.json                    # 插件元数据

engineering/（日常代码工作）

适用：写功能、修 bug、拆需求、架构治理、代码理解

常用技能：

1
2
3
4
5
6
7
8
9
/setup-matt-pocock-skills：每仓库首次初始化（必做）
/tdd：红绿重构，适合新增功能/修复问题
/diagnose：复杂 bug/性能回归排查
/to-prd：把当前讨论整理成 PRD
/to-issues：把 PRD/计划拆成可执行 issue
/triage：issue 分流与状态管理
/zoom-out：从系统层面理解局部代码
/improve-codebase-architecture：定期去“泥球化”
/grill-with-docs：需求盘问 + 术语与 ADR/CONTEXT 对齐

productivity/（非代码流程工具）

适用：思路澄清、沟通提效、知识沉淀

常用技能：

1
2
3
/grill-me：纯方案盘问，快速澄清需求
/caveman：极简输出，减少冗余
/write-a-skill：把团队经验沉淀为 skill

misc/（低频工具）

适用：一次性工程基建、迁移、脚手架类任务，不是日常主路径。

示例：

  • git-guardrails-claude-code：Git 危险操作防护
  • setup-pre-commit：快速建立 pre-commit 质量门
  • scaffold-exercises：练习目录脚手架

personal/（个人配置）

适用：作者个人工作流/环境相关内容，不建议直接照搬。

使用原则：

  • 优先借鉴方法，不复制路径与工具细节
  • 若与团队规范冲突，以团队规范为准

in-progress/（草稿区）

适用：实验中的技能草稿。

使用原则：

  • 仅用于学习或试验
  • 上生产前必须补充验证与回滚策略

分类与场景

engineering/：代码实现、修复、架构演进主战场。

productivity/：需求澄清、沟通压缩、流程抽象。

misc/：低频但实用的工程工具箱。

personal/：个性化配置参考，不作为通用标准。

in-progress/：预览/草稿，不承诺稳定。

安装与初始化

安装skills

找到 Codex/Claude Code 的配置目录, 比如 win11 下的 C:\Users\<User>\.codex

运行:

1
npx skills@latest add mattpocock/skills

初始化

使用Codex在项目根目录下执行:

1
/setup-matt-pocock-skills

这个 Skill 会依次问你：

  1. Issue Tracker：选择你用哪个工具管理 Issues（GitHub / Linear / 本地文件）
  2. Triage Labels：给 Issue 打标签时用哪些词汇（/triage 技能会用到）
  3. 文档保存路径：生成的 ADR 和文档放在哪里

注意：/setup-matt-pocock-skills 的核心产物是 docs/agents/ 下的配置文档，以及在 CLAUDE.md/AGENTS.md 中写入 ## Agent skills 说明块。

CONTEXT.md 是否存在，取决于你的仓库本身，不一定由该命令自动创建。

推荐工作流

  1. 需求不清：/grill-with-docs（或 /grill-me）
  2. 实现前：/tdd（小步红绿重构）
  3. 出问题：/diagnose
  4. 任务管理：/to-prd -> /to-issues -> /triage
  5. 周期治理：/zoom-out + /improve-codebase-architecture

决策速查表

  • “我要做新功能” -> /grill-with-docs + /tdd
  • “线上有难复现 bug” -> /diagnose
  • “需求很多，想拆成可并行任务” -> /to-prd + /to-issues
  • “Issue 太乱” -> /triage
  • “看不懂这段代码在系统中的位置” -> /zoom-out
  • “代码库越来越乱” -> /improve-codebase-architecture
  • “我只要最短输出” -> /caveman

配置文件说明（重点）

初始化后建议重点关注这几类文件：

  • CLAUDE.md 或 AGENTS.md
    • 里面的 ## Agent skills 是入口索引
  • docs/agents/issue-tracker.md
    • 规定 issue 来自哪里（GitHub/GitLab/本地/其他）
  • docs/agents/triage-labels.md
    • 规定 triage 的标签词汇映射
  • docs/agents/domain.md
    • 规定 domain docs 布局（single-context 或 multi-context）

常见误区与修正

误区 1：只记住命令，不维护配置文档。

修正：优先维护 docs/agents/*.md，技能行为由这些配置驱动。

误区 2：把 misc 当主流程。

修正：主流程优先 engineering + productivity，misc 低频启用。

误区 3：未澄清需求就直接让 AI 写代码。

修正：先 grill-*，再 tdd/diagnose，返工会显著减少。

误区 4：草稿技能直接上生产。

修正：in-progress 只用于试验，先补验证清单。

我的最小实践模板

可复制到每周工作计划：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
本周目标：

1) 需求对齐
- [ ] 使用 /grill-with-docs 明确边界与验收标准

2) 实现与验证
- [ ] 使用 /tdd 完成至少一个垂直切片
- [ ] 问题项使用 /diagnose 输出复现与根因

3) 任务协作
- [ ] 使用 /to-prd 产出说明
- [ ] 使用 /to-issues 拆分可执行任务
- [ ] 使用 /triage 维护状态

4) 架构健康
- [ ] 使用 /zoom-out 做一次全局理解
- [ ] 使用 /improve-codebase-architecture 记录一项改进