术语表 — 构建优秀 Skill

关于「什么让 skill 变优秀」的领域模型。Skill 的存在，是为了从随机系统中 wrangle 出 determinism；下面每个术语都是作用于该目标的 lever。这是 writing-great-skills 的 disclosed reference。

任意定义中的加粗术语本身也在本术语表中定义；按标题查找即可。

Language

Predictability

Skill 使 agent 在每次运行中以相同 方式 行为的程度——相同的 process，而非相同的 output（头脑风暴类 skill 应 predictably 发散；token 会变，行为不变）。根 virtue，其他每个术语都服务于它——cost 与 maintainability 是其症状，而非对手。

Avoid: consistency, reliability, robustness, output-determinism

Model-Invoked

保留 description 字段的 skill，agent 能看见并自主触发——人类仍可输入名称，因此 model-invocation 始终 包含 user reach。不存在 model-only 状态：description 只会 增加 agent 发现能力，从不剥夺人类的。以每 turn 永久的 context load 换取该 discoverability。可被其他 skill 触及，因为使其 agent-discoverable 的 description 也使其可 invoke。内容全是 reference 的 model-invoked skill 也是 shared reference 的一个 home：另一 skill 可 invoke 它，多个 skill 共需的 reference 只存一处。仅当 agent 必须自主触及时才选 model-invocation；若除手动外从不触发，删掉 description，不付 context load。

Avoid: ability, tool, capability

User-Invoked

description 被剥离的 skill——对 agent 不可见，仅人类输入名称可触及（user-only；model-invoked 是 user-and-agent）。用 agent-discoverability 换取零 context load。因无 description，除人类外 nothing 能触及：无其他 skill 可触发它。

Avoid: procedure, workflow, command

Description

Skill 的机器可读 trigger，也是 model-invoked skill 被迫始终加载的唯一 context pointer。其 mere presence 即 invocation 轴：保留则为 model-invoked（且可被其他 skill 触及）；删除则为 user-invoked，仅人类可触及。Model-invoked skill 的 context load 之源。

Avoid: frontmatter, summary

Context Pointer

Agent context 中持有的 reference，指向 context 外某材料，并编码触及它的条件。description 是顶层 context pointer（context window → skill）；指向 disclosed 文件的 pointer 是同一对象下一层。其 wording，而非 target，决定 agent 何时 触及——以及 多 reliably。must-have target 藏在 weakly worded pointer 之后是 variance bug：先修 wording，仅当 sharpen 失败才 inline 材料。

Avoid: link, reference, import

Context Load

Model-invoked skill 施加于 agent context window 的成本——其 description 始终 loaded，消耗 token 与 attention。User-invoked skill 因无 description 而 escape 的成本，也是拆成更多 model-invoked skill 的 brake。

Avoid: token cost, context bloat

Cognitive Load

User-invoked skill 施加于人类的成本——他们必须在脑中持有：哪些 skill 存在、何时选用（人类即 index）。Model-invocation 以 agent-discoverability 消除的成本，也是拆成更多 user-invoked skill 的 brake。不是应最小化的 cost：它是 human agency 的 price，是部分 skill 保持 user-invoked 的理由。Human judgement 重要处 spend；不重要处 remove。

Avoid: human index, burden, overhead

Granularity

Skill 切多细。切得越细，花费两种 load 之一：更多 model-invoked skill 花费 context load（更多 description 挤占 window、争夺 attention）；更多 user-invoked skill 花费 cognitive load（人类需记住并触发的更多）。两种 cut 指导划分。按 invocation：有 distinct leading word 可触发时拆出 model-invoked skill——prompt 中实际使用的 trigger word。按 sequence：steps 的某段 run 中，某 step 的 post-completion steps 需要隐藏时拆分，因 isolating 于独立 context 会清除后续内容。警惕反向：合并 sequence 会把各 step 的 post-completion steps 暴露给后续，招致 premature completion。

Avoid: chunking, modularity

Router Skill

User-invoked skill，职责是指向你的其他 user-invoked skill——逐一命名及何时选用——让人类只需记住一个 skill 而非许多。只能 hint，不能 fire：user-invoked skill 无 description，除人类外 nothing 能触及。User-invoked skill 增多时 cognitive load 的 cure。

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

Information Hierarchy

Skill 内容按 agent 多 urgently 需要材料排序——单一 ladder，由两种 cut 产生：in-file 或 behind pointer，以及 step 或 reference。Rung：

• Steps — in-file，primary
• Reference，in-file — secondary
• Reference，disclosed — 在 context pointer 之后

