原始 GitHub 文件：

• SKILL.md
• GLOSSARY.md

这篇文章复现 Matt Pocock 的 writing-great-skills。目标是让读者同时得到两件东西：

• 先拿到一套完整中文 skill 文件，至少包含 SKILL.md 和 GLOSSARY.md 两份核心文件。
• 再看懂原 SKILL.md 里真正容易读浅的设计难点。

可读性更高的SKILL展示：writing-great-skills

1. 完整可复制中文 SKILL.md（主文件）

下面是第一份核心文件，也就是可直接复制为 SKILL.md 的中文版本。它保留原 skill 的结构和行为，但用中文重写。

---
name: writing-great-skills
description: 写作和编辑高质量 skill 的参考：提供让 skill 行为更可预测的词汇和原则。
disable-model-invocation: true
---

Skill 存在的目的，是从随机系统中争取确定性。**可预测性** 指 Agent 每次运行时采用同一种过程，而不是产出同样的文本。下面所有杠杆都服务于这个目标。

**加粗术语** 的完整定义应放在 `GLOSSARY.md` 中；当你不确定术语边界时，先查术语表再修改 skill。

## Invocation

先决定这条 skill 由谁触发。两种选择花费不同成本：

- **Model-invoked** skill 保留 **description**，这样 Agent 可以自动触发它，其他 skill 也可以触达它；用户仍然可以手动点名。代价是 **context load**：description 会在每轮对话里占用上下文窗口和注意力。机制上，不设置 `disable-model-invocation`，并写面向模型的 description，包含明确触发措辞，例如 “Use when the user wants...” 或 “Use when the user mentions...”。
- **User-invoked** skill 对 Agent 隐形，只能由用户输入名称触发，其他 skill 也不能自动触发它。它没有 context load，但会消耗 **cognitive load**：用户自己必须记住它存在，并知道什么时候使用。机制上，设置 `disable-model-invocation: true`；description 变成人类摘要，只写一句说明，不写触发清单。

只有当 Agent 必须自己想起这条 skill，或其他 skill 必须能触达它时，才选择 model-invocation。如果它只会由用户手动调用，就做成 user-invoked，避免支付 context load。

当 user-invoked skills 多到用户记不住时，用一个 **router skill** 处理 cognitive load：这个 user-invoked skill 只列出其他 user-invoked skills 以及什么时候该用它们。

## Writing the description

model-invoked 的 **description** 有两个职责：说明这条 skill 是什么，以及列出哪些 **branches** 应该触发它。description 中每个词都会增加 context load，所以它比正文更需要修剪：

- **把 leading word 放在前面**：description 是 leading word 发挥 invocation 作用的地方。
- **每个 branch 只保留一个 trigger**：同义词如果只是重命名同一个 branch，就是 **duplication**。例如 “build features using TDD” 和 “asks for test-first development” 通常是同一个 branch 写了两遍。合并它们，只保留真正不同的触发分支。
- **删除正文里已经说明的身份信息**：description 只保留触发条件，以及必要的 “when another skill needs...” 触达说明。

不要把 description 写成正文流程摘要。description 负责触发 skill，不负责替代 `SKILL.md`。

## Information hierarchy

Skill 由两类内容构成：**steps** 和 **reference**。它们可以自由组合：一条 skill 可以全是 steps、全是 reference，也可以两者都有。核心决策是：使用哪类内容，以及它们位于 **information hierarchy** 的哪一层。

信息层级按 Agent 多快需要这些材料排序：

1. **In-skill step**：写在 `SKILL.md` 里的有序动作，是最高优先级。它告诉 Agent 按什么顺序做什么。每个 step 都应结束于 **completion criterion**，即判断该步骤完成的条件。completion criterion 要尽量可检查，必要时要穷尽。例如 “every modified model accounted for” 比 “produce a change list” 更强；模糊标准会诱发 **premature completion**。
2. **In-skill reference**：写在 `SKILL.md` 里的定义、规则或事实，供 Agent 按需查阅。它可以是平铺的同级规则集，例如 review skill 中每条规则都同等重要。平铺不一定是坏味道。`writing-great-skills` 本身就是全 reference 型 skill。
3. **External reference**：从 `SKILL.md` 拆到单独文件里的参考内容，通过 **context pointer** 触达，只在 pointer 触发时加载。它可以是同目录下的 `GLOSSARY.md`，也可以是 skill 系统外的普通参考文件。

