writing-great-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill 的存在，是为了从随机系统中拧出 determinism。Predictability 是根本美德：agent 每次采取相同的 process，而不是产出相同的 output。下面所有杠杆都服务于它。

粗体术语 在

GLOSSARY.md

中定义；需要完整含义时查那里。

Skills exist to extract determinism from stochastic systems. Predictability is the core virtue: the agent follows the same process every time, rather than producing the same output. All the levers below serve this goal.

Bold terms are defined in

GLOSSARY.md

; refer to it for full meanings.

Invocation

两种选择，成本不同：

Model-invoked skill 保留 description，所以 agent 可以自主触发它，其他 skills 也能触达它（用户仍可手动输入名称）。它会带来 context load：description 每轮都在 context window 中。机制：省略
```
disable-model-invocation
```
，并写 model-facing description，带丰富触发措辞（"Use when the user wants..."、"mentions..."）。
User-invoked skill 把 description 从 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 以及何时使用它们。

Two options, with different costs:

Model-invoked skills retain their description, so the agent can trigger it autonomously, and other skills can also access it (users can still manually input the name). It incurs context load: the description stays in the context window every round. Mechanism: Omit
```
disable-model-invocation
```
, and write a model-facing description with rich trigger phrasing ("Use when the user wants...", "mentions...").
User-invoked skills remove the description from the agent's reach: it can only be called when the user inputs the name, and other skills cannot invoke it either. Zero context load, but incurs cognitive load: the user must remember it exists. Mechanism: Set
```
disable-model-invocation: true
```
; the
```
description
```
becomes a one-line summary for humans, not included in the trigger list.

Choose model-invoked only when the agent must find the skill on its own, or another skill needs to call it. If it will only be triggered manually, make it user-invoked to avoid paying context load.

When there are too many user-invoked skills for users to remember, solve the cognitive load with a router skill: a user-invoked skill responsible for naming other user-invoked skills and when to use them.

Writing the description

Model-invoked description 做两件事：说明 skill 是什么，并列出应触发它的 branches。每个词都会增加 context load，所以 description 比正文更需要修剪：

把 skill 的 leading word 放前面。
每个 branch 一个 trigger。 同义词如果只是重命名单一 branch，就是 duplication；合并它。
删掉正文已有的 identity。 Description 只保留 triggers，以及必要的 "when another skill needs..." reach clause。

Model-invoked descriptions do two things: explain what the skill is, and list the branches that should trigger it. Every word increases context load, so descriptions need more pruning than the main text:

Put the skill's leading word first.
One trigger per branch. Synonyms that only rename a single branch are duplication; merge them.
Remove identity already present in the main text. The description only retains triggers and the necessary "when another skill needs..." reach clause.

Information hierarchy

Skill 由两类内容构成：steps 与 reference。它可以全是 steps、全是 reference，或两者都有。核心决策是把内容放在 information hierarchy 的哪一层：

In-skill step -
```
SKILL.md
```
中的有序动作，是 primary tier。每个 step 以 completion criterion 结束。Criterion 要可检查，必要时要 exhaustive。
In-skill reference -
```
SKILL.md
```
中的定义、规则或事实，按需查阅。
External reference - 从
```
SKILL.md
```
推到独立文件中，经 context pointer 触达。

强 completion criterion 会驱动充分 legwork。把太少内容下放会让顶层膨胀；把太多内容下放会隐藏 agent 实际需要的材料。

Progressive disclosure 是把 reference 下移到链接文件中，让顶层保持清晰。Mechanics：skill folder 中的 linked

.md

文件，用内容命名。多用途 skill 的每种用法都是一个 branch：所有 branches 都需要的内容内联，只有部分 branches 需要的内容放到 pointer 后面。Context pointer 的措辞，而不是目标文件，决定 agent 何时以及多可靠地触达材料。

Co-location 决定内容一旦下放后放在哪里：把一个概念的定义、规则和 caveats 放在同一 heading 下，而不是散落各处。

Skills consist of two types of content: steps and reference. They can be all steps, all reference, or a mix of both. The core decision is which layer of the information hierarchy to place the content in:

In-skill step - Ordered actions in
```
SKILL.md
```
, the primary tier. Each step ends with a completion criterion. The criterion should be verifiable and exhaustive if necessary.
In-skill reference - Definitions, rules, or facts in
```
SKILL.md
```
, accessed on demand.
External reference - Pushed from
```
SKILL.md
```
to an independent file, accessed via a context pointer.

Strong completion criteria drive sufficient legwork. Putting too little content lower down bloats the top layer; putting too much content lower down hides materials the agent actually needs.

Progressive disclosure is moving reference content down to linked files to keep the top layer clear. Mechanics: Linked

.md

files in the skill folder, named after their content. Each use case of a multi-purpose skill is a branch: content needed by all branches is inline, content needed only by some branches is placed after a pointer. The wording of the context pointer, not the target file, determines when and how reliably the agent accesses the material.

