一句话
Skill 的存在理由：从随机系统里拧出确定性。根美德 predictability——
每次运行走同一个过程，不是产出同一个输出。
每个术语都是它的一根杠杆；成本和可维护性是症状，不是对手。
本 skill 全 reference、无 steps、user-invoked、什么都不写——纯案头参考书。
何时伸手
- 写新 skill：定调用方式 → 写 description → 摆内容层级 → 决定拆不拆
- 改旧 skill：当检查单用（SSOT / relevance / no-op 三查）
- 诊断 skill：行为不对 → 对号六个失败模式 → 拿对应杠杆
- 别去：改项目领域术语 →
domain-modeling；不知走哪条 flow → ask-matt
调用轴：两种 load
| Model-invoked | User-invoked |
|---|
| 谁能触发 | agent 自动 + 别的 skill prose 调用 + 人打字（无 model-only 态） | 只有人打字；无其它任何调用方 |
| 付账 | Context load：description 每轮常驻窗口，花 token + 注意力 | Cognitive load：人是索引，自己记它存在（human agency 的价钱，不求最小化） |
| description | 面向模型，带触发语「Use when…」 | 面向人，一行摘要，剥掉触发列表 |
| 机制 | 默认（无 disable 标记） | disable-model-invocation: true + openai.yaml allow_implicit_invocation: false，两份同步 |
选择规则：只在「agent 必须自己够到它、或另一个 skill 必须够到它」时选 model-invoked。
Router skill：user-invoked 多到记不住时的解药；只能 hint 不能 fire（活例：ask-matt）。
description 三规矩
- Front-load the leading word——领头词顶到最前，它在 description 里干 invocation 的活
- One trigger per branch——同义说法写两遍 = duplication；只留真正不同的分支
- Cut body identity——只留触发语 + 「when another skill needs…」reach 条款
信息层级（三级梯子）
1. In-skill step 主层；每步以 completion criterion 收尾
2. In-skill reference 按需查阅；平铺同侪集合是合法布局（本 skill 全在这层）
3. External reference 压在 context pointer 后面，触发才加载
disclosed（sibling 如 GLOSSARY.md）→ external（skill 系统外的普通文件）
- Completion criterion：checkable（分得清 done / not-done）+ exhaustive（「every X accounted for」，不是「produce a list」）；模糊判据邀请 premature completion
- Legwork：步内的暗中挖掘；由 demanding 判据驱动，有没有 steps 都生效；永远不是独立一步
- Progressive disclosure：挪 reference 下梯子让顶部可读；branch 是最干净的披露测试（每条 branch 都要的 inline，部分才走的披露）
- Context pointer：措辞（不是目标）决定何时、多可靠够到；必达材料够不到 = variance bug，先磨措辞再考虑 inline 回来
- Co-location：定义 + 规则 + 注意事项收在同一标题下；梯子管压多深，co-location 管旁边住谁；≠ duplication（一个意思重复两处）也 ≠ scatter（一个意思碎很多处）
拆分两种切法（granularity）
- By invocation：有独立 leading word 该自己触发，或别的 skill 必须够到 → 拆 model-invoked；付新 description 的常驻 context load
- By sequence：post-completion steps 诱惑赶当前步 → 拆出去藏；付一次真实上下文边界（新会话 / subagent）
- 反向警告：合并序列会暴露 post-completion steps，招来 premature completion
Leading word
- 已活在预训练里的紧凑概念（Leitwort）；作为 token 重复，不作为句子解释；分布式定义锚定整片行为
- 双倍服务：正文锚 execution；description 锚 invocation（同一词住在 prompt / docs / code 里触发更可靠）
- 自造词招募不到先验，定义 token 自己掏；先找现成词
- 猎捕：三处复述的三元组、一句话比划一个想法 → collapse 成单 token（tight / red / tracer bullets / fog of war / lesson）
- 弱 leading word = no-op（be thorough）；修法是更强的词（relentless），不是换技术
修剪三查（按顺序）
- SSOT：每个意思住一个权威地点，改行为 = 一处编辑
- Relevance：逐行问「还和 skill 干的事有关吗」；无关分从未相关和过时两种
- No-op 测试：逐句问「相对默认行为改了什么」；过不了整句删，不修词；要狠。争议是 model-relative 的——跑一遍 skill 解决，别辩论
失败模式 → 杠杆（诊断主表）
| 失败模式 | 症状 | 杠杆 |
|---|
| Premature completion | 步没做完就收，注意力滑向「做完」 | ① 先磨 completion criterion（cheap, local）② 仅当判据不可约模糊 + 真观察到赶工，才按序列拆藏后续；藏只跨真实上下文边界有效（user-invoked 交接 / subagent；inline model-invoked 调用不算） |
| Duplication | 同一意思住两处 | 合并 SSOT；leading word 重复 token 不算重复意思 |
| Sediment | 旧层堆积：加感觉安全，删感觉危险 | 修剪纪律；relevance 逐行查 |
| Sprawl | 全活全独特但就是太长 | 披露 reference 下梯子；按 branch / 序列拆 |
| No-op | 写了模型默认就会做的事 | 逐句测，整句删；注意：一行可 relevant 但仍 no-op |
| Negation | 「不要 X」把 X 点名叫醒（大象） | Prompt the positive：说目标行为；硬护栏才留禁止，且配对「那该怎么做」 |
判别：无 steps 的 skill 早早收工 ≠ premature completion，是 thin legwork（判据 demand 没吃够）。
长度三病因先分清再治：sediment（过时）/ duplication（重复）/ sprawl（长度本身）。
词汇速记（按轴分组）
- Invocation 轴
- Model-Invoked / User-Invoked · Description（存在即调用轴）· Context Load（agent 侧每轮账）· Cognitive Load（人脑索引账）· Router Skill（只 hint 不 fire）· Granularity（每刀花一种 load）
- Information Hierarchy 轴
- Steps（主层）· Reference（按需查阅）· External Reference（disclosed → external；两个 user-invoked skill 共享材料的唯一方式）· Progressive Disclosure · Context Pointer（措辞定时机）· Co-location · Sprawl（failure）
- Steering 轴
- Branch（一种用法一条路径）· Leading Word（预训练先验 token）· Completion Criterion（checkable + demand）· Legwork（步内暗挖）· Post-Completion Steps（前拽力）· Premature Completion（failure）· Negation（failure，大象）
- Pruning 轴
- Single Source of Truth · Duplication（failure）· Relevance · Sediment（failure）· No-Op（failure，逐句删）
本仓库改 skill 后的同步链（AGENTS.md）
.claude-plugin/plugin.json 的 skills 数组（已发布集合的唯一权威）- 顶层 + bucket
README.md 条目（按 User / Model 分组，链到 SKILL.md）
docs/<bucket>/<skill>.md 文档页（按 .agents/writing-docs.md 同步）ask-matt 路由（user-reachable skill 变动必更新——路由器不许说谎）- 重跑
scripts/link-skills.sh；碰 manifest 后 claude plugin validate . --strict
副作用 / 下一步
本 skill 自己什么都不写（纯参考）；编辑都落在目标 skill 的
SKILL.md 正文、frontmatter description、sibling 披露文件、agents/openai.yaml 上。
用完接：当检查单改目标 skill → 走上面的同步链 → 不确定哪个 skill 负责就 /ask-matt。