无 steps 的 skill 只用下面两层 rung——常为 legitimately flat peer-set（如 review 的每条规则在同一 rung），fine arrangement，不是 smell。Hierarchy 与 invocation 独立：skill 可 model- 或 user-invoked，无论全是 steps、全是 reference，或二者兼有。有 steps 时，本应 disclosed 的 in-file reference 会 bury steps，使 attend 变成 coin-flip——variance lever，不仅是 legibility。保持 ladder 顶部 legible；能 push down 的尽量 push。

Avoid: structure, organization, layout

Co-location

Agent 一次需要的材料放在一处——概念的定义、规则、caveats 在同一 heading 下，而非 scattered——读一处时邻居一并带入。Information Hierarchy 的 within-file companion：hierarchy 排 how far down；co-location 决定到那里后 what sits beside it。Reference 正文无固定 format 公式；test 是 skill 应像为 agent 写的 documentation，grouped material 如此而 scattered 不然。Duplication 不同：后者在两处重复同一 meaning，scattering 把单一 meaning 碎成许多。

Avoid: grouping, clustering, cohesion

Branch

Skill 可被 invoke 的一种 distinct 方式——skill 处理的一种 case——不同 run 走不同 path。多 step 的 skill 可有 many branches；线性 skill 无 branch。

Avoid: path, case, fork

Progressive Disclosure

把 reference 沿 ladder 下移——出 SKILL.md、进 context pointer 之后——使 top 保持 legible。主要不是 token 优化；它是保护 information hierarchy 的方式。Branching 授权：disclose 仅部分 branches 需要的；inline 每条 path 都需要的；pointer 在 must-have 材料上 fire unreliably 时 sharpen wording，仅当失败才 pull back inline。

Avoid: lazy loading, chunking

Steps

Agent 执行的有序动作——有 steps 时是内容 primary tier，也是其在 SKILL.md 中占位的理由。不是每个 skill 都有 steps：可全 steps（tdd）、全 reference（review），或兼有，与 invocation 无关。每 step 以 completion criterion 结束，清晰或模糊。

Avoid: workflow, instructions, choreography

Completion Criterion

告诉 agent 工作单元完成的条件——它 judge 的 target。两属性使其成为 lever，不仅是 quality。Clarity（agent 能否区分 done 与 not-done？）抵抗 premature completion——模糊 bound（「understanding reached」）让 agent declare done 并 slip 到下一步；此轴需要 steps 才 bite，因 premature completion 是 between-steps failure。Demand（要求多高）设定 legwork——「every modified model accounted for」迫使 thorough work，「produce a change list」则否——此轴 不 绑定 step：也可绑定 flat reference body，无 steps 的 skill 仍可 carry exhaustiveness bar（「every rule applied」）。最强 criterion 既 checkable 又 exhaustive。

Avoid: done condition, exit condition, stopping rule

Post-Completion Steps

当前 step 之后的 steps。可见时把 agent 拉向 premature completion——看得越多 tug 越强；defence 是把 step sequence 拆成两段以 hide 它们。

Avoid: horizon, fog of war, lookahead

Legwork

Agent 在单 step 内幕后做的工作——读文件、探索 codebase、改代码、dig 所需而非 offload 给用户。活在 step structure 之下：从不写成独立 step，latent 于 wording，由 agent 控制而非 skill。Across-step pull 的 post-completion steps 在 within-step 的 counterpart。由 leading word（comprehensive、thorough）或要求 exhaustive 的 completion criterion 抬高——含 demand 轴用于 flat reference，即驱动 flat reference skill 覆盖全部 rung 的方式。Demand 缺失或 premature completion 截短 step 时变 thin。

Avoid: scope, effort, diligence, coverage

Reference

Agent 按需查阅的材料——定义、事实、参数、示例、条件指令。有 steps 时为 secondary；无 steps 时为 entire content；或完全活在 skill 外——见 External Reference。经 context pointer 触及，是 progressive disclosure 的首要候选。

Avoid: supporting material, docs, background

External Reference

活在 skill 系统外的 reference——plain file，无 description、无 steps、不可 invoke——任何 skill 可指向。Shared reference 不必自行 fire 时的 home；两个 user-invoked skill 唯一能共用的 shared home，因二者都无 description，彼此不能 fire。

Avoid: doc, resource, knowledge base

Leading Word

