22 skills, one philosophy:
wrangle determinism out of a
stochastic system.

我大概一周前开始认真看 mattpocock/skills。200k stars，被 Claude Code 官方 marketplace 收录，MIT 许可——但真正打动我的是他 AI Hero 主页 上那句 "Skills For Real Engineers"。

一个 skill 不是"我让 agent 做某件事"的文件。一个 skill 是 从随机系统里挤出确定性 的工程化产物。

这一篇不是教程，也不是翻译。我想做的是：把 22 个 skill 按"它解决什么失败模式"重新组织起来，让你读完知道：

1. 他为什么写这 22 个 skill（不是 50 个、不是 10 个）
2. 每一类 skill 的核心机制
3. 怎么用他的思路写自己工作流里的 skill

这一篇本身有 6500 字左右。如果你赶时间，章节里都有"心智模型"小标题，可以跳着读。最后有一份完整索引。

第 1 节：核心哲学

Matt 在 writing-great-skills/SKILL.md 里把整篇的根写得很清楚：

"A skill exists to wrangle determinism out of a stochastic system."

—— Predictability: agent 每次跑同样的 process，不是同样的 output。

翻译过来就是：

• AI 是随机的（每次输出可能不同）
• Skill 的核心价值 = 让 AI 每次按同样流程做事
• 不要追求"输出完全一样"——追求 过程稳定

这跟 superpowers（obra/superpowers，259K stars）的"TDD Iron Law"路线不同。superpowers 把工程纪律（Test-Driven / Red-Green-Refactor）做成核心约束；Matt 的路线是把"沟通纪律"做成核心约束。他观察到的 4 个失败模式，每一个的根都在"沟通不对齐"：

这 4 个失败模式对应 4 类 skill——也是 Matt 自己组织的逻辑：

1. 对齐（grill）：先想清楚再做
2. 语言（domain-modeling）：让 agent 和你用同一套词
3. 反馈（tdd / bugs）：让 agent 看得到自己的错
4. 设计（codebase）：保持代码库结构稳定

第 2 节：第一个核心机制——User-invoked vs Model-invoked

这是 Matt 整个 repo 最值钱的设计决策之一，也是他写 skill 写得比绝大多数人好的根本原因。

两者的 frontmatter 差异

---
name: grill-me
description: A relentless interview to sharpen a plan or design.
disable-model-invocation: true
---
Run a `/grilling` session.

---
name: tdd
description: Test-driven development. Use when writing new
  features or fixing bugs — strict red-green-refactor loop.
---

TDD is the red → green loop...

注意 disable-model-invocation: true 这个字段。打开它之后：

• User-invoked skill 的 description 不进 context。只有当用户敲 /grill-me 时，skill body 才被加载。
• Model-invoked skill 的 description 每轮都进 context。agent 看到描述，根据匹配度决定要不要加载 body。

为什么要分两类？

Token 经济学。

• User-invoked skill 的触发是 用户的嘴（敲 /xxx）。所以 description 写得再烂没关系——用户已经知道要调它了。
• Model-invoked skill 的触发是 模型的判断。每轮 token 都为它付钱。Description 必须写成一个 精准的 trigger phrase，多一个字都是浪费。

选择标准

第 3 节：22 个 skill 完整分类

下面是我重新组织的版本——按"它解决哪一类失败模式"分类，不是按文件夹分类。

Engineering 18 个

🟦 User-invoked（9 个——你显式调用）

🟩 Model-invoked（9 个——agent 自动用）

Productivity 5 个

🟦 User-invoked（4 个）

🟩 Model-invoked（1 个）

第 4 节：第二个核心机制——leading words

这是 Matt 写 skill 跟别人拉开差距的第二个关键点：

A leading word is a compact concept already living in the model's pretraining.

翻译：leading word = 模型已经会的概念 + 你反复用 = 行为稳定。

3 个真实例子

为什么 leading word 工作

• 少 token。"relentless interview" 比 "keep asking until satisfied" 少一半字符。
• 更准确。模型对 pretrained 概念反应比临时造的短语更稳定。
• 前后一致。description / body / docs 用同词，agent 不会困惑。

Matt 整个 repo 的 leading words 我列了一下：relentless, red, green, vertical, tracer-bullet, deep, seam, grill, fact, decision, scope, ship, blocking, frontier, depth, leverage, locality。注意他不是 造词——他是从软件工程几十年的共同语汇里挑出来的。

第 5 节：5 个标志性 SKILL.md 拆解

这一节把 22 个 skill 里的 极简派和长篇派 摆在一起，让你看到他的文风跨度。

