Skill Progressive Disclosure Design — 技能进阶式揭示设计（Progressive Disclosure Design）

技能渐进披露设计 每个推荐方向的部分都包含明确的优缺点。该技能中的决策是权衡，而不是规则。使用此技能的模型应根据用户的具体情况从权衡中推理，而不是盲目应用规则。 触发与披露：首先分离这两者 两个问题混淆在一起，需要在做出任何拆分决定之前分离。触发是指 Claude 是否调用该技能。完全由 YAML 描述驱动。文件拆分不会影响触发。如果问题是“我的技能不能可靠地触发”，则不应拆分文件，而应修复描述（使用 skill-creator 技能中的 run_loop.py）。 渐进披露是指技能激活后加载的内容。SKILL.md 正文始终加载。references/ 只在 SKILL.md 指示模型读取特定文件时加载。scripts/ 执行时不会加载到上下文中。这就是上下文保护发生的地方。如果用户询问拆分文件是由于触发问题，首先要澄清混淆并重定向。 默认：不拆分 单一的 SKILL.md 文件优于拆分的文件，除非有证据证明拆分是必要的。只有当以下至少一项为真时才拆分：SKILL.md 文件超过约 400 行，内容有自然的分支。实证证据（评估记录）显示模型在不相关的部分上浪费了上下文。特定的内容很大，只在特定条件下需要。 保持单一文件的优点：单一上下文加载，无需维护路由文本。无需从读取 references 中加载工具调用。无需模型加载错误参考或跳过所需参考的风险。更容易维护：一个文件，一个真实来源。适合内容紧密相连且上下文是全局的。更容易让人类审查者从头到尾阅读。 保持单一文件的缺点：每次调用都支付完整的令牌成本，即使只使用 10% 的内容。超过约 500 行时，模型的能力会下降。没有机制来控制罕见或小众内容。所有内容都必须证明其始终加载的状态。维护变得更加困难，因为文件的增长。 三个有效的拆分轴

• 变体分支

用户意图选择一个路径。SKILL.md 包含决策逻辑和共享工作流。每个 references/<变体>.md 文件包含特定路径的详细信息。 my-skill/ ├── SKILL.md # 决策树 + 共享步骤 └── references/ ├── variant-a.md ├── variant-b.md └── variant-c.md 清晰变体的例子：云提供商、数据库引擎、框架选择、输出格式、语言。 优点：每次调用只加载匹配的变体；当变体很大时可以节省大量成本。变体可以独立演化，简化维护。添加新变体不会使现有内容变得臃肿。心理模型很简单：根据输入选择一个路径。清晰地映射到用户意图，该意图已经提到了变体。 缺点：需要在 SKILL.md 中包含路由逻辑，这会消耗一些行数的节省。跨越多个变体的更改会增加工作量。随着时间的推移，变体之间的处理可能会有所不同。如果用户意图不明确，模型可能会加载多个变体并失去节省。

• 工作流与参考数据

SKILL.md 包含程序（动词、序列、决策）。references/ 包含通过键查询的查找材料。 良好的参考内容：模式、错误代码表、API 表面列表、示例库、配置选项矩阵、设计令牌。 优点：所有拆分中最高的杠杆：查找很窄，模型只读取一个条目。自然的概念边界（程序与数据）。参考可以增长而不影响每次调用的成本。添加新参考条目不会影响工作流。参考数据可以经常由机器生成和重新生成。 缺点：模型必须在读取之前知道要查找什么。指针必须显式编码查找键。无法在工作流需要将参考数据内联到特定点而不是离散点时使用。拆分内容是概念上统一的，对于人类读者来说更难。

• 深度层（常见路径与边缘情况）

SKILL.md 覆盖 80% 的情况。references/edge-cases.md 覆盖其余情况。指针必须读起来像这样：如果您看到 X、Y 或 Z，请在继续之前停止并读取 references/edge-cases.md。 优点：常见路径保持最小、快速、廉价。边缘情况可以是详尽的，而不会污染每次调用。很容易扩展边缘情况的覆盖范围，而不需要触摸常见路径。反映了专家工作的方式：默认值优先，异常按需。 缺点：加载条件必须是尖锐和可观察的，从用户输入中可以看出。大多数边缘情况都不满足此条件。模糊的条件会导致始终加载（浪费）或从不加载（死重量）。边缘情况得到的关注较少。