强 completion criterion 会驱动更充分的 **legwork**。这不只适用于步骤型 skill；即使是平铺 reference，只要要求“每条规则都应用”，也会驱动 Agent 做更多幕后工作。

放下去太少，`SKILL.md` 顶部会臃肿；放下去太多，又会隐藏 Agent 实际需要的材料。这个张力就是 information hierarchy 的核心决策。

**Progressive disclosure** 是把 reference 沿层级往下移动：从 `SKILL.md` 移到链接文件里，让顶部保持清晰。机制上，在 skill 目录里放一个命名明确的 `.md` 文件，例如把完整术语定义放到 `GLOSSARY.md`。

一条 skill 可能有多种使用方式；每种不同使用方式就是一个 **branch**。branch 是最干净的 disclosure 判断标准：每条 branch 都需要的内容留在正文，只有某些 branch 需要的内容放到 pointer 后面。**Context pointer** 的措辞，而不是目标文件本身，决定 Agent 什么时候以及多可靠地读取该材料。

如果 information hierarchy 决定一块内容放多深，那么 **co-location** 决定它和谁放在一起：一个概念的定义、规则和 caveats 应放在同一个标题下，不要散落在文件各处。

## When to split

**Granularity** 是 skill 拆多细的问题。每次拆分都会花掉两种负载之一，所以只有拆分收益明确时才拆。

有两种拆法：

- **按 invocation 拆**：当你有一个独立 **leading word** 应该触发某条 model-invoked skill，或另一个 skill 必须能触达它时，拆出一条 model-invoked skill。代价是新的 description 会常驻上下文，增加 context load；独立触达必须值得这个成本。
- **按 sequence 拆**：当一个步骤后面的 **post-completion steps** 会诱导 Agent 匆忙结束当前步骤，即发生 **premature completion**，就把步骤序列拆开。让后续步骤不在当前上下文里，可以促使 Agent 在当前任务上投入更多 **legwork**。

拆分不是为了形式上的模块化，而是为了控制 context load、cognitive load 和 premature completion。

## Pruning

每个含义都应该有一个 **single source of truth**：只有一个权威位置。这样修改行为时，只需要改一个地方。

逐行检查 **relevance**：这一行是否仍然服务于这条 skill 要做的事？

然后逐句猎杀 **no-ops**，不要只按行检查。把每个句子单独拿出来做 no-op 测试：它会改变模型相对于默认行为的表现吗？如果不会，删除整句，而不是试图修饰它。要激进一点；大多数 no-op prose 应该被删除，不是被改写。

## Leading words

**Leading word** 是一个模型预训练中已经熟悉的紧凑概念，Agent 在运行 skill 时会用它来思考。例如 _lesson_、_fog of war_、_tracer bullets_。它可以在很少 token 内编码一个行为原则，因为它借用了模型已有先验。

leading word 通过重复出现积累分布式定义，锚定一整片行为区域。它不一定必须重复很多次；足够强的 leading word 可能出现一次就够。

它服务可预测性两次：

- 在正文里，它锚定 **execution**：每次这个词出现，Agent 都会回到同一类行为。
- 在 description 里，它锚定 **invocation**：当同一个词出现在用户提示、文档和代码库里，Agent 更容易把这个共享语言和 skill 连接起来，更可靠地触发 skill。

主动寻找能用 leading word 重构 skill 的地方。一个意思被三个句子反复解释，或者 description 花一整句模糊指向某个概念，通常都可以压缩成一个 token。

例子：

- “fast, deterministic, low-overhead” 可以压成 _tight_，例如 a _tight_ loop。
- “a loop you believe in” 可以压成 _red_，把模糊门禁变成可观察的二值状态：这个循环有没有在 bug 上变红？

收益有两个：更少 token，以及更锋利的思考挂钩。假设每条 skill 都带着可以被 leading word 替代的重复说明，然后去找它们。

## Failure modes

用这些失败模式诊断用户在使用 skill 时遇到的问题。