Compact concept——亦称 Leitwort——已活在 model pretraining 中，agent 运行 skill 时用它思考。用最少 token 编码 behavioural principle，invoke 模型已有 priors（如 lesson、proximal zone of development、fog of war、tracer bullets）。作为 token 重复，从不作为句子，积累 distributed definition，anchor 整片行为。自造词可行若定义清晰，但 made-up word 不 recruit priors——你付 definition token，pretrained word 免费给。优先 reach 已有词。

Leading word twice 服务 predictability。Body 中 anchor execution——概念出现时 agent 每次 reach 同一行为；flat reference 内聚焦 attention 于某类 thing to look for，每 run recruit 正确 checks。在 description 中 anchor invocation——且不限于 skill 内：同一词 living 于 prompts、docs、codebase 时，agent 将 shared language 链到 skill，更 reliably fire。Description 用你实际 prompt 时的 leading words。

Avoid: keyword, term, motif

Single Source of Truth

每种 meaning 恰在一处 authoritative 的 desired state，改 skill 行为只需改一处。Duplication 是其 violation。

Avoid: home, canonical location

Relevance

一行是否仍 bear on skill 做什么——保留内容的 lens。一行失去 relevance 或因从不 bear on task（mere exposition，或应 disclosed 的 branch），或因 stale：所描述行为或世界变化而 drift out of date。更短 skill 更易保持 relevant，因每行 cheaper to check。与 no-op 不同：relevance 问一行是否 bear on task，而非是否改变行为。

Avoid: load-bearing, staleness, freshness

Failure Modes

Premature Completion

当前 step 未 genuinely done 就结束，因 agent attention slip 到 being done 而非 work。Between-steps failure：需要 steps 才发生——无 steps 的 skill 早退不是 premature completion，而是 unmet demand 下 thin legwork。两力 tug-of-war：可见 post-completion steps（pull forward）与 completion criterion 的 clarity（resistance——sharp、checkable bar 顶住；vague 让路）。Fuzziness 是必要条件：sharp bound 无论后续多少 step 可见都 resist pull，故从不 rush 的 step 无需 defend。会 rush 的 step 有两 lever，但按序 reach：先 sharpen bound——local 且 cheap。仅当 criterion irreducibly fuzzy 且 实际观察到 rush 时 hide later steps——且 hiding 仅跨 real context boundary 有效（user-invoked hand-off 或 subagent dispatch；inline model-invoked call 仍把 later steps 留在 context，clear nothing）。Thin legwork 的一因，但与之 distinct：step 跑满 completion 时 legwork 仍可能 thin。

Avoid: premature closure, the rush, rushing, shortcutting

Duplication

同一 meaning 多于一处 single source of truth。Cost maintenance（改一处须改其他）、cost tokens，inflate prominence——重复 meaning 在 ladder 上 weight 超过 real rank。Accidental inverse of leading word，后者故意重复 token 抬高 attention，从不重复 meaning。

Avoid: repetition, redundancy

Sediment

旧 content 层 settle 于 skill 且从不 clear——adding feels safe、removing feels risky——stale 与 irrelevant 行 accumulate，须 core down 才找 live 内容。无 pruning discipline 的 skill 的 default fate；relevance 的 slow erosion，与 duplication 的 repeated meaning 相对。

Avoid: accretion, bloat, cruft, rot

Sprawl

Skill simply 太长——SKILL.md 行数过多——与是否 stale 或 repeated 无关。全 live、全 unique 仍可 sprawl。Cost readability（agent wade 更久才能 act，attention 在 excess 上 thin）、maintainability（每多一行须保持 relevant）、tokens。Cure 是 information hierarchy：把 reference push down 到 context pointer 后，按 branch 或 sequence 拆分，使每条 path 只 carry 所需。与 sediment（stale accumulation 致长）和 duplication（repeated meaning 致长）不同——sprawl 是 length 本身，无论 cause。

Avoid: bloat, length, size, verbosity

No-Op

因 model 默认已做而改变 nothing 的 instruction——你付 load 告诉 agent 它本来就会做的。Test：一行相对 default 是否改变行为？一行可 perfectly relevant 仍是 no-op。使 leading word free 的 priors 使 no-op worthless。

Leading word 是 technique；No-Op 是对一行的 verdict——二者交叉。Beat 不了 default 的 weak leading word 是 no-op（agent 已 thorough-ish 时的 be thorough）；fix 是通过 verdict 的 stronger word（relentless），非换 technique。故 No-Op test——相对 default 是否改变行为？——也是 grading leading word 是否 earning repetitions 的方式。Model-relative，非 reader-relative：两人对一行是否 no-op 分歧即对 default 分歧，靠 run skill 而非 debate settle。

Avoid: redundant instruction, restating the obvious, belaboring