> ## Documentation Index
> Fetch the complete documentation index at: https://adonis-til.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills for Real Engineers：Matt Pocock 的可组合 Agent Skills

> 介绍 Matt Pocock 的 mattpocock/skills——用小而可组合的 skill 对抗 vibe coding 翻车，核心是 grilling 对齐、CONTEXT.md 领域语言与 deep modules，而不是接管整条开发流程。

> 发布于 2026-07-14 · 更新于 2026-07-14

> AI 写代码很快，但常见翻车往往不是模型不够聪明：**需求没对齐、术语各说各话、反馈环缺失、架构熵增失控**。[mattpocock/skills](https://github.com/mattpocock/skills)（Matt Pocock）把这些失败模式拆成一箱小而可改的 skill——目标是 *real engineering*，不是 vibe coding，也不是把流程主权交给某套「全家桶」方法论。

***

## 一、这是什么

仓库自称 **Skills For Real Engineers**：Matt 自己日常在用的 agent skills，直接从他的 agent 配置里长出来。

和 GSD、BMAD、Spec-Kit 一类方案不同——那些通常通过 **接管流程（own the process）** 来帮忙，代价是 **你失去控制权**：流程本身出 bug 时，往往比业务 bug 更难修。

Matt 的设计原则反过来：

| 原则                | 含义                                |
| ----------------- | --------------------------------- |
| **Small**         | 单个 skill 短、职责单一，读得完、改得动           |
| **Easy to adapt** | 鼓励 fork 改，而不是「必须原样用」              |
| **Composable**    | 用户触发的编排 skill + 模型可触发的纪律 skill 拼装 |
| **Any model**     | 不绑定单一模型或单一 harness                |

一句话：**零件箱，不是流水线总成。** 你掌舵，skill 只在关键节点注入工程常识。

***

## 二、四个失败模式，四类解药

README 的主线不是「有哪些文件」，而是 **coding agent 最常翻车的四种方式**。

### 1. Agent 没做你想要的 → Grilling

软件工程最常见的失败是 **misalignment**：你以为对方懂了，交付物出来才发现完全不是一回事。AI 时代只是把这个间隙放大了。

解药是 **grilling session**：逼 agent 对你做审讯式追问，把决策树每一支走完，再动手。

| Skill              | 场景                     |
| ------------------ | ---------------------- |
| `/grill-me`        | 非代码、或还没有代码库时的对齐        |
| `/grill-with-docs` | 有代码库时的对齐；同时维护领域语言与 ADR |

`grill-with-docs` 在实现上几乎是「组合技」：跑 `/grilling`，并挂上 `/domain-modeling`。纪律写得很硬，例如：

* **一次只问一个问题**，等你答完再问下一个
* 每个问题附带 **推荐答案**，降低决策摩擦
* 能查环境（仓库、工具）的事实 **不要问人**；**决策**必须留给你
* 达成 shared understanding 之前 **不行动**

Matt 自己的建议是：每次要改东西，都先 grill 一遍。

### 2. Agent 太啰嗦 / 术语乱 → 共享语言（CONTEXT.md）

Agent 被丢进陌生仓库，只能边猜黑话边写——于是 20 个词才能说清 1 个概念。

解药是 **ubiquitous language**：一份 agent 能解码的项目词典，通常落在 `CONTEXT.md`，难讲的决策进 `docs/adr/`。

Matt 举过自己的例子：长句描述「课程某 section 下的 lesson 被 materialize 到文件系统」 vs 领域词 **materialization cascade**——后者跨会话、跨 agent 都更省 token，也更稳。

共享语言的附带收益：

* 变量 / 函数 / 文件命名更一致
* 代码库对 agent **更可导航**
* agent **少花 token 在绕弯解释**

这是整仓最值得试的一招，往往比再加十条 lint 规则更有杠杆。

### 3. 代码不可靠 → 反馈环（TDD / 诊断）

对齐之后 agent 仍可能写出垃圾——因为没有对「代码是否真的 work」的稳定反馈。

需要的还是老派工程件：静态类型、浏览器可达、自动化测试。技能层则是：

| Skill              | 作用                                          |
| ------------------ | ------------------------------------------- |
| `/tdd`             | red → green 竖切；在 **事先约定的 seam** 上测行为，不测实现细节 |
| `/diagnosing-bugs` | 复现 → 最小化 → 假设 → 埋点 → 修复 → 回归测试              |

`/tdd` 还明确反对「先写完全部测试再实现」的横向切片：一次一个 tracer bullet，让上一轮的反馈塑造下一轮。

### 4. 泥球架构 → 每天投资设计

Agent 加速编码的同时，也在 **加速软件熵增**。多数 vibe 出来的应用难改、难测、难让下一个 agent 读懂。

贯穿全仓的解药是 **在乎模块设计**——尤其是 Ousterhout 意义上的 **deep modules**：小接口后面藏大行为。

| Skill                            | 作用                                                |
| -------------------------------- | ------------------------------------------------- |
| `/codebase-design`               | 统一词汇：Module / Interface / Depth / Seam / Adapter… |
| `/to-spec`                       | 写 spec 前先对齐你要动哪些模块与 seam                          |
| `/improve-codebase-architecture` | 扫 deepening 机会，出 HTML 报告，再对选定项 grill              |

Matt 的节奏建议：每隔几天就对代码库跑一次架构改善扫描——把「设计」从年度重构变成日常卫生。

***

## 三、User-invoked vs Model-invoked

这套 skills 按 **谁可以触发** 切一刀，比按文件夹切更重要：

| 类型                | 谁触发                  | 职责                              |
| ----------------- | -------------------- | ------------------------------- |
| **User-invoked**  | 只有你键入（如 `/grill-me`） | **编排**：定节奏、定产物、定何时停             |
| **Model-invoked** | 你或 agent 在任务匹配时自动够到  | **纪律**：TDD、诊断、领域建模、code review… |

规则：

* user-invoked **可以**调用 model-invoked
* user-invoked **不要**再链式调用另一个 user-invoked（避免编排套编排、失去可控性）

这是可组合性的护栏：零件能拼，但拼装权在人。

***

## 四、日常推荐路径

迷路时先 `/ask-matt`——它是面向「我该用哪个 skill」的路由器。多数功能开发会收敛成下面这条主路径：

```
/setup-matt-pocock-skills     ← 每个仓库一次
        │
        ▼
/grill-with-docs              ← 对齐 + 写 CONTEXT.md / ADR
        │
        ▼
/to-spec  →  /to-tickets      ← 对话沉淀为 spec 与 tracer-bullet 票
        │
        ▼
/implement                    ← 内嵌 /tdd，收尾 /code-review，再 commit
        │
        ▼
周期性 /improve-codebase-architecture
```

几个常用岔路：

| 情况               | 去向                                         |
| ---------------- | ------------------------------------------ |
| 还没有代码库 / 非代码决策   | `/grill-me`                                |
| 会话要换 agent 或窗口   | `/handoff`                                 |
| 问题必须「跑起来才知道」     | `/prototype`（可配合 handoff 跨会话）              |
| 工作大到一窗装不下、路还看不清  | `/wayfinder`（决策地图；默认只规划不瞎冲）                |
| 外部涌入的 bug / 需求堆着 | `/triage`（不要 triage 已经 `/to-tickets` 产好的票） |

实践提示：**grill → spec → tickets 尽量留在同一上下文**；每个 `/implement` 再清上下文按票开工。上下文接近模型「还聪明」的上限时，宁可 handoff，不要硬撑。

***

## 五、安装：两条路径，两种哲学

### 路径 A：skills.sh（可编辑副本）

```bash theme={null}
npx skills@latest add mattpocock/skills
```

安装时勾选你需要的 skill 与目标 agent，**务必包含** `/setup-matt-pocock-skills`。\
适合：想改 skill、多 harness（Claude Code、Codex 等 Agent Skills 标准环境）。

### 路径 B：Claude Code 原生插件（只读订阅）

在 Claude Code 内：

```
/plugin marketplace add mattpocock/skills
/plugin install mattpocock-skills@mattpocock
```

或在 shell：

```bash theme={null}
claude plugin marketplace add mattpocock/skills
claude plugin install mattpocock-skills@mattpocock
```

插件是 **managed bundle**：不拷贝可改文件进仓库，跟着上游版本走。适合：只想用 Matt 的官方集，并随更新演进。

### 每仓库一次 setup

无论哪条安装路径，在具体项目里跑一次：

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

它会问清三件事：

1. Issue tracker：GitHub / Linear / 本地文件
2. Triage 用的 label 词汇（`/triage` 依赖）
3. 文档（如 `CONTEXT.md`、ADR）落在哪里

没有这一步，后面的 `/to-spec`、`/to-tickets`、`/wayfinder` 会缺少「事实源」约定。

***

## 六、Skill 地图（精简）

### Engineering — User-invoked

| Skill                           | 一句话                                   |
| ------------------------------- | ------------------------------------- |
| `ask-matt`                      | 路由：现在该走哪条 flow                        |
| `setup-matt-pocock-skills`      | 每仓配置 tracker / labels / docs          |
| `grill-with-docs`               | 审讯式对齐 + 领域文档                          |
| `to-spec`                       | 把已有对话合成 spec，发布到 tracker（不再面试）        |
| `to-tickets`                    | 拆成带阻塞边的 tracer-bullet 票               |
| `implement`                     | 按 spec/票实现；TDD + code-review + commit |
| `triage`                        | 外来 issue 的状态机分拣                       |
| `improve-codebase-architecture` | 找 deepening 机会并 grill                 |
| `wayfinder`                     | 超大工作的决策地图                             |

### Engineering — Model-invoked

| Skill                       | 一句话                     |
| --------------------------- | ----------------------- |
| `tdd`                       | red-green 竖切与好测试标准      |
| `diagnosing-bugs`           | 硬 bug / 性能回归的诊断环        |
| `domain-modeling`           | 维护 `CONTEXT.md` 与 ADR   |
| `codebase-design`           | deep module 共享词汇与原则     |
| `code-review`               | Standards × Spec 双轴并行审查 |
| `prototype`                 | 用可丢弃原型回答设计问题            |
| `research`                  | 高信任源调研并落盘带引用的 md        |
| `resolving-merge-conflicts` | 按双方意图解冲突，不轻易 abort      |

### Productivity

| Skill                   | 一句话                            |
| ----------------------- | ------------------------------ |
| `grill-me` / `grilling` | 通用审讯环（grilling 为可复用 primitive） |
| `handoff`               | 压缩会话，交给下一个 agent               |
| `teach`                 | 多会话教学工作区                       |
| `writing-great-skills`  | 如何把 skill 写得可预期                |

仓库里还有 `misc/`、`personal/`、`in-progress/`、`deprecated/`——介绍阶段不必全装；先主路径，再按痛点加。

***

## 七、和 Superpowers / agent-skills 怎么选

本站已有两篇近亲文章：

* [Superpowers 全生命周期指南](./superpowers-workflow-guide.md)
* [Addy Osmani 的 agent-skills 实战指南](./agent-skills-guide.md)

三套可以 **并存**，不必二选一：

| 维度   | Superpowers | agent-skills                     | mattpocock/skills                |
| ---- | ----------- | -------------------------------- | -------------------------------- |
| 主隐喻  | 纪律层 + 生命周期  | Google 工程文化 + 线性 `/spec`→`/ship` | 可组合零件；人掌舵                        |
| 流程强度 | 强引导         | 强引导                              | 弱引导（主路径在文档里，不强制接管）               |
| 最值得偷 | 验证闭环、TDD 纪律 | anti-rationalization、persona     | grilling、CONTEXT.md、deep modules |
| 适合心态 | 「给我一条靠谱流水线」 | 「把 senior 判断注入每环」                | 「我要控制权，只要关键节点的好零件」               |

已经装了前两套时，仍值得单独试用的最小集合：

1. `/setup-matt-pocock-skills`
2. `/grill-with-docs`（或 `/grill-me`）
3. 坚持维护一份 `CONTEXT.md`

***

## 八、什么时候值得装

**适合你，如果：**

* 已经用 coding agent 写真实产品，痛的是对齐与熵增，不是「不会生成代码」
* 希望 skill **可读、可改、可删**，而不是黑盒方法论
* 认同「先问清楚再写」和「模块深度」这类老派工程观

**可以先缓缓，如果：**

* 还在纯玩具 / 一次性脚本阶段，流程税高于收益
* 只想要一条强制 `/do-everything` 命令（这套故意不提供）
* 团队没有任何 tracker 或文档约定，又不想跑 setup

**最小承诺**：装上 → setup → 下一个真实改动先 `/grill-with-docs` 再写代码。一周后再决定是否引入 tickets / implement 全链路。

***

## 九、结尾

软件工程基本功没有过时——agent 只是把「跳过基本功」的代价放大、并把「熵增速度」乘上了一个系数。Matt 的 skills 把 Pragmatic Programmer、DDD、XP、Philosophy of Software Design 里 provable 的那部分，压成可重复执行的小步骤。

* 仓库：[github.com/mattpocock/skills](https://github.com/mattpocock/skills)
* 安装入口：[skills.sh/mattpocock/skills](https://skills.sh/mattpocock/skills)
* 本站素材底座：`raw/mattpocock-skills.md`

先 grill，再写代码。零件在手，流程仍是你的。