- **Premature completion**：当前步骤还没真正完成，Agent 的注意力就滑向“已经完成”。防御顺序：先锐化 completion criterion，因为这是局部且便宜的修复；只有当标准无法再清晰、且你确实观察到 rushing 时，才通过拆分隐藏 post-completion steps。
- **Duplication**：同一个含义出现在多个地方。它增加维护成本和 token 成本，还会把这个含义在信息层级中的权重抬得过高。
- **Sediment**：旧内容因为“添加安全、删除危险”而沉积下来。没有修剪纪律的 skill 默认都会出现 sediment。
- **Sprawl**：skill 单纯太长，即使每一行都还有效、也不重复。它损害可读性、可维护性并浪费 token。解决方法是使用 information hierarchy：把 reference 放到 pointer 后面，并按 branch 或 sequence 拆分，让每条路径只携带需要的内容。
- **No-op**：模型默认就会遵守的句子。你付出了 load，却没有改变行为。测试方式是：这句话会改变模型相对于默认行为的表现吗？弱 leading word 也可能是 no-op，例如当模型本来就会稍微认真时，_be thorough_ 并不会增加多少约束；修复方式是换成更强的词，例如 _relentless_，而不是换一种技术。

2. 完整可复制中文 GLOSSARY.md（术语文件）

下面是第二份核心文件，也就是可直接复制为 GLOSSARY.md 的中文版本。它负责定义这条 skill 的术语边界，和主文件一起才算完整。

# Glossary：好 Skill 的术语模型

什么样的 skill 才算好，这里给出它的领域模型。skill 的目的，是从随机系统中尽量拽出确定性；下面每个术语，都是作用在这个目标上的一个杠杆。这是 [`writing-great-skills`](SKILL.md) 所披露出来的参考文件。

任意定义里的 **加粗术语**，也都在这个 glossary 中有自己的条目；按标题查找即可。

## Language

### Predictability（可预测性）

一条 skill 让 Agent 在每次运行时都以同一种 *方式* 行动的程度。这里的一致性指的是过程一致，而不是输出一致。比如 brainstorming skill 应该“可预测地发散”：每次 token 可以不同，但行为模式应该稳定。它是其他所有术语共同服务的根目标；成本和可维护性只是它的外在症状，不是与它并列的竞争目标。

_Avoid_: consistency, reliability, robustness, output-determinism

这里的 `_Avoid_` 不是“这些词绝对不能出现”，而是“不要把它们当成 `Predictability` 的同义替代词”，因为它们会把“过程稳定”误带成“系统可靠”或“输出确定”。后文类似。

### Model-Invoked（模型触发型）

保留 **description** 字段的 skill。这样 Agent 能看见它并自主触发，人也仍然可以手动输入它的名字，所以 model-invocation 总是包含用户可达。不存在“只有模型能用、用户反而不能用”的状态：description 只会增加 Agent 的发现能力，不会减少人的触达能力。它用永久性的 **context load** 换来可发现性。它也可以被其他 skill 触达，因为 description 让它对 Agent 可发现，也就对 skill 可调用。一个内容全是 **reference** 的 model-invoked skill，还可以作为共享参考的归宿：多个 skill 需要的参考，可以放在这一个可调用的地方。只有在 Agent 必须能自己想到这条 skill 时，才选择 model-invocation；如果它永远只会被手动调用，就删除 description，不支付 context load。

_Avoid_: ability, tool, capability

### User-Invoked（用户触发型）

去掉 **description** 的 skill。它对 Agent 不可见，只能由人手动输入名称来触发。所以 user-invoked 是“只有用户能触达”，而 **model-invoked** 是“用户和模型都能触达”。它用放弃 Agent 可发现性来换取零 **context load**。因为没有 description，除了人之外没有东西能触达它：其他 skill 也无法自动触发它。

_Avoid_: procedure, workflow, command

### Description

skill 的机器可读触发器，也是 **model-invoked** skill 被迫始终加载在上下文中的那个 **context pointer**。它的存在本身就是 invocation 轴：保留它，skill 就是 model-invoked；删掉它，skill 就是 **user-invoked**，只能由人触达。它也是 model-invoked skill **context load** 的来源。

_Avoid_: frontmatter, summary

### Context Pointer

一种保留在 Agent 上下文里的指针：它指向上下文外的材料，并编码“什么时候该去读它”的条件。**Description** 是最上层的 context pointer（从上下文窗口指向 skill）；指向披露文件的链接，是同一种对象在下一层的表现。真正决定 Agent 什么时候去读、以及读得是否可靠的，不是目标文件，而是 pointer 的措辞。一个必须读取的材料，如果被放在措辞很弱的 pointer 后面，就是方差 bug：先修 pointer 的写法，只有在写法强化仍然无效时，才把材料重新内联回正文。

_Avoid_: link, reference, import

Context Pointer 强调的是“指向 + 触发条件 + 读取可靠性”，而 link/reference/import 都只抓到其中一部分。

### Context Load

