skill-progressive-disclosure-design

Skill 渐进式披露设计

每个推荐某种方向的章节都会明确列出优缺点。本技能中的决策属于权衡，而非规则。使用本技能的模型应根据权衡推理，结合用户的具体情况作出判断，而不是盲目套用规则。

先区分触发与披露

在决定是否拆分之前，需要先将两个容易混淆的问题区分开来。

触发指 Claude 是否会调用该技能。这完全由 YAML description 决定。拆分文件不会影响触发。如果问题是“我的技能无法可靠触发”，就不要拆分文件，而应修正描述（使用 skill-creator 技能中的 run_loop.py）。

渐进式披露指技能激活后加载哪些内容。SKILL.md 正文始终会加载。只有在 SKILL.md 告知模型读取某个特定文件时，才会加载 references/*。scripts/* 无需加载到上下文中即可执行。这才是保护上下文的关键。

如果用户因触发问题而询问拆分事宜，先指出这种混淆，再引导用户解决触发问题。

默认做法：不要拆分

除非有充分证据，否则单体 SKILL.md 优于拆分后的版本。

只有在至少满足以下一项时才拆分：

• SKILL.md 超过约 400 行，且内容有自然分支。
• 经验性证据（评估记录）表明模型在不相关章节上浪费上下文。
• 某些内容篇幅较大，且只在特定条件下才需要。

保持单体文件的优点：

• 一次加载全部上下文，无需维护路由说明。
• 无需读取参考文件，不会产生工具调用开销。
• 不存在模型加载错误参考文件或跳过必要参考文件的风险。
• 更易维护：一个文件，一个事实来源。
• 适用于内容高度互相关联、需要全局上下文的情况。
• 方便人工审阅者从头到尾阅读。

保持单体文件的缺点：

• 每次调用都要承担全部 token 开销，即使只有 10% 的内容相关。
• 超过约 500 行后难以扩展，模型查找重要内容的能力会下降。
• 无法限制罕见或小众内容的加载。
• 所有内容都必须证明其始终加载的必要性。
• 文件增长后，维护会变得更困难。

三种有效的拆分维度

1. 变体分支

用户意图会选择且只选择一条路径。SKILL.md 保存决策逻辑和通用工作流。每个 references/<variant>.md 保存特定路径的详细内容。

my-skill/
├── SKILL.md               # decision tree + shared steps
└── references/
    ├── variant-a.md
    ├── variant-b.md
    └── variant-c.md

清晰的变体示例：云服务提供商、数据库引擎、框架选择、输出格式、语言。

优点：

• 每次调用只加载匹配的变体；变体内容较多时可大幅节省上下文。
• 各变体可独立演进，从而简化维护。
• 添加新变体不会让现有内容变得臃肿。
• 心智模型简单：根据输入选择一条路径。
• 与用户意图中已有的变体信息自然对应。

缺点：

• 需要在 SKILL.md 中加入路由逻辑，会抵消部分行数节省。
• 涉及所有变体的更改都要修改每个变体文件，增加工作量。
• 随着时间推移，各变体的处理方式可能逐渐分化。
• 如果用户意图不明确，模型可能加载多个变体，无法节省上下文。
• 如果变体之间有超过约 60% 的内容相同，这种抽象就会失效。

2. 工作流与参考数据

SKILL.md 保存操作流程（动词、顺序、决策）。references/ 保存按键查询的查找材料。

适合作为参考内容的内容：架构、错误代码表、API 接口列表、示例库、配置选项矩阵、设计令牌。

优点：

• 在所有拆分方式中，杠杆效应最高：查找范围小，模型只需读取一个条目。
• 概念边界自然（流程与数据）。
• 参考内容可以扩展得很大，而不影响每次调用的成本。
• 添加新的参考条目无需改动工作流。
• 参考数据通常可以通过机器生成，并重新生成。

缺点：

• 模型必须在读取前知道要查找什么。指针必须明确包含查找键。
• 当工作流需要内联穿插参考数据，而不是在离散节点读取时，这种方式会失效。
• 这会拆分概念上统一的内容，让人类读者更难理解。
• 模型可能会错过仅存在于参考内容中的更广泛背景信息。
• 查找数据较少时（总计不到约 50 行），通常不值得拆分。

3. 深度分层（常见路径与边缘情况）

SKILL.md 覆盖 80% 的情况。references/edge-cases.md 覆盖其余情况。

指针必须写成这样：

如果遇到 X、Y 或 Z，请停止并在继续之前阅读 references/edge-cases.md。

优点：

• 常见路径保持精简、快速、低成本。
• 边缘情况可以详尽覆盖，而不会让每次调用都受到影响。
• 无需改动常见路径，即可轻松扩展边缘情况的覆盖范围。
• 符合专家的工作方式：先处理默认情况，再按需处理例外。

缺点：

• 加载条件必须明确，并且能从用户输入中观察到。大多数边缘情况不符合这一点。
• 条件模糊会导致要么始终加载（浪费），要么从不加载（徒有其名）。
• 由于评估自然会集中在常见查询上，边缘情况得到的测试较少。
• 模型可能会沿着常见路径继续执行，错过应升级处理的时机。
• 对 80/20 的估计常常有误；看似边缘的情况最终可能会变成常见情况。

不起作用的拆分方式

对于每种反模式，“看起来有吸引力的原因”说明设计者为何会采用它；“为什么会失败”说明实际使用中会出现什么问题。

按主题拆分，但调用并不按主题聚类

将测试技能拆分为 unit.md、integration.md、mocks.md 就是一个典型示例。

看起来有吸引力的原因：

• 概念清晰，符合人类组织文档的习惯。
• 维护者容易浏览。
• 看起来可以减少每次调用所需的上下文。

为什么会失败：

• 实际任务会涉及 2-3 个主题，导致每次调用都需要多次加载。
• 跨主题内容会重复或被拆散。
• 节省只是理论上的，并无实际数据支持。

为达到行数目标而拆分，但没有真正的分支条件

看起来有吸引力的原因：

• 一个启发式规则（“将 SKILL.md 控制在 400 行以内”）看起来简单明了，容易遵守。
• 拆分让人感觉是在取得进展。

为什么会失败：

• 没有分支条件时，参考内容会并行加载或始终加载，无法节省任何成本。
• 这会给 SKILL.md 增加路由说明，往往反而让内容总量变得更多。

将罕见但关键的内容放进 references/

看起来有吸引力的原因：

• 内容庞大或专业性强。
• 将其从 SKILL.md 移出，看起来像是良好的整理方式。

为什么会失败：

• 参考内容按设计是可选的，模型可能会跳过。
• 如果内容至关重要，就必须确保可靠加载，也就是说应放在 SKILL.md 中。
• “罕见”和“关键”同时出现，通常说明这个技能承担了两项职责，应拆分为两个技能。

装饰性拆分（Examples、Notes、Tips 文件）

看起来有吸引力的原因：

• 减少 SKILL.md 中的视觉杂乱。
• 感觉组织得更有条理。

为什么会失败：

• 没有加载条件：要么始终加载（浪费工具调用），要么从不加载（内容形同虚设）。
• 暗示了运行时并不存在的重要性层级。
• 经常会让模型看不到它实际需要的内容。

指针规范

当 SKILL.md 指向某个参考资料时，该指针就是完整的加载约定。规则如下：

• 指明触发加载的用户可见信号。“如果用户提到快照测试”，而不是“针对测试相关问题”。
• 每个指针只用一个句子。不要在 SKILL.md 中概述参考资料的内容。
• 在文件名中注明加载条件。用 go126-simd.md，而不是 advanced.md。
• 对于超过 300 行的参考资料，在文件顶部添加目录。
• 如果两份参考资料在大多数运行中都会一起加载，就将它们合并。

严格遵循指针规范的优点：

• 错误加载率会大幅下降。
• 文件名注明加载条件，便于未来的维护者了解用途。
• 促使人们预先明确每份参考资料的适用时机。
• 让架构评估更容易解读。

严格遵循指针规范的缺点：

• 有些内容没有明确的触发条件；规则会迫使人们采用生硬的表述。
• 文件名会变得冗长且别扭。
• 需要保持纪律；随着时间推移，很容易偏离规范。
• 当触发条件确实模糊时，可能会过度限制有用内容的加载。

优先使用 scripts/，而非 references/

对于任何确定性任务（格式化、验证、架构生成、文件转换、正则表达式密集型解析），使用 scripts/ 中的脚本优于在 references/ 中编写说明性内容。

使用脚本而非参考资料说明的优点：

• 执行时不消耗上下文。
• 输出确定且可重复。
• 无需重新阅读即可在多次调用中复用。
• 可以独立进行单元测试。
• 通常比由模型根据说明生成更快。

脚本的缺点：

• 需要运行环境支持执行脚本；并非所有环境都支持。
• 灵活性不如让模型根据说明进行推理。
• 若遇到意料之外的边缘情况，处理起来更困难，除非修改代码。
• 增加维护负担：技能中的代码需要持续保持可用。
• 用户无法轻松自定义行为，除非编辑脚本。
• 失败影响更直接：脚本出错会中断工作流。

决策清单

从 SKILL.md 拆分出任何内容之前，请回答：

1. 这项内容是否有明确、可观察的加载条件，模型能否从用户输入中识别？
2. 考虑到添加到 SKILL.md 中的路由说明，拆分是否真的能减少上下文？
3. 这是参考资料数据（查找）还是流程性内容（步骤）？流程性内容通常应保留原处。
4. 是否可以用脚本确定性地处理？
5. 在真实的调用场景中，有多少比例的运行会加载此文件？低于 20% 时，应内嵌或删除——很少加载的参考资料通常不值得增加路由开销。20–80% 是适合拆分的区间。高于 80% 时，应移入 SKILL.md——路由成本已超过加载所节省的成本。

如果第 1 个问题的答案不明确，就不要拆分。

评估技能架构

架构评估不同于输出评估。输出评估会问“技能是否生成了正确结果？”，架构评估会问“技能是否出于合理原因、以可接受的成本加载了正确文件？”使用相同的测试框架，但指标不同——两者都要运行：输出质量是底线，架构优化则是在此基础上的提升。

运行架构评估的优点：

• 能发现失效的参考资料、SKILL.md 中无效的部分，以及路由错误的内容。
• 能量化拆分是否真正节省了 Token，而不只是看起来更整洁。
• 能揭示直觉无法察觉的实际加载模式。
• 促使评估集覆盖所有声明的路径，从而发现无效路径。
• 与输出评估相结合，能发现这两个维度上的回归问题。

运行架构评估的缺点：

• 需要在标准输出评估之外搭建测试框架。
• 为路径覆盖设计评估集需要投入精力。
• 指标需要按技能校准（阈值会因成本特征而异）。
• 仍然需要输出评估；这会增加总体迭代成本。
• 容易为了优化 Token 成本而牺牲输出质量。

架构评估集设计

输出评估旨在提升对真实查询的输出质量。架构评估旨在覆盖各条路径。评估集必须检验技能声称支持的每条代码路径，否则指标就没有意义。

至少构造以下查询：

• 每个已声明变体对应一个查询（如果技能使用变体分支）。
• 每个边界情况分支对应一个查询（如果存在深度层级分支）。
• 每个主要查找类别对应一个查询（如果存在参考数据分支）。
• 一个只应走常见路径且不加载任何参考资料的查询。
• 2-3 个不相关查询，这些查询不应触发技能（同时也能测试描述）。

如果没有真实查询会触发某个参考文件，该文件就是无用文件。在开始运行任何内容之前，应将其内联或删除。

运行检测

每次评估运行都由加载了该技能的子 Agent 执行。每次运行都要捕获：

1. 完整对话记录，包括每次工具调用。
2. 读取了哪些 references/* 文件（解析技能目录内路径上的 view 调用）。
3. 是否调用了 scripts/*。
4. Token 总数和耗时。
5. 输出（用于并行的输出质量评估）。

将每次运行的数据与标准输出一同保存为 transcript.json 和 loads.json。skill-creator 的运行框架已在 timing.json 中记录 Token 数和耗时；扩展其评分步骤，从对话记录中提取参考资料加载情况。

每个参考文件的指标

对于所有评估运行中的每个 references/*.md：

• 加载率：读取该文件的运行占比。
• 共同加载率：对于其他每个参考文件，同时加载两者的运行占比。
• 加载后的使用率：在加载该文件的运行中，内容是否明显影响了输出（引用了内容、应用了流程、使用了架构）？检查对话记录。
• 重复读取率：同一次运行中重复加载同一文件的比例。

技能整体指标

• 每次调用的 Token 数中位数和 p95，分别统计包含和不包含参考资料的情况。
• SKILL.md 利用率：阅读对话记录，找出模型在任何运行中都未引用的 SKILL.md 章节。这些章节是优先考虑删除的对象。
• 路径覆盖率：每条已声明路径是否至少被一个查询命中？

决策规则

观察结果	操作
参考文件加载率低于 20%	内联到 SKILL.md 或删除——路由开销不值得
参考文件加载率为 20–80%	保持拆分——这是最佳区间，路由的收益值得付出成本
参考文件加载率高于 80%	并入 SKILL.md——始终加载的成本低于路由成本
两个参考文件共同加载率高于 70%	合并为一个文件
加载了参考文件，但输出中未使用	修复或移除 SKILL.md 中的指向
同一次运行中重复读取参考文件	SKILL.md 路由不清晰；应予以明确
没有查询触发某个参考文件	删除该参考文件
某个 SKILL.md 章节在任何运行中都未被引用	删除该章节

这些阈值只是起点。应根据成本情况进行调整：加载成本低的小型参考资料可以容忍较低的加载率，大型资料则不然。

比较两种架构

选择架构时（单体与拆分，或拆分方案 A 与拆分方案 B）：

1. 对两个版本运行完全相同的评估集。
2. 对两个版本都运行输出质量评估。确认没有退步。如果质量下降，无论节省了多少 Token，这种架构变更都得不偿失。
3. 比较每次运行的 Token 数中位数、p95 和耗时中位数。
4. 比较路径覆盖率：每个版本是否都能通过预期路径可靠地得到相同输出？

如果拆分架构节省了 15% 的 Token，却导致输出质量不稳定，就不如单体架构。可靠性胜过效率。

指标无法告诉你的内容

• SKILL.md 中的文字是否清晰。阅读对话记录，查看是否有令人困惑的工具调用和无果的尝试。
• 描述是否能正确触发。这是单独的评估（使用 skill-creator 技能中的 run_loop.py）。
• 内容的放置是否符合用户的心智模型。这是主观判断；请与人工审核者一起评估。

设计时看似清晰的拆分，往往与实际负载模式不符。相信对话记录，而非自己的直觉。

提供建议时

有人询问如何组织某个特定技能时：

1. 先诊断。这是触发问题还是信息披露问题？
2. 在给出建议前，引用现有 SKILL.md 中的相关内容（或用户对其内容的描述）。
3. 提出最小可行拆分。避免拆分成不必要的多个文件。
4. 对每个建议新增的参考文件，写出应放入 SKILL.md 的确切指引句。
5. 明确说明权衡取舍。参照此技能中的优缺点来呈现建议。
6. 如果不确定拆分是否有帮助，建议先添加监测（评估该技能、阅读对话记录），再做决定。