Co-location determines where content is placed once moved down: keep the definition, rules, and caveats of a concept under the same heading, rather than scattered.

When to split

Granularity 是 skill 切分粒度。每次切分都会花两种 load 之一，所以只有切分有收益时才切。

By invocation - 当你有一个独立 leading word 应自主触发，或另一个 skill 必须触达它时，拆出 model-invoked skill。你要为新 description 支付 context load，所以独立触达必须值得。
By sequence - 当后续 steps 会诱使 agent 急着结束前一步（premature completion）时，拆分 step sequence，把后面的内容隐藏起来。

Granularity refers to how skills are split. Each split incurs one of the two types of load, so only split when there is a benefit.

By invocation - Split out a model-invoked skill when you have an independent leading word that should trigger autonomously, or another skill needs to access it. You pay context load for the new description, so independent access must be worthwhile.
By sequence - Split the step sequence when subsequent steps tempt the agent to finish the previous step early (premature completion), hiding the later content.

Pruning

让每个 meaning 都有 single source of truth：一个权威位置，行为变化时只改一处。

逐行检查 relevance：它是否仍支撑 skill 的工作？

然后逐句寻找 no-ops。把每个句子单独做 no-op test；失败时删除整句，而不是只修剪词。要激进；多数失败 prose 应删除，不应重写。

Give each meaning a single source of truth: an authoritative location where changes are made in only one place when behavior changes.

Check relevance line by line: Does it still support the skill's function?

Then look for no-ops sentence by sentence. Test each sentence individually for being a no-op; delete the entire sentence if it fails, rather than just trimming words. Be aggressive; most failing prose should be deleted, not rewritten.

Leading words

Leading word 是一个已经存在于模型预训练中的紧凑概念，agent 会在运行 skill 时用它思考（例如 lesson、fog of war、tracer bullets）。它在文本中反复出现，累积 distributed definition，并用最少 tokens 固定一片 behavior。

它从两方面服务 predictability。正文中它锚定 execution；description 中它锚定 invocation。当相同词出现在 prompts、docs 和 codebase 中，agent 更容易把 shared language 连到该 skill。

寻找机会把 skills 重构为使用 leading words。三处重复展开的 triad、花一句话绕一个概念的 description，都可能能 collapse 成一个 token。例如：

"fast, deterministic, low-overhead" -> tight
"a loop you believe in" -> red

你同时赢得更少 tokens 和更尖锐的 thinking hook。

A leading word is a compact concept already present in the model's pre-training, which the agent uses to think while running the skill (e.g., lesson, fog of war, tracer bullets). It repeats in the text, accumulates a distributed definition, and anchors a set of behaviors with minimal tokens.

It serves predictability in two ways. In the main text, it anchors execution; in the description, it anchors invocation. When the same word appears in prompts, docs, and codebase, the agent can more easily connect the shared language to the skill.

Look for opportunities to refactor skills to use leading words. Triads that are expanded three times, descriptions that take a sentence to circle a concept, can potentially collapse into a single token. For example:

"fast, deterministic, low-overhead" -> tight
"a loop you believe in" -> red

You gain both fewer tokens and a sharper thinking hook.

Failure modes

Premature completion - 当前 step 尚未真正完成就结束。防御顺序：先 sharpen completion criterion；只有当 criterion 不可避免地模糊且你观察到 rush 时，才通过拆分隐藏 post-completion steps。
Duplication - 同一 meaning 出现在多个地方。它提高维护成本、浪费 tokens，并夸大该 meaning 在 hierarchy 中的重要性。
Sediment - 因为添加看似安全、删除看似有风险而沉积的 stale layers。
Sprawl - skill 太长，即使每一行都 live 且 unique。用 hierarchy 治疗：把 reference 放到 pointers 后，按 branch 或 sequence 拆分。
No-op - 模型默认就会做的 instruction。测试：它是否改变默认 behavior？弱 leading word（如 be thorough，当 agent 已经大致 thorough）就是 no-op；修法是换更强的词（如 relentless）。

Premature completion - Ending a step before it is truly finished. Defense sequence: First sharpen the completion criterion; only hide post-completion steps by splitting when the criterion is inevitably vague and you observe rushing.
Duplication - The same meaning appears in multiple places. It increases maintenance costs, wastes tokens, and exaggerates the importance of the meaning in the hierarchy.
Sediment - Stale layers accumulated because adding seems safe and deleting seems risky.
Sprawl - The skill is too long, even if every line is live and unique. Treat with hierarchy: Move reference content behind pointers, split by branch or sequence.
No-op - Instructions that the model would do by default. Test: Does it change default behavior? Weak leading words (e.g., be thorough, when the agent is already roughly thorough) are no-ops; fix by replacing with stronger words (e.g., relentless).