← 技能图谱 · 术语表

name	writing-great-skills
description	Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.
触发词	编写与精修技能的参考——使技能具备可预测性的词汇与原则。
disable-model-invocation	true

writing-great-skills

Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.

A skill exists to wrangle determinism out of a stochastic system. Predictability — the agent taking the same process every run, not producing the same output — is the root virtue; every lever below serves it.

技能的存在，是为了从随机系统中驯服出确定性。可预测性——代理每次运行走相同的过程，而非产出相同的输出——是根本美德；下文每一个杠杆都服务于它。

Bold terms are defined in GLOSSARY.md; look them up there for the full meaning.

粗体术语在 GLOSSARY.md 中定义；请到该处查阅完整含义。

Invocation

Two choices, trading different costs:

调用方式

两种选择，各付不同的代价：

A model-invoked skill keeps a description, so the agent can fire it autonomously and other skills can reach it (you can still type its name too). It contributes to context load — the description sits in the window every turn. Mechanics: omit disable-model-invocation, and write a model-facing description with rich trigger phrasing ("Use when the user wants…, mentions…").
A user-invoked skill strips the description from the agent's reach: only you, typing its name, can invoke it — and no other skill can. Zero context load, but it spends cognitive load: you are the index that must remember it exists. Mechanics: set disable-model-invocation: true; the description becomes human-facing — a one-line summary, trigger lists stripped.

模型调用技能保留 description，这样代理可以自主触发它，并且其他技能也能触达它（你仍然可以直接输入它的名字）。它计入上下文负载——description 每轮都留在窗口里。机制：省略 disable-model-invocation，编写面向模型的 description，包含丰富的触发措辞（"当用户想要……、提到……时使用"）。
用户调用技能将 description 从代理的视野中剥离：只有你输入它的名字才能调用它——其他技能做不到。零上下文负载，但消耗认知负载：你自己必须充当索引来记住它的存在。机制：设置 disable-model-invocation: true；description 变为面向人类——一行摘要，去掉触发词列表。

Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.

只有在代理需要自主触达该技能，或其他技能需要触达它时，才选择模型调用。如果它永远只靠手动触发，就做成用户调用，不用付上下文负载。

When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a router skill: one user-invoked skill that names the others and when to reach for each.

当用户调用技能多到你记不住时，累积的认知负载可以通过一个路由器技能来解决：一个用户调用技能，列出其他技能以及何时使用每一个。

Writing the description

A model-invoked description does two jobs — state what the skill is, and list the branches that should trigger it. Every word increases context load, so a description earns even harder pruning than the body:

编写 description

模型调用的description 承担两项工作——说明技能是什么，以及列出应触发它的分支。每个词都增加上下文负载，因此 description 比正文更需要严格修剪：

Front-load the skill's leading word — the description is where it does its invocation work.
One trigger per branch. Synonyms that rename a single branch are duplication — "build features using TDD … asks for test-first development" is one branch written twice. Collapse them; keep only genuinely distinct branches.
Cut identity that's already in the body. Keep the description to triggers, plus any "when another skill needs…" reach clause.

把技能的前导词放在最前面——description 是它发挥调用作用的地方。
每个分支一个触发词。同一个分支换说法的同义词就是重复——"用 TDD 构建功能……要求测试优先开发"是把一个分支写了两次。合并它们；只保留真正不同的分支。
删掉正文中已有的身份信息。description 只保留触发词，加上任何"当其他技能需要……"的触达子句。

Information hierarchy

A skill is built from two content types — steps and reference — that mix freely: a skill can be all steps, all reference, or both. The core decision is which to use and where each sits on the information hierarchy, a ladder ranked by how immediately the agent needs the material:

信息层级

技能由两种内容类型构建——步骤和参考——可自由混合：技能可以全是步骤、全是参考，或兼而有之。核心决策是使用哪种类型，以及每种类型在信息层级上的位置——一个按代理对材料需求的紧迫程度排列的阶梯：

In-skill step — an ordered action in SKILL.md, the primary tier: what the agent does, in order. Each step ends on a completion criterion, the condition that tells the agent the work is done. Make it checkable (can the agent tell done from not-done?) and, where it matters, exhaustive ("every modified model accounted for", not "produce a change list") — a vague criterion invites premature completion.
In-skill reference — a definition, rule, or fact in SKILL.md, consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell. This skill is all reference.
External reference — reference pushed out of SKILL.md into a separate file, reached by a context pointer, loaded only when the pointer fires. (Spans disclosed reference — a sibling file like GLOSSARY.md, still part of the skill — through fully external reference that lives outside the skill system and any skill can point at.)

