· 9 MIN · claude-code · skill

mattpocock/skills 速览：让 Claude Code 真正搞工程

mattpocock/skills 是 TypeScript 圈子里很多人熟悉的 Matt Pocock 维护的一组 Claude Code skills。仓库 README 第一句话表达得很直白：“Skills For Real Engineers” —— 这些 skills 不是用来 vibe coding 玩玩的，是真的拿来做工程的。本文是它的速览，帮你判断要不要装、装哪几个、什么场景下用哪个。

先回顾一下：什么是 Claude Code Skill

Skill 是 Claude Code（以及 Codex 等 agent 工具）的一种可复用指令包。每个 skill 是一个目录，根下放 SKILL.md：

---
name: tdd
description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD...
---

# Test-Driven Development

## Philosophy
...

description 是给 Claude 自己看的”什么时候触发我”的提示；正文是被触发后要遵循的方法论。

调用方式有两种：

  • 用户主动调：聊天里输入 /tdd，Claude 加载 SKILL.md 并按它执行
  • Claude 自动判断：用户描述的场景命中 description 里写的触发条件，Claude 主动加载

跟 CLAUDE.md 的区别：CLAUDE.md 是项目级常驻上下文（每次会话都加载）；skill 是按需加载（只在被触发的那次会话里生效）。所以 skills 适合做”流程性方法论”，CLAUDE.md 适合做”项目级偏好”。

它要解决的四个失败模式

Matt 在 README 里列了 AI 编码常见的四种翻车场景，每种对应一组 skills。这是理解整个仓库设计的最快路径：

失败模式现象对应 skills
对不齐AI 听完做出来不是你想要的/grill-me、/grill-with-docs
太啰嗦AI 用 20 个词说本来 1 个词能讲的事/grill-with-docs（建 CONTEXT.md 共享词汇）
代码不跑对齐了，但 AI 写出来的还是不能用/tdd、/diagnose
滚成泥球AI 提速 → 复杂度也以更快速度积累/to-prd、/zoom-out、/improve-codebase-architecture

值得展开的是”太啰嗦”那一条。Matt 给的对比例子：

  • 没有共享词汇：“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)”
  • 有共享词汇：“There’s a problem with the materialization cascade”

第二种说法之所以能成立，是因为 CONTEXT.md 里早就定义了 “materialization cascade” 这个概念。这种压缩在每次会话里都会复利累积 —— 节省 token、降低误解、文件命名也跟着统一。

30 秒安装

npx skills@latest add mattpocock/skills

跑完会让你选要装哪些 skills、装到哪个 agent（Claude Code / Codex / 其它）。一定要选上 /setup-matt-pocock-skills —— 装完后必须在 agent 里执行一次：

/setup-matt-pocock-skills

这一步会问你：

  • 用哪个 issue tracker（GitHub Issues / Linear / 本地文件）
  • triage 时用哪些标签
  • 文档（CONTEXT.md / ADR）放哪里

不跑这一步，/to-prd、/to-issues、/triage、/diagnose、/tdd、/improve-codebase-architecture、/zoom-out 都没法正常工作 —— 它们都依赖这个初始化产物。

核心 skills 分类速览

仓库目录分三类：engineering/（工程类，日常写代码用）、productivity/（通用流程类）、misc/（不常用）。下面按重要程度排，每个加一句”什么时候用”。

Engineering — 编码核心

/grill-with-docs —— Matt 自己说是”这个仓库里可能最酷的一个”。在动手前对你拷问，把决策树一支支走完；同时把对话里浮现的领域语言写进 CONTEXT.md，把关键架构决策写成 ADR。每次开始改大功能前先跑它。

/to-prd —— grill-with-docs 跑完后，把当前会话浓缩成一份 PRD 直接提到 issue 跟踪器。不会再追问，纯粹基于你刚才聊过的东西。

/to-issues —— 把一份计划/PRD 拆成可独立认领的 issue，用”垂直切片”（tracer-bullet 风格）划分。PRD 出来后做拆分时跑它。

/tdd —— 红绿重构循环。强调一个核心观点：不要先写完所有测试再写实现。这是”水平切片”，会写出 crap tests。要”垂直切片”：一个测试 → 实现 → 重复。每个测试都基于上一次循环学到的东西。做有验收标准的功能时跑它。

/diagnose —— 一个 disciplined 的 bug 排查循环：复现 → 最小化 → 假设 → 加探针 → 修 → 回归。Phase 1 把”建立 fast deterministic 反馈环”写得非常重 —— 没有可重复的失败信号，看再多代码也没用。遇到难复现的 bug 或性能回归时跑它。

/improve-codebase-architecture —— 在 CONTEXT.md 和 ADR 提供的语境下，找出”该深化/合并/解耦”的机会。Matt 建议每隔几天对整个 codebase 跑一次，主动管理软件熵。