**Model-invoked** skill 对 Agent 上下文窗口施加的成本。它的 **description** 会在每一轮都被加载，持续消耗 token 和注意力。**User-invoked** skill 正是通过没有 description 来逃避这种成本。它也是“是否继续拆成更多 model-invoked skills”的制动器。

_Avoid_: token cost, context bloat

- token cost 说得太窄，只讲数量
- context bloat 说得太偏结果，只讲臃肿
- Context Load 讲的是 持续占用上下文窗口的整体负担：token + 注意力

### Cognitive Load

**User-invoked** skill 加在人身上的成本：用户必须在脑中记住有哪些 skill、什么时候该用哪一个，也就是“人自己当索引”。这正是 **model-invocation** 帮用户拿掉的负担，也是“是否继续拆成更多 user-invoked skills”的制动器。它不是要被一味最小化的成本：它本身就是人类能动性的价格。有些地方必须保留人的判断，就应该花这笔 cognitive load；不需要人的地方，才应该尽量移除。

_Avoid_: human index, burden, overhead

### Granularity（粒度）

skill 拆得有多细。拆得越细，就越会花掉两类负载中的一类：更多 **model-invoked** skills 会增加 **context load**，因为更多 description 会常驻上下文并争夺注意力；更多 **user-invoked** skills 会增加 **cognitive load**，因为用户要记住更多东西。拆分主要有两种依据。按 **invocation** 拆：当你有一个清晰的 **leading word**，并且你确实会在提示词里用它来触发 skill，就可以把它拆成独立的 model-invoked skill。按 **sequence** 拆：当一串 **steps** 里的某一步后续内容必须被隐藏时，就应该拆开，因为把它隔离进自己的上下文，能让后面的东西暂时消失。也要小心反过来：把多个 sequence 合并，会让每个步骤都暴露在后续 **post-completion steps** 面前，从而诱发 premature completion。

_Avoid_: chunking, modularity

### Router Skill

一种 **user-invoked** skill，它的职责是指向其他 user-invoked skills：列出它们是什么、什么时候该用哪个。这样用户只需要记住一个 skill，而不是很多个。它只能提示，不能真正触发那些 skill，因为 user-invoked skills 没有 **description**，除了人之外没人能触达它们。当 user-invoked skills 多到难记时，router skill 就是解决 **cognitive load** 的办法。

_Avoid_: dispatcher, menu, registry, index, router procedure

### Information Hierarchy（信息层级）

skill 内容按“Agent 多快需要它”排序后形成的层级。它由两次切分共同决定：内容是在文件内，还是放到 pointer 后面；内容是 step，还是 reference。层级从上到下是：

- **Steps**：文件内，主层
- 文件内的 **Reference**：次层
- 被披露到 pointer 后面的 **Reference**

一条没有 **steps** 的 skill，只使用下面两层，而且这通常完全合理。例如 review skill 中的所有规则都可以平铺在同一层上，这不是坏味道。信息层级和 invocation 是独立的：一条 skill 无论是 model-invoked 还是 user-invoked，都可以是全 steps、全 reference，或两者兼有。真正有步骤的 skill，如果把本该披露下去的 reference 留在文件内，就会把 steps 埋住，让 Agent 是否注意到它们变成掷硬币，这不只是可读性问题，而是方差来源。顶部必须保持清晰，能往下推的内容就尽量推下去。

作用：首先是保护注意力，让Agent专注重要步骤；其次是token 优化。

_Avoid_: structure, organization, layout

### Co-location（共置）

把 Agent 在同一时刻需要一起读的东西放在一起。比如一个概念的定义、规则和 caveats 放在同一个标题下，而不是散落在不同段落里。它是 **Information Hierarchy** 在文件内部的配套原则：hierarchy 决定一块内容放多深，co-location 决定它和什么放在一起。reference 没有固定的唯一格式，判断标准是：这份 skill 读起来是否像一份写给 Agent 的文档。该放在一起的内容放在一起时，它会更像；分散时就不像。它和 **Duplication** 不同：duplication 是同一个意思重复了两遍；scattering 是同一个意思被拆散到很多地方。

_Avoid_: grouping, clustering, cohesion

### Branch

skill 被调用的一种不同方式，也就是它要处理的一个分支。不同 branch 会让 skill 在不同运行中走不同路径。一条带很多步骤的 skill 可能有很多 branch；完全线性的 skill 则可能没有。

_Avoid_: path, case, fork

### Progressive Disclosure（渐进披露）