技能内步骤——SKILL.md 中的有序操作，主要层级：代理按顺序执行的动作。每个步骤以完成标准结束，即告诉代理工作已完成的条件。使其可检查（代理能否区分完成与未完成？）并在需要时穷尽（"每个修改过的模型都已计入"，而非"生成变更列表"）——模糊的标准会招致过早完成。
技能内参考——SKILL.md 中按需查阅的定义、规则或事实。通常是合理的扁平对等集合（审查的每条规则在同一层级上）——这是很好的安排，不是坏味道。本技能全是参考。
外部参考——从 SKILL.md 推入单独文件的参考，通过上下文指针触达，仅在指针触发时加载。（涵盖已披露的参考——如 GLOSSARY.md 这样的同级文件，仍属于技能——直到完全的外部参考，即存在于技能系统之外、任何技能均可指向的文件。）

A demanding completion criterion drives thorough legwork — the digging the agent does within the work — whether the skill has steps or not, since "every rule applied" binds flat reference just as "every step done" binds a sequence.

要求严格的完成标准驱动彻底的基础工作——代理在工作中进行的深度挖掘——无论技能是否有步骤，因为"每条规则都已应用"约束扁平参考，正如"每个步骤都已完成"约束序列。

Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.

向下推得太少，顶层就会臃肿；推得太多，又会把代理真正需要的材料藏起来。这种张力就是整个决策的核心。

Progressive disclosure is the move down the ladder — out of SKILL.md into a linked file — so the top stays legible. Mechanics: a linked .md file in the skill folder, named for what it holds (this skill discloses its full definitions to GLOSSARY.md). Some skills are used in more than one way, and each distinct way is a branch — different runs taking different paths through the skill. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. A context pointer's wording, not its target, decides when and how reliably the agent reaches the material.

渐进式披露是沿阶梯向下移动——从 SKILL.md 移入一个链接文件——以保持顶层可读。机制：在技能文件夹中放一个链接的 .md 文件，以其内容命名（本技能将完整定义披露到 GLOSSARY.md）。有些技能有多种使用方式，每种不同的方式是一个分支——不同的运行在技能中走不同的路径。分支是最清晰的披露测试：内联每个分支都需要的内容，将只有部分分支触及的内容推到指针后面。上下文指针的措辞，而非其目标，决定了代理何时以及多可靠地触达材料。

Where the ladder decides how far down a piece sits, co-location decides what sits beside it once there: keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it.

阶梯决定一段内容放在多深，共置则决定它到了那里之后与什么相邻：将概念的定义、规则和注意事项放在同一标题下，而非分散各处，这样阅读一部分就能连带看到邻近内容。

When to split

Granularity is how finely you divide skills, and each cut spends one of the two loads, so split only when the cut earns it. Two cuts:

何时拆分

粒度是你划分技能的精细程度，每次切分都会消耗两种负载之一，因此只有在切分物有所值时才能进行。两种切分方式：