/triage —— 用一个由角色驱动的状态机处理 issue。新 issue 进来或者要清空积压时用。

/zoom-out —— 让 agent 跳出当前函数，给一个更高层视角解释这段代码。面对不熟悉的代码区域时用。

/prototype —— 做一次性的原型来探索设计。两条分支：要么是一个可跑的命令行 demo（验业务逻辑/状态机），要么是几个不同视觉风格的 UI 变体（一个路由可切换）。正式投入前想”先玩一下”用。

/setup-matt-pocock-skills —— 上面提到的一次性初始化。每个 repo 跑一次。

Productivity — 通用流程

/grill-me —— grill-with-docs 的”无代码版”。同样是拷问式追问，但不更新文档。非代码场景（写作、设计、产品决策）用这个。

/handoff —— 把当前会话压缩成一份交接文档，给另一个 agent 接力用。长会话快塞满上下文窗口、或者要换个模型继续时用。

/write-a-skill —— 帮你写一个新的 skill，遵循”渐进披露 + 资源捆绑”的结构。你自己想写 skill 时用。

/caveman —— 超压缩通信模式。砍掉冠词、虚词等填充词，号称能省 75% token。技术信息完整保留。

Misc — 不常用但能救急

  • /git-guardrails-claude-code —— 给 Claude Code 装上 hooks，拦截 git push --force、git reset --hard、git clean 这类危险命令。Claude 第一次不小心 force push 完之后建议立刻装。
  • /setup-pre-commit —— Husky + lint-staged + Prettier + 类型检查 + 测试，一条龙。
  • /scaffold-exercises —— 创建练习题目录结构，TypeScript 教程作者向。
  • /migrate-to-shoehorn —— 测试文件里 as 类型断言迁移到 @total-typescript/shoehorn，Total TypeScript 学员向。

推荐工作流：从想法到上线

把这些 skills 按典型开发顺序串起来，大概是这样：

flowchart LR
    A[模糊的想法] -->|/grill-with-docs| B[对齐 + CONTEXT.md + ADR]
    B -->|/to-prd| C[PRD]
    C -->|/to-issues| D[一组独立 issues]
    D -->|/tdd| E[一片片实现]
    E -->|/diagnose| F[卡壳时排查]
    F --> E
    E -->|每几天 /improve-codebase-architecture| G[控制软件熵]
    G --> D

不需要每次都全套走完。最小可用是：

  • 快速试个想法 → /prototype 直接来
  • 要做正式功能 → /grill-with-docs → /tdd
  • 大项目阶段性整理 → /improve-codebase-architecture + /zoom-out

几个实战注意点

1. 默认英文输出：仓库里所有 SKILL.md 都是英文的，触发后 Claude 会沿着语言惯性继续用英文回复。如果你想用中文，在 ~/.claude/CLAUDE.md 或项目级 ./CLAUDE.md 里加一段语言偏好声明就行。具体写法见 让英文 Claude Skill 输出中文。

2. caveman 跟中文输出冲突：caveman 的核心是用压缩英文降低 token —— 跟”始终中文”是反目标。要么二选一，要么用 caveman 时单独覆盖语言偏好。

3. /setup-matt-pocock-skills 是硬前置：跳过会让大部分 engineering skills 没有 issue tracker、没有 CONTEXT.md 路径、没有 triage label 字典可用，行为退化或直接报错。安装后立刻跑一遍。

4. 跟 IDE 自带的 review/security-review 不冲突：Claude Code 自带的 /review 和 /security-review 是另一套，Matt 的 skills 跟它们正交，可以并存。

5. 没有 CLI 限定：Matt 强调 skills “work with any model” —— Claude Code 主用、Codex / Cursor 也能加载。所以即便你不用 Claude Code，这些 skills 也有参考价值。

关于”渐进披露”

仔细看 /tdd 的目录会发现：SKILL.md 自己只有几百行核心方法论，引用了 tests.md 和 mocking.md 两个补充文档。这是 Matt 在 write-a-skill 里强调的”progressive disclosure”模式：

  • SKILL.md 只放核心、必须的指令
  • 详细的 do/don’t 例子、边界情况放在同目录的辅助 .md
  • agent 真的需要时才去读辅助文档

好处：触发时只装载主文件，不浪费上下文窗口；用户也好维护，主结构稳定，例子可以单独迭代。

自己写 skill 时学这个结构。

我现在的用法

我（这个博客的作者）正在试用的几个：

  • /grill-me：在 brainstorming 阶段用得最多，效果显著
  • /diagnose：排查难复现 bug 时强迫自己走流程，避免”凭直觉乱试”
  • /improve-codebase-architecture：每周对本博客代码跑一次，找出可以合并/解耦的地方

如果你才刚开始用 Claude Code 或类似 agent，建议从这三个进入。等熟悉了再补 /tdd 和 /to-prd 这套更”流程化”的 skills。