把 **reference** 沿着层级往下移动：从 `SKILL.md` 挪到 **context pointer** 后面，让顶部保持清晰。它首先不是一种 token 优化，而是保护 **information hierarchy** 的办法。它的许可条件来自 **branching**：只有部分 branch 需要的材料可以披露下去；每条路径都需要的材料要留在正文里。如果某个必须读取的材料放在 pointer 后面却总是触发不稳，先强化 pointer 的措辞，只有失败后才把材料重新拉回正文。

_Avoid_: lazy loading, chunking

### Steps

Agent 需要按顺序执行的动作。如果一条 skill 有 steps，它们就是正文里的主层内容，也是它真正值得放进 `SKILL.md` 的部分。不是所有 skill 都必须有 steps：一条 skill 可以全是 steps（如 `tdd`），全是 **reference**（如一条 review skill），也可以两者兼有，而这与 invocation 无关。每个 step 都会结束在一个 **completion criterion** 上，无论这个 criterion 是清晰还是模糊。

_Avoid_: workflow, instructions, choreography

### Completion Criterion

告诉 Agent 一段工作何时算完成的条件，也就是它判断 done 与 not-done 的依据。它有两个真正起作用的属性。第一是 **清晰度**：Agent 能不能判断什么时候完成？它用来抵抗 **premature completion**。模糊边界例如“理解到了”会让 Agent 很容易自认完成并滑到下一步；这条作用只在存在 steps 时才成立，因为 premature completion 是 steps 之间的失败。第二是 **要求强度**：它要求 Agent 做多少 **legwork**。例如“每个修改过的 model 都交代清楚”会迫使 Agent 做扎实工作，而“列出改动清单”就不会。这个维度不依赖 steps：它也可以约束一组平铺的 reference，因此一条没有 steps 的 skill 仍然可以有穷尽性要求，例如“每条规则都应用”。最强的 completion criterion 同时具备可检查性和穷尽性。

_Avoid_: done condition, exit condition, stopping rule

### Post-Completion Steps

当前步骤之后还没开始的那些 **steps**。只要它们可见，就会把 Agent 的注意力往前拉，诱发 **premature completion**。看到的后续越多，拉力越强；防御方式是通过拆 sequence 把后续步骤藏起来。

_Avoid_: horizon, fog of war, lookahead

### Legwork

Agent 在单个步骤内部做的幕后工作，例如读文件、探索代码库、实际改代码、自己挖出需要的信息，而不是把这些工作转嫁给用户。它存在于步骤结构之下：不应该被单独写成 step，而是隐含在措辞里，由 Agent 主导而不是由 skill 直接编排。它是 **post-completion steps** 那种“跨步骤拉力”在步骤内部的对应物。它会被更强的 **leading word** 拉高，也会被更强的 **completion criterion** 拉高，包括那种作用在平铺 reference 上的穷尽性要求。它会变薄，要么因为要求本来就弱，要么因为 **premature completion** 提前把步骤截断了。

_Avoid_: scope, effort, diligence, coverage

### Reference

Agent 按需查阅的材料：定义、事实、参数、例子、条件指令等。如果 skill 有 **steps**，reference 是次层；如果没有 steps，reference 就是全部内容；或者它甚至可以完全在 skill 系统外，这就是 **External Reference**。reference 通过 **context pointers** 被触达，也是 **progressive disclosure** 最该处理的对象。

_Avoid_: supporting material, docs, background

### External Reference

存在于 skill 系统之外的 **reference**：一个普通文件，没有 **description**，没有 **steps**，也不可被调用，但任何 skill 都可以指向它。它适合承载那些不需要自己独立触发、但可能被多条 skill 共享的参考内容。对于两条 **user-invoked** skills 来说，它也是唯一可共享的归宿，因为它们彼此都没有 description，不能互相调用。

_Avoid_: doc, resource, knowledge base

### Leading Word

一个紧凑的概念，也可理解为 *Leitwort*。它最好已经存在于模型预训练中，因此 Agent 在运行 skill 时能直接“借用”它来思考。例如 _lesson_、_proximal zone of development_、_fog of war_、_tracer bullets_。它用最少的 token 编码一个行为原则，因为它调用了模型已有的先验。leading word 应该重复为“词”，而不是重复为整句解释；这样它会在全文中逐渐积累起分布式定义，锚定一整片行为区域。你当然也可以自己造词，只要定义得足够清楚；但造词无法借用现成先验，会把原本可以白拿的语义改成你必须自己付 token 去解释的成本，所以优先选已有词。