1. grill-me（5 行）—— 极简派

---
name: grill-me
description: A relentless interview to sharpen a plan or design.
disable-model-invocation: true
---
Run a `/grilling` session.

特点：

• 5 行完事
• 一句话指到 grilling，复用 不是重复
• disable-model-invocation: true——不占 context
• 没有任何 step——它 就是 路由

2. grilling（10 行）—— 执行核心

Interview me relentlessly about every aspect of this until
we reach a shared understanding.

Walk down each branch of the decision tree, resolving
dependencies between decisions one-by-one.

For each question, provide your recommended answer.

Ask the questions one at a time, waiting for feedback
on each question before continuing.
Asking multiple questions at once is bewildering.

If a *fact* can be found by exploring the environment
(filesystem, tools, etc.), look it up rather than asking me.
The *decisions*, though, are mine — put each one to me
and wait for my answer.

Do not act on it until I confirm we have reached a
shared understanding.

5 原则：

1. Relentless——别客气
2. Decision tree——一次走一条分支
3. One at a time——一次一个问题，多个 = bewildering
4. Fact vs Decision——事实自己查，决策交给你
5. No premature action——不确认不行动

Fact vs Decision 是 Matt 的核心洞察。大多数人（包括我）会问"用户的预算范围是多少？"，但其实"用户的预算"是 fact（可以从行业数据查），"预算 够不够买" 才是 decision（必须用户回答）。把这两类混在一起问，agent 问出来的就是噪音。

3. handoff（11 行）—— 极简派 + 引用原则

---
name: handoff
description: Compact the current conversation into a handoff
  document for another agent to pick up.
argument-hint: "What will the next session be used for?"
disable-model-invocation: true
---
Write a handoff document summarising the current conversation
so a fresh agent can continue the work. Save to the temporary
directory of the user's OS - not the current workspace.

Include a "suggested skills" section in the document, which
suggests skills that the agent should invoke.

Do not duplicate content already captured in other artifacts
(specs, plans, ADRs, issues, commits, diffs). Reference them
by path or URL instead.

Redact any sensitive information...

注意最后那行："Do not duplicate content already captured in other artifacts. Reference them by path or URL instead." 这是 单一来源真相 原则的直接体现。如果 handoff 文档里复制了 spec 的内容，spec 改了 handoff 不会改——重复就是债务。

4. teach（100+ 行）—— 详细派

跟 grill-me 5 行完全相反。原因是它要做的事完全不同——多会话教学，需要完整的 workspace 设计：

• 文件结构：MISSION.md · RESOURCES.md · learning-records/ · lessons/ · assets/
• 哲学：Knowledge / Skills / Wisdom 三分
• 心理学：提醒"fluency vs storage strength"（流利度 vs 存储强度）
• 状态化：NOTES.md 记录用户偏好

grill-me vs teach 的对比 就是 Matt 写 skill 的两个极端：

5. writing-great-skills（200+ 行）—— meta skill

整篇就是"如何写 skill 的 skill"。

• 有 GLOSSARY.md——所有 bold 词 在那定义
• 是 reference——全程无 step
• 教 原则——不教具体做法

它本身就是 它教的东西的样板：用 leading words、用 GLOSSARY、用 information hierarchy。

第 6 节：第三、第四个核心机制——Information Hierarchy & No-op 检测

Information Hierarchy（信息层级）

Matt 把信息分成 3 层：

1. In-skill step（步骤）——主要 SKILL.md
2. In-skill reference（参考）——也放 SKILL.md
3. External reference（外部）——单独 .md 文件

怎么用：

核心原则：

• 完成准则可检查——"每条规则都应用了"，不是"给个清单"
• 过度模糊 → premature completion（agent 跳到"做完了"）
• 过度分裂 → 隐藏 agent 真正需要的信息

5 个失败模式

No-op 检测（核心实操）

拿掉这一句，行为变了吗？没变 = no-op，删，不是改写。

这一条是 Matt 的"减肥"工具。SKILL.md 写到 50 行的时候回头看一遍，每一行问自己：拿掉它，agent 行为会变吗？答案如果是否，删。重复这个过程直到每一行都 有作用。

Negation（额外陷阱）

用禁止来引导 = 反效果（"不要想大象"会让你想大象）。

说 正向行为——"做 X"，而不是"不要做 Y"。grilling 里说"Ask the questions one at a time"，不说"Don't ask multiple questions at once"。这是同一个反 no-op 工具的延伸。

第 7 节：两条工作流——Plan-then-Build & Domain-Driven

