<!-- title: 72万安装tdd：工程套件拆解 -->

# 72万安装的tdd：拆解Matt Pocock工程Skill套件的系统设计

## 概述

当大多数开发者还在写「一个 SKILL.md 解决一个问题」时，TypeScript 社区最有影响力的教育者 Matt Pocock（Total TypeScript 作者）已经把 Skill 做成了**套件**。他的 `mattpocock/skills` 仓库在 skills.sh 全站排行榜上霸榜：`tdd` 以 72.2 万安装排第 6，`grill-with-docs`（77.5 万）第 4，`improve-codebase-architecture`（74.7 万）第 5，`handoff`、`triage`、`prototype` 全部进入前 12。本期不重复拆已经写过的 `grill-me`，而是把镜头对准它的工程侧：`tdd`、`diagnosing-bugs`、`code-review`、`codebase-design` 这组「真实工程」Skill。通过 GitHub API 拉取的完整文件树可以看到，这套 Skill 的价值不在单个文件，而在三层系统设计——**双层调用架构、瘦封装厚原语、附属文件懒加载**。看完本文，你会明白为什么「套件化」正在成为 Skill 设计的下一个分水岭。

## 评测对比表

| Skill | 功能完整度(25%) | 设计质量(25%) | 实战效果(20%) | 上手难度(15%) | 社区活跃度(15%) | 综合 |
|-------|------|------|------|------|------|------|
| tdd | ★★★★☆ | ★★★★★ | ★★★★☆ | ★★★★☆ | ★★★★★ | **4.5** |
| diagnosing-bugs | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★☆☆ | ★★★★☆ | **4.2** |
| code-review | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★☆☆ | ★★★★☆ | **4.1** |
| improve-codebase-architecture | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★☆☆ | ★★★★☆ | **4.1** |
| codebase-design | ★★★☆☆ | ★★★★☆ | ★★★☆☆ | ★★★☆☆ | ★★★★☆ | **3.6** |
| domain-modeling | ★★★☆☆ | ★★★★☆ | ★★★☆☆ | ★★★☆☆ | ★★★★☆ | **3.5** |
| vercel-react-best-practices（对照组） | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★★★ | ★★★★☆ | **4.3** |

评分说明：安装数据取自 skills.sh 全站排行榜（2026-08-28 实时抓取）；`vercel-react-best-practices` 作为「规则库」范式的对照组纳入，与 Pocock 的「流程纪律」范式形成对比。

## 一、先看全局：一个仓库，四种失败模式

`mattpocock/skills` 的 README 开宗明义：这套 Skill 不是功能集合，而是对 coding agent 四种典型失败模式的逐一回应。这个「问题驱动」的组织方式本身就值得抄：

| 失败模式 | 出处 | 对应 Skill |
|---------|------|-----------|
| #1 Agent 没做我想要的 | 《程序员修炼之道》「没人确切知道自己要什么」 | grill-me / grill-with-docs |
| #2 Agent 太啰嗦 | Eric Evans《领域驱动设计》共同语言 | domain-modeling / CONTEXT.md |
| #3 代码跑不起来 | 《程序员修炼之道》「反馈速率是你的速度上限」 | tdd / diagnosing-bugs |
| #4 我们造了一团泥球 | Kent Beck「每天投资系统设计」 | codebase-design / improve-codebase-architecture |

每条失败模式都引用一本经典工程书籍作理论背书——这是 Skill 写作的高级技巧：**用公认权威降低用户对新流程的信任成本**。

从 GitHub API 拉取的文件树看，仓库把 Skill 分为四个目录：`skills/engineering`（18 个，日常代码工作）、`skills/productivity`（7 个，通用工作流）、`skills/misc`（4 个）、`skills/in-progress`（6 个，孵化中）。仓库根目录还有一份 44KB 的 CHANGELOG.md，说明迭代频率相当高。

## 二、套件架构的核心：双层调用模型

这是整个仓库最值得学的设计。README 的 Reference 一节明确写道，所有 Skill 按一个轴切分——**谁能调用它**：

```mermaid
flowchart TD
    subgraph UserInvoked["用户调用层（编排件）"]
        IMPL["/implement<br/>按票据实现，在约定接缝驱动tdd"]
        ICA["/improve-codebase-architecture<br/>扫描深化机会→HTML报告→追问"]
        GWD["/grill-with-docs<br/>拷问+共建领域模型"]
        TRI["/triage<br/>issue分流状态机"]
    end
    subgraph ModelInvoked["模型调用层（纪律件）"]
        TDD["tdd<br/>红-绿-重构循环"]
        CR["code-review<br/>双轴审查"]
        DB["diagnosing-bugs<br/>诊断循环"]
        CBD["codebase-design<br/>深模块设计规范"]
        DM["domain-modeling<br/>术语与ADR维护"]
        GR["grilling<br/> Interview原语"]
    end
    IMPL -->|"在预定接缝调用"| TDD
    IMPL -->|"提交前收尾"| CR
    ICA -->|"选中候选项后追问"| GR
    GWD --> GR
    TRI --> GR
    TDD -.-> CBD
    GWD -.-> DM
```