leading word 会双重服务 **predictability**。在正文里，它锚定 **execution**：每次这个概念出现，Agent 都更容易回到同一类行为；即使在一堆平铺的 reference 里，它也能把注意力聚焦到同一类检查点上。在 **description** 里，它锚定 **invocation**：而且不只是 skill 内部。当同一个词同时出现在你的 prompt、文档和代码库里，Agent 更容易把这套共享语言和 skill 对上。description 最好也使用你平时真的会说出来的 leading words。

_Avoid_: keyword, term, motif

### Single Source of Truth

理想状态是：每个含义都只有一个权威位置。这样你要修改 skill 行为时，只改一处即可。**Duplication** 就是对这个状态的破坏。

_Avoid_: home, canonical location

### Relevance

一行内容是否仍然服务于这条 skill 要做的事。这是判断该保留什么的镜头。失去 relevance 有两种方式：要么一开始就没真正服务任务，只是多余解释，或者是本该披露下去的 **branch**；要么它曾经相关，但后来过期了。skill 越短，越容易保持 relevant，因为每一行都更便宜复查。它和 **no-op** 不同：relevance 判断的是“是否相关”，不是“是否真的改变了行为”。

_Avoid_: load-bearing, staleness, freshness

## Failure Modes

### Premature Completion

当前步骤还没真正完成，Agent 的注意力就已经滑向“尽快完成”。这是 steps 之间的失败：没有 **steps** 的 skill 如果提前停下，不叫 premature completion，而叫在要求不足时出现的薄 **legwork**。它是两股力量的拉扯结果：一边是可见的 **post-completion steps** 往前拉，另一边是 **completion criterion** 的清晰度在往后稳住。模糊边界是必要条件：一个锋利、可检查的边界可以抵抗后续拉力，无论后面还暴露了多少步骤。所以防御顺序必须是：**先锐化 completion criterion**，因为这便宜而且局部；只有当这个边界真的无法再清晰，而且你也确实观察到 rushing 时，才去 **隐藏后续步骤**。而隐藏只有跨越真实的上下文边界才有效，例如交给一个 user-invoked hand-off 或 subagent；内联的 model-invoked 调用不会让后续步骤真的消失。它是导致薄 legwork 的一种原因，但两者并不等价：就算一个步骤完整跑完，legwork 也可能仍然很薄。

_Avoid_: premature closure, the rush, rushing, shortcutting

### Duplication

同一个含义有不止一个 **single source of truth**。它会增加维护成本，因为你改一处就得改所有重复处；也会增加 token 成本；还会错误抬高这个含义在信息层级中的权重。它正好和 **leading word** 相反：leading word 是为了有意提高一个概念的注意力，而 duplication 是无意间把同一个意思写了两次。

_Avoid_: repetition, redundancy

### Sediment

旧内容像沉积层一样堆在 skill 里不再被清理。因为添加看起来安全，删除看起来危险，于是过时和不相关的内容一层层沉下来。没有修剪纪律的 skill，默认都会走向 sediment。它是 **relevance** 被长期侵蚀后的状态，而不是 **duplication** 那种简单的重复。

_Avoid_: accretion, bloat, cruft, rot

### Sprawl

skill 单纯太长了。即使每一行都还活着、每一行都不重复，它依然可能 sprawl。它会损害可读性，因为 Agent 在行动前得先穿过更长的正文，注意力也会被拉薄；会损害可维护性，因为每多一行就多一行要保持 **relevant**；也会浪费 token。解决方法是用 **information hierarchy**：把 **reference** 放到 **context pointers** 后面，并按 **branch** 或 sequence 拆分，让每条路径只携带它真正需要的内容。它不同于 **sediment**（长度来自沉积）和 **duplication**（长度来自重复）；sprawl 是“长度本身”。

_Avoid_: bloat, length, size, verbosity

### No-Op

一条不会改变任何行为的指令，因为模型默认就会这么做。你为它支付了 load，却没有得到行为增量。判断方法是：相对于默认行为，这一行真的改变了什么吗？一条内容可以完全 **relevant**，却仍然是 no-op。让 **leading word** 能白嫖先验的同一套模型特性，也让 no-op 变得毫无价值。