22 个 skill 拼起来支持 2 个核心工作流：

工作流 1：Plan-then-Build（计划 + 实施）

grill-me / grill-with-docs
        ↓
     to-spec         ← 把对话合成 spec，发布到 issue tracker
        ↓
     to-tickets      ← 拆成 vertical slice，标 blocker
        ↓
     implement       ← 在预约定 seam 触发 /tdd，提交前 /code-review
        ↓
     code-review     ← Standards + Spec 双轴

关键点：每一步之间都显式停下来，不连跑。你跑完 to-spec 之后确认 spec 写得对，才开始 to-tickets。这跟 superpowers 的 "writing-plans → executing-plans" 单线 pipeline 不同——Matt 的链条里每一步都可以 grill 重新对齐。

工作流 2：Domain-Driven（领域驱动）

grill-with-docs
        ↓
   CONTEXT.md 持续更新
        ↓
   ADR 记录决策
        ↓
   domain-modeling 持续完善
        ↓
   shared language 在 agent + dev + 团队里通用

Matt 反复强调：shared language 是这个 repo 最 cool 的技术。原因——

1. 变量 / 函数 / 文件命名一致，代码库更易导航（agent 导航）
2. 更少 token 思考——agent 看到 "materialization cascade" 比看到"a lesson inside a section of a course is made 'real'" 消耗 token 少 10×
3. 变量名 = 测试名 = 文件名 = commit message，整个 repo 是一致的

他在 course-video-manager 仓库里给过一个真实例子：

• Before："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)"
• After："There's a problem with the materialization cascade"

后者读起来 几乎像代码。这就是 shared language 的力量。

第 8 节：Matt vs superpowers（obra）—— 两种风格的对比

我跟过两个 repo 的笔记。同一类问题，两个解法：

两个 repo 不互斥——superpowers 偏纪律（"你必须 TDD"），Matt 偏对齐（"先确认我们说的是同一件事"）。纪律在执行层最重要（避免退步），对齐在规划层最重要（避免建错）。我自己的 Hermes 工作流里两个都装了——superpowers 做底座，Matt 的 4 个核心（grill-me / tdd / codebase-design / writing-great-skills）做顶层。

第 9 节：怎么用他的思路写自己的 skill

我读完他的 repo 之后，把自己的 skill 写作流程归纳成 5 步：

Step 1：决定 user-invoked vs model-invoked

只手动用 → user-invoked（省 context）。AI 自动用 → model-invoked（写好 description）。

Step 2：写 description（1 行 trigger）

用 leading word。"Use when X — strict Y loop" 的句式。一个 trigger 一个分支。不要堆同义词。

Step 3：写 body

前面 3-5 行说原则。中间是 step 或 reference（用 leading word 替换啰嗦）。最后是完成准则（可检查）。

Step 4：no-op 测试

把每一行拿掉，agent 行为会变吗？不会变 = 删。

Step 5：leading word 替换

把啰嗦变简洁。"be very thorough" → "relentless"。"make sure the code is right" → "vertical slice"。

我自己用这 5 步写了 3 个新 skill：

• multi-agent-case-study：用来分析多 agent 协作的失败案例（user-invoked）
• finishing-a-development-branch：从 PR 到合到主分支的 6 步清单（model-invoked）
• chrome-headless-pdf：用 Chrome headless 生成中文 PDF，避过字体坑（model-invoked）

每个写完都 30-50 行。再长我就回头做 no-op 检测。

第 10 节：完整索引

22 个 skill 加上 3 个关键 reference 文件。我做了一个表方便查：

22 个 skill，加上 4 个 user-invoked + 1 个 model-invoked 的 productivity 子集。

收尾

这一篇我花了大概 2 个小时写完——不是"读"，是"读 + 在自己工作流里跑一遍 + 写"。如果你只读不跑，读完你可能觉得"嗯有道理"，但你写不出自己的 skill。

我建议这么读：

1. 先看 Matt 的 README（10 分钟）——理解他为什么写 22 个而不是 100 个
2. 挑 1 个 skill 装到你的 Claude Code / Codex（30 分钟）——grill-me 最容易起效
3. 找一个你最近在做的项目，用 grill-me 跑 1 轮（30 分钟）
4. 看 writing-great-skills（30 分钟）——然后写自己的 1 个 skill

如果你只想抄一份结论：leading word + 复用 + no-op 检测。这三个工具单独用都有价值，组合起来就是 Matt 的整个 repo。

—— 写完于 2026-08-03 的周日下午。上海下暴雨。