Skill 的存在，是为了从随机系统中 wrangle 出 determinism。Predictability——agent 每次运行走同一 process，而非产出同一 output——是根 virtue；下面每个 lever 都服务于它。
加粗术语在 GLOSSARY.zh-CN.md 中定义；查那里获取完整含义。
Invocation
两种选择，trade 不同成本：
- Model-invoked skill 保留 description，agent 可自主触发 且 其他 skill 可触及（你仍可输入名称）。它贡献 context load——description 每 turn 都在窗口里。机制：省略
disable-model-invocation，写面向模型的 description，含丰富触发措辞（「Use when the user wants…, mentions…」）。 - User-invoked skill 将 description 从 agent 触及范围剥离：只有你输入名称才能调用——其他 skill 不能。零 context load，但花费 cognitive load：你 是必须记住它存在的 index。机制：设置
disable-model-invocation: true；description面向人类——一行摘要，去掉 trigger 列表。
仅当 agent 必须自主触及 skill，或另一 skill 必须触及时，才选 model-invocation。若它只用手动触发，做成 user-invoked，不付 context load。
当 user-invoked skill 多到记不住时， piled-up cognitive load 由 router skill 治愈：一个 user-invoked skill 列出其他 skill 及何时选用。
Writing the description
Model-invoked 的 description 做两件事——说明 skill 是什么，并列出应触发它的 branches。每个词都增加 context load，因此 description 比正文更需要 prune：
- Front-load skill 的 leading word——description 是它做 invocation 工作的地方。
- 每个 branch 一个 trigger。 给同一 branch 改名的同义词是 duplication——「build features using TDD … asks for test-first development」是一个 branch 写了两遍。合并；只保留真正 distinct 的 branches。
- 砍掉 body 里已有的 identity。 Description 只保留 triggers，以及任何「when another skill needs…」 reach 子句。
Information hierarchy
Skill 由两种内容类型构成——steps 与 reference——可自由混合：skill 可以全是 steps、全是 reference，或二者兼有。核心决策是用哪种、每种在 information hierarchy 上占哪一层——按 agent 多 urgently 需要材料排序的 ladder：
- In-skill step——
SKILL.md中的有序动作，primary tier：agent 按序做什么。每步以 completion criterion 结束——告诉 agent 工作完成的条件。要 checkable（agent 能否区分 done 与 not-done？）并在重要处 exhaustive（「every modified model accounted for」，而非「produce a change list」）——模糊 criterion 招致 premature completion。 - In-skill reference——
SKILL.md中的定义、规则或事实，按需查阅。常常是 legitimately flat peer-set（review 的每条规则在同一 rung）——fine arrangement，不是 smell。本 skill 全是 reference。 - External reference——reference 推出
SKILL.md到单独文件，经 context pointer 触及，仅在 pointer 触发时加载。（跨度从 disclosed reference——如GLOSSARY.md的 sibling 文件，仍是 skill 一部分——到完全 external reference，活在 skill 系统外，任何 skill 可指向。）
苛刻的 completion criterion 驱动 thorough legwork——工作内的 digging——无论 skill 有无 steps，因为「every rule applied」绑定 flat reference，如同「every step done」绑定 sequence。
Push 太少则 top 膨胀；push 太多则隐藏 agent 实际需要的材料。这 tension 就是整个决策。
Progressive disclosure 是沿 ladder 下移——出 SKILL.md 进 linked file——让 top 保持 legible。机制：skill 文件夹内 linked .md，按内容命名（本 skill 将完整定义 disclose 到 GLOSSARY.md）。有些 skill 有多种用法，每种 distinct 方式是一个 branch——不同 run 走 skill 内不同 path。Branching 是最 clean 的 disclosure 测试：inline 每个 branch 都需要的；pointer 后 push 仅部分 branches 触及的。Context pointer 的 wording，而非 target，决定 agent 何时、多 reliably 触及材料。
Ladder 决定 how far down；co-location 决定到那里后 what sits beside it：概念的定义、规则、caveats 放在同一 heading 下，而非 scattered，读一处时邻居一并带入。
When to split
Granularity 是 skill 切多细；每切一刀花费两种 load 之一，因此只有 cut 值得时才 split。两种 cut：
- By invocation——当有 distinct leading word 应独立触发，或另一 skill 必须触及时，拆出 model-invoked skill。你为新的 always-loaded description 付 context load，因此 independent reach 必须值得。
- By sequence——当后续 steps（某 step 的 post-completion steps）诱使 agent rush 当前步（premature completion）时，拆分 step run。把它们移出视野鼓励 agent 在当前 task 做更多 legwork。
Pruning
每个 meaning 保持 single source of truth：一处 authoritative，改行为只需改一处。
逐行检查 relevance：它是否仍 bear on skill 做什么？
然后 hunt no-ops，逐句而非逐行：对每句单独跑 no-op test，失败则删整句而非 trim 词。要 aggressive——多数失败的 prose 应删，而非 rewrite。
Leading words
Leading word 是 model pretraining 中已有的 compact concept，agent 运行 skill 时用它思考（如 lesson、fog of war、tracer bullets）。全文重复（不必处处——强 leading word 可能只需一次），它积累 distributed definition，用最少 token anchor 整片行为，recruit 模型已有的 priors。
它 twice 服务 predictability。Body 中 anchor execution：词出现时 agent 每次 reach 同一行为。Description 中 anchor invocation：同一词 living 于 prompts、docs、code 时，agent 将 shared language 链到 skill，更 reliably 触发。
Hunt 用 leading words refactor skill 的机会。三处 spell out 的 triad（duplication）、description 用一句 gesture 一个 idea——每段都在 beg collapse 成 single token。例如：
- "fast, deterministic, low-overhead" -> tight——一 quality 跨 phase restate——into single pretrained word（tight loop）。
- "a loop you believe in" -> red——将 fuzzy gate 转为 binary observable state（loop 在 bug 上 red，否则不）。
你 win twice：更少 token，且 sharper hook 供 agent hang thinking。Assume 每个 skill 都 carrying restatements，leading words 可 retire——去找它们。
Failure modes
用于诊断用户可能遇到的 skill 问题。
- Premature completion——step 未 genuinely done 就结束，attention slip 到 being done。Defence，按序：先 sharpen completion criterion（cheap、local）；仅当 irreducibly fuzzy 且 观察到 rush 时，hide post-completion steps by splitting（sequence cut）。
- Duplication——同一 meaning 多于一处。Cost maintenance 与 tokens，并将 meaning prominence 在 ladder 上 inflate 超过 real rank。
- Sediment——stale layers 因 adding feels safe、removing feels risky 而 settle。任何无 pruning discipline 的 skill 的 default fate。
- Sprawl——skill simply 太长，即使每行 live 且 unique。hurt readability、maintainability，浪费 tokens。Cure 是 ladder：disclose reference 到 pointers 后，按 branch 或 sequence split，使每条 path 只 carry 所需。
- No-op——模型默认已 obey 的行，付 load 说 nothing。Test：相对 default 是否改变行为？弱 leading word（agent 已 thorough-ish 时的 be thorough）是 no-op；fix 是更强词（relentless），非不同 technique。