leading word 是一种 *技术*，No-Op 是对一行内容的 *判决*；两者会交叉。一个太弱的 leading word 也可能是 no-op，例如当模型本来就已经“有点认真”时，_be thorough_ 没有带来新的约束；修复方式不是换技术，而是换成更强、真正能通过 no-op 测试的词，例如 _relentless_。所以 no-op 测试同时也是在检验 leading word 是否值得它那几次重复。它是模型相对的，而不是读者相对的：两个人如果争论一行是不是 no-op，本质上是在争论“默认行为是什么”，这要通过运行 skill 来验证，而不是靠辩论。

_Avoid_: redundant instruction, restating the obvious, belaboring

3. 后文只挑疑难点，并加入主动回忆

前面已经把完整中文 SKILL.md 和 GLOSSARY.md 放出来了，所以后面不再贴完整原文，也不逐节复述中文主文件已经说清楚的内容。

这里的目标换成长期记忆：每个难点都给出一个非平凡判断，再给几个需要主动提取的回忆题。先自己答，再回看上文。

后文只处理这些容易读浅的点：

• information hierarchy 解决的不是排版，而是注意力优先级
• leading word 不是神秘开关，而是可测试的语义压缩
• no-op 怎么判断
• failure modes 如何变成诊断框架

4. Information hierarchy：真正难的不是分类，而是取舍

表面上，information hierarchy 只是把内容分成 steps、in-skill reference、external reference。真正难的是判断：当前最该让 Agent 先看到什么。

它首先不是 token 优化。省 token 只是副作用。核心问题是：如果 SKILL.md 顶部塞满暂时不需要的参考、定义、例子，Agent 就更难稳定抓到当前该执行的主线。顶部材料的角色，是保护注意力顺序。

这也不等于专门防 premature completion。两者有关，但层级不同：

• information hierarchy 处理“什么材料先出现、什么材料后出现”
• premature completion 处理“当前步骤为什么过早自认完成”

后者常常需要先修 completion criterion；前者则是在安排材料位置，避免步骤、参考、外部材料混成一团。

快速回忆：

1. 为什么说 progressive disclosure 不是首先为了省 token？
2. 一条全 reference 的 skill 为什么仍然可以是好 skill？
3. 如果一个必须读取的材料被放到 pointer 后面，但 Agent 总是不读，第一修复动作是什么？

答案要点：

• 因为它保护的是顶部注意力顺序，不只是减少字数。
• 因为有些 skill 的职责就是提供判断框架或规则集合，不需要有序步骤。
• 先强化 pointer 的措辞；只有 pointer 变强仍失败，才考虑重新内联。

5. Leading word：它是可测试的语义压缩，不是模型内置开关

leading word 值得学，但不能神化。它不是说每个模型内部都有一张公开词表，写下某个词就必然触发固定行为。

更稳妥的理解是：某些词或短语在训练语料中携带了高密度实践语境，因此有机会用更少 token 牵出更稳定的行为模式。它利用的是模型的分布式语义联想，不是一个显式暴露的 API。

所以 leading word 的判断标准不是“词看起来高级”，而是它能不能真的压缩并稳定召回一个行为区域。

几个例子：

• lesson：不是单纯“课程”，而是一整套教学单元感
• fog of war：不是修辞，而是“故意隐藏后续信息，防止提前行动”
• tracer bullets：不是“先做 demo”，而是“先打一条端到端可验证路径”
• red：不是颜色，而是 TDD 语境里“门槛是否真的失败”的二值状态

leading word 必须接受 no-op 测试。be thorough 往往太弱，因为模型默认就会有点认真；relentless 更可能改变行为，因为它把过程拉向持续追问、不轻易停手。

快速回忆：

1. leading word 和普通 keyword 的差别是什么？
2. 为什么自己造词通常比使用已有词更贵？
3. 为什么 be thorough 可能是 no-op，而 relentless 不一定是？

答案要点：

• keyword 主要负责匹配；leading word 试图压缩并召回一整片行为模式。
• 造词不能借模型已有先验，必须在正文里额外付 token 定义。
• be thorough 接近模型默认行为；relentless 更具体地改变停止条件和追问强度。

6. 怎么判断 no-op

no-op 的核心测试是：删掉这句话以后，模型行为会不会和默认行为有可观察差异？

如果答案是“基本不会”，它就是 no-op。它可能相关、正确、听起来积极，但仍然不改变行为。

判断时不要问“这句话好不好”，而要问四个更硬的问题：

1. 默认行为测试：没有这句话，模型大概率也会这么做吗？
2. 行为增量测试：这句话新增了具体动作、顺序、证据、边界或完成条件吗？
3. 违例可见性测试：如果模型没遵守这句话，能不能明确指出它违反了什么？
4. 失败模式测试：这句话到底在防哪一种默认失败？如果说不出来，通常很可疑。