By invocation — split off a model-invoked skill when you have a distinct leading word that should trigger it on its own, or another skill must reach it. You pay context load for the new always-loaded description, so that independent reach has to be worth it.
By sequence — split a run of steps when the steps still ahead (a step's post-completion steps) tempt the agent to rush the one in front of it (premature completion). Keeping them out of view encourages the agent to do more legwork on the current task.

按调用方式拆分——当你有一个独特的前导词可以独立触发某个技能，或另一个技能需要触达它时，拆分出一个模型调用技能。你需要为新的始终加载的 description 付出上下文负载，所以这种独立触达必须值得。
按序列拆分——当后面的步骤（某步骤的完成后步骤）诱使代理匆忙完成当前步骤（过早完成）时，拆分一系列步骤。将后续步骤隐藏起来，鼓励代理对当前任务做更多的基础工作。

Pruning

Keep each meaning in a single source of truth: one authoritative place, so changing the behaviour is a one-place edit.

修剪

将每个含义保存在单一真相源中：一个权威位置，这样改变行为只需改一处。

Check every line for relevance: does it still bear on what the skill does?

检查每一行的相关性：它是否仍然与技能的功能有关？

Then hunt no-ops sentence by sentence, not just line by line: run the no-op test on each sentence in isolation, and when one fails, delete the whole sentence rather than trim words from it. Be aggressive — most prose that fails should go, not be rewritten.

然后逐句排查无操作，而非仅仅逐行：对每个句子单独进行无操作测试，当某一句未通过时，删除整个句子而非删减其中的词语。要激进——大多数未通过的文句应该直接删掉，而非改写。

Leading words

A leading word is a compact concept already living in the model's pretraining that the agent thinks with while running the skill (e.g. lesson, fog of war, tracer bullets). Repeated throughout the text (though not necessarily - a strong leading word might only be needed once), it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds.

前导词

前导词是已经存在于模型预训练中的紧凑概念，代理在运行技能时用它来思考（例如 lesson、fog of war、tracer bullets）。它在整个文本中重复出现（虽然不一定——一个强前导词可能只需出现一次即可），通过招募模型已有的先验，用最少的 token 积累分布式定义，锚定整个行为区域。

It serves predictability twice. In the body it anchors execution: the agent reaches for the same behaviour every time the word appears. In the description it anchors invocation: when the same word lives in your prompts, docs, and code, the agent links that shared language to the skill and fires it more reliably.

它以两种方式服务于可预测性。在正文中，它锚定执行：代理每次看到该词都会采取相同的行为。在 description 中，它锚定调用：当同一个词出现在你的提示词、文档和代码中时，代理将这种共享语言与技能关联起来，更可靠地触发它。

Hunt for opportunities to refactor skills to use leading words. A triad spelled out at three sites (duplication), a description spending a sentence to gesture at one idea — each is a passage begging to collapse into a single token. Examples include:

寻找机会重构技能以使用前导词。在三处展开的三元组（重复），用一句话指向一个概念的 description——每段都渴望压缩成单个 token。示例包括：

"fast, deterministic, low-overhead" -> tight — one quality restated across a phase — into a single pretrained word (a tight loop).
"a loop you believe in" -> red — converts a fuzzy gate into a binary observable state (the loop goes red on the bug, or it doesn't).

"fast, deterministic, low-overhead" → tight——一个在阶段中反复重述的品质——压缩成单个预训练词（一个紧凑的循环）。
"a loop you believe in" → red——将模糊的门控转化为二进制的可观察状态（循环遇到 bug 变红，或者不变）。

You win twice over: fewer tokens, and a sharper hook for the agent to hang its thinking on. Assume every skill is carrying restatements that leading words retire — go find them.

你赢得双重收获：更少的 token，以及更锐利的钩子让代理挂住思维。假设每个技能都带着前导词可以淘汰的重述——去找到它们。

Failure modes

Use these to diagnose issues the user may be having with the skill.

失败模式

用这些来诊断用户在技能使用中可能遇到的问题。

Premature completion — ending a step before it's genuinely done, attention slipping to being done. Defence, in order: sharpen the completion criterion first (cheap, local); only if it is irreducibly fuzzy and you observe the rush, hide the post-completion steps by splitting (the sequence cut).
Duplication — the same meaning in more than one place. Costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank.
Sediment — stale layers that settle because adding feels safe and removing feels risky. The default fate of any skill without a pruning discipline.
Sprawl — a skill simply too long, even when every line is live and unique. Hurts readability and maintainability and wastes tokens. The cure is the ladder: disclose reference behind pointers, and split by branch or sequence so each path carries only what it needs.
No-op — a line the model already obeys by default, so you pay load to say nothing. The test: does it change behaviour versus the default? A weak leading word (be thorough when the agent is already thorough-ish) is a no-op; the fix is a stronger word (relentless), not a different technique.
Negation — steering by prohibition backfires: don't think of an elephant names the elephant and makes it more available, not less. Prompt the positive — state the target behaviour so the banned one is never spoken; keep a prohibition only as a hard guardrail you can't phrase positively, and even then pair it with what to do instead.

过早完成——在步骤真正完成前就结束，注意力滑向已完成的状态。防御方式，按顺序：先锐化完成标准（便宜、局部）；只有当标准不可约地模糊且你确实观察到匆忙时，才通过拆分来隐藏完成后步骤（序列切分）。
重复——同一个含义出现在多个地方。消耗维护成本和 token，并在层级上将含义的突出度膨胀到超过其真实排名。
沉淀——陈旧的层次因为添加感觉安全、删除感觉冒险而不断沉积。任何缺乏修剪纪律的技能都难逃此命运。
蔓延——技能单纯太长，即使每一行都活跃且独特。损害可读性和可维护性，浪费 token。治愈方法是阶梯：将参考披露到指针后面，按分支或序列拆分，使每条路径只携带所需内容。
无操作——模型默认已经遵守的行，你付出负载却什么也没说。测试方法：它是否改变了与默认行为相比的行为？弱前导词（代理已经够彻底时还说be thorough）就是无操作；修复方法是更强的词（relentless），而非不同的技术。
否定式指令——用禁止来引导适得其反：不要想大象提起了大象，反而让它更易被联想到。应当提示正向行为——说出目标行为，让被禁止的行为根本不被提及；只在无法正面表述的硬边界上使用禁止，而且即使如此也要同时说明应该做什么。