规则有三条：**用户调用件（user-invoked）只能通过手动输入触发**，职责是编排；**模型调用件（model-invoked）既可手动触发，也会被 agent 在任务匹配时自动调用**，承载可复用的纪律；用户调用件可以调用模型调用件，反之不行。翻译成软件工程语言：这是一套禁止向上依赖的分层架构，把「流程控制」和「领域纪律」解耦了。

这个设计的直接收益是组合自由度：你可以单独用 `/tdd` 改一个 bug，也可以让 `/implement` 在多票据开发中自动在「预定接缝」插入 tdd 循环、收尾时自动跑 code-review——同一个纪律件，两种消费方式。

## 三、tdd 逐文件拆解：3.5KB 主文件如何撬动一套方法论

`skills/engineering/tdd/` 目录下只有四个文件（字节数来自 GitHub Git Trees API 实测）：

```
skills/engineering/tdd/
├── SKILL.md          3,568 字节   ← 主文件，红-绿-重构循环
├── mocking.md        1,481 字节   ← 何时 mock、何时不 mock
├── tests.md          2,214 字节   ← 好测试/坏测试的判据
└── agents/openai.yaml   87 字节   ← 跨 agent 适配声明
```

**第一处设计：主文件刻意保持小。** 3.5KB 大约是 800 token 出头，加载成本可以忽略。对比仓库里的其他 Skill：`wayfinder` 的 SKILL.md 有 11.9KB，`ask-matt` 有 11.5KB——编排件需要完整流程图所以大，纪律件只写核心循环所以小。文件大小本身就编码了架构意图。

**第二处设计：附属文件懒加载。** `tests.md` 和 `mocking.md` 不会在 Skill 触发时就进入上下文，而是 SKILL.md 在循环推进到「写测试断言」或「遇到依赖需要隔离」的对应步骤时才指引 agent 去读。这正是 Agent Skills 规范设计的渐进式披露（progressive disclosure）能力——Pocock 把它用成了「按需加载的方法论章节」。同样的模式出现在 `codebase-design`（附 `DEEPENING.md`、`DESIGN-IT-TWICE.md`，均取自 Ousterhout《软件设计哲学》的概念）和 `domain-modeling`（附 `ADR-FORMAT.md`、`CONTEXT-FORMAT.md`）。

**第三处设计：不绑定测试框架。** SKILL.md 的循环描述是框架无关的——红（先写失败测试）、绿（最小实现让其通过）、重构（在测试保护下整理）。具体跑什么命令由仓库自身的测试设施决定，Skill 只负责「流程纪律」。这让它可以零配置插入任何项目，也是 72 万安装的重要前提：**通用纪律 + 项目自带的反馈环，而非自建脚手架**。

**第四处设计：跨 agent 适配文件。** 每个 Skill 目录里都有一个约 100 字节的 `agents/openai.yaml`。这个细节说明作者从一开始就按「多 agent 通用」设计，而不是 Claude Code 专属——配合 skills.sh 的安装器（支持 Claude Code、Cursor、Codex、Copilot、Windsurf 等 21 个 agent），同一个 Skill 文件可以在不同宿主间迁移。

## 四、双轴 code-review：用子 agent 隔离防止「审查视角污染」

`skills/engineering/code-review/SKILL.md`（6,634 字节）的设计点是**把一次审查拆成两个互不污染的并行子 agent**：

- **Standards 轴**：这次 diff 是否符合仓库的编码规范 + Martin Fowler 的坏味道基线？
- **Spec 轴**：这次 diff 是否忠实实现了发起它的 issue/spec？

为什么要拆？单 agent 同时戴两顶帽子时，规范类意见会淹没需求类意见（或反之），而两个并行子 agent 各自只看一个轴，结论再合并。这是把「关注点分离」直接做进了 Skill 的执行拓扑里——**不是写在提示词里的软约束，而是结构上的硬隔离**。

与之配套的是 `diagnosing-bugs`（SKILL.md 8,969 字节）：把调试封装成带门禁的阶段循环——**构建一个能在此 bug 上变红的反馈环 → 最小化复现 → 提出假设 → 插桩验证 → 修复 → 回归测试**。它是 `skills/engineering/` 下少数带脚本的 Skill：`scripts/hitl-loop.template.sh`（1,319 字节）提供了一个 human-in-the-loop 循环模板，把「每阶段暂停等人确认」做成了可执行文件而非纯提示词。