几个对照：

• “请认真检查代码。”
  通常是 no-op。它没有定义认真到什么程度，也没有给出可检查完成标准。

• “检查所有被修改的 model，并说明每个 model 的行为是否受影响。”
  不是 no-op。它新增了对象范围、动作和完成条件。

• “使用最佳实践。”
  通常是 no-op。最佳实践没有领域边界，也没有违例标准。

• “不要标记完成，直到新增测试覆盖失败路径且本地测试通过。”
  不是 no-op。它改变了完成条件。

快速回忆：

1. 为什么“相关”不等于“不是 no-op”？
2. 判断 no-op 时，最重要的问题是什么？
3. leading word 为什么也可能是 no-op？

答案要点：

• 一句话可以和任务相关，但如果模型默认也会做，它没有行为增量。
• 删掉这句话以后，行为是否有可观察差异。
• 如果它太弱、太泛，或只换了说法没有改变约束，就仍然是 no-op。

7. Failure modes：术语最后要能变成诊断动作

failure modes 的价值不是背名字，而是每个名字都对应一种修法。

• premature completion：先锐化 completion criterion；只有确实观察到 rush，才考虑隐藏 post-completion steps
• duplication：合并到 single source of truth
• sediment：删除过时沉积层
• sprawl：重新安排 information hierarchy，或按 branch / sequence 拆
• no-op：删掉没行为增量的句子，或换成更强的约束

这里最值得抓的是 no-op 和 leading word 的交叉。原文不是说 leading word 总是好，而是说：leading word 也必须证明自己不是 no-op。这把词汇选择从审美问题拉回到行为问题。

快速回忆：

1. 哪个 failure mode 最容易由“只加不删”造成？
2. 哪个 failure mode 最适合先检查 completion criterion？
3. 哪个 failure mode 会让一个概念在文档里显得比它实际更重要？

答案要点：

• sediment
• premature completion
• duplication

8. 快速复习关键思想

这一节不再重复文件结构，而是用来做间隔复习。读完前面的完整 SKILL.md、GLOSSARY.md 和难点分析后，应该能在不看上文的情况下提取出下面这些判断。

关键思想压缩：

• Skill 的目标不是让输出固定，而是让过程更可预测。
• description 不是摘要，而是 model-invoked skill 的触发器。
• context load 不只是 token 数量，还包括注意力占用。
• information hierarchy 不是排版技巧，而是在保护 Agent 先看到当前最该看的材料。
• progressive disclosure 首先不是 lazy loading，而是把低频 reference 放到 pointer 后面，维护顶部主线。
• completion criterion 的强弱会直接影响 legwork 的厚度。
• leading word 不是关键词，而是可测试的语义压缩；它也可能是 no-op。
• no-op 的判断标准不是“这句话是否正确”，而是“删掉以后行为是否有可观察差异”。
• failure modes 不是术语列表，而是诊断入口；每个失败模式都应该对应一个修法。
• GLOSSARY.md 不是附录，而是术语边界文件；它本身就是 progressive disclosure 的示范。

快速回忆：

1. Predictability 为什么不是 output-determinism？
2. Context Pointer 为什么不只是 link？
3. Context Load 比 token cost 多了哪一层含义？
4. Information hierarchy 在保护什么？
5. 什么内容应该留在 SKILL.md，什么内容可以放到 GLOSSARY.md？
6. 一个 completion criterion 怎样才算更强？
7. leading word 和普通 keyword 的差别是什么？
8. 怎么判断一句话是不是 no-op？
9. premature completion 为什么优先修 completion criterion，而不是马上拆 skill？
10. duplication 为什么会错误抬高一个概念的重要性？

答案要点：

• Predictability 是过程稳定，不是结果一样。
• Context Pointer 同时包含指向、触发条件和读取可靠性。
• Context Load 还包含注意力竞争。
• 它保护当前最该先被 Agent 看到的材料。
• 高频原则和必须执行的步骤留在 SKILL.md；完整术语边界、低频参考、分支性材料可以放到 pointer 后面。
• 更强的标准应该可检查、范围明确，必要时穷尽覆盖。
• keyword 更偏匹配；leading word 试图召回一整片行为模式。
• 删掉它，看模型行为是否仍然基本一样。
• 因为模糊完成标准是 premature completion 的直接入口；拆分是更重的修复。
• 重复出现会让模型误以为这个概念在信息层级里权重更高。