## 五、对照组：Vercel 的规则库范式

把 `vercel-labs/agent-skills`（64.7 万安装的 `vercel-react-best-practices` 所在仓库）放进来对比，能看到 Skill 设计的两种范式：

| 维度 | Pocock 流程纪律范式 | Vercel 规则库范式 |
|------|------------------|-----------------|
| 内容形态 | 循环、阶段、门禁 | 40+ 条规则，8 个分类，按影响优先级 |
| 知识来源 | 经典工程书籍 + 个人实践 | Vercel 工程部内部评审标准 |
| 生效方式 | 改变 agent 的工作节奏 | 改变 agent 写代码时的检查清单 |
| 代表触发 | 「实现这个功能」→ 进入红绿循环 | 「审查这个组件」→ 逐条比对规则 |
| 可裁剪性 | 高（纪律可部分采纳） | 中（规则可挑选但彼此独立） |

Vercel 仓库的 `web-design-guidelines` 走得更极端：100+ 条规则覆盖可访问性、表单、动画、排版等 11 类，本质是一份机器可执行的评审手册。两种范式没有高下——**流程纪律适合「怎么工作」，规则库适合「什么是好」**，成熟的个人配置往往是两者混装。

## 六、安装与使用

```bash
# 方式一：Claude Code 官方插件市场（托管式，自动更新）
claude plugins install mattpocock-skills
# 或会话内：/plugin install mattpocock-skills

# 方式二：skills.sh 安装器（文件落盘式，可自行魔改）
npx skills@latest add mattpocock/skills
# 安装时记得勾选 setup-matt-pocock-skills

# 只要 tdd 单件：
npx skills add mattpocock/tdd

# 安装后每仓库跑一次配置（选 issue 跟踪器：GitHub/Linear/本地文件）
/setup-matt-pocock-skills
```

README 特别提醒：两种方式**二选一**，都装会得到两份重复 Skill。托管式适合「订阅」，落盘式适合「fork 后改造」——这个双通道发布策略本身也值得国内 Skill 作者参考。

## 七、推荐排行榜

- **最适合第一个安装**：`tdd` — 框架无关、零配置、立刻改变 agent 产出质量
- **最值得学习的设计**：`code-review` — 子 agent 双轴隔离，Skill 执行拓扑设计的教科书
- **最适合老项目**：`improve-codebase-architecture` — 输出可视化 HTML 报告再逐项追问，定位是「普查而非抢救」
- **最适合团队**：`grill-with-docs` — 顺手把 CONTEXT.md 和 ADR 沉淀下来，属 Pocock 自评「整个仓库最酷的技术」
- **最被低估**：`handoff`（62.8 万安装）— 会话压缩成交接文档，多 session 长任务的刚需件

## 八、能直接抄走的三个写法

1. **瘦封装厚原语**：`grill-me` 的 SKILL.md 只有 147 字节、`grill-with-docs` 245 字节——它们只是指向 1.9KB 的 `grilling` 原语的指针。同一个 Interview 引擎被 grill-me、grill-with-docs、triage、wayfinder、improve-codebase-architecture 五个入口复用。写 Skill 先问：这个逻辑是否该下沉为一个可复用原语？
2. **按字节预算分层**：主文件控制在 3-7KB，把展开的判据、格式规范放进附属 md 按需加载。上下文窗口是稀缺资源，Skill 的加载成本就是它的运行时价格。
3. **声明调用层级**：在 README/SKILL.md 里显式写「谁可以调用谁」。大多数 Skill 生态的混乱来自所有 Skill 平权互调，一个单向依赖声明就能让套件可维护。

## 参考来源

1. [skills.sh — The Agent Skills Directory](https://skills.sh) — 全站排行榜安装数据（tdd 722.0K、grill-me 911.2K 等），2026-08-28 抓取
2. [mattpocock/skills — GitHub](https://github.com/mattpocock/skills) — 套件 README、四大失败模式、双层调用模型说明
3. [mattpocock/skills Git Trees API](https://api.github.com/repos/mattpocock/skills/git/trees/main?recursive=1) — 全部 Skill 文件结构与字节数实测
4. [vercel-labs/agent-skills — GitHub](https://github.com/vercel-labs/agent-skills) — react-best-practices（40+ 规则）与 web-design-guidelines（100+ 规则）规则库范式
5. [SkillsMP — Agent Skills Marketplace](https://skillsmp.com) — 生态规模数据：2,806,826 个 SKILL.md、247,452 位创作者，Testing 类 87,298 个

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)