Skill.md 三阶段加载机制（基于 Progressive Disclosure 渐进披露架构）
Skill.md 三阶段加载机制（基于 Progressive Disclosure 渐进披露架构）
整套机制是为了控制 Token 开销，不一次性把完整技能全部塞进上下文，分三层懒加载，对应 Cline/Cursor 编码智能体标准设计。
阶段 1：元数据常驻层（永久加载，轻量索引）
存储内容（写在文件头部 YAML 前置块）
yaml
--- name: generate-unit-test description: 读取源码自动生成配套单元测试，安装依赖并执行校验 allowed-tools: ReadFile, WriteFile, Terminal version: 1.0 tags: backend, test ---核心作用
- 所有 Skill 的元数据全程常驻 System Prompt 上下文（全部 Skills 合计约 20k tokens）；
- 给 Reasoner 提供「意图匹配索引」，用户发需求时，快速判断该调用哪个技能；
- 仅保留极简标识，无详细流程，控制基础上下文体积。
特点
永久载入、极低 Token、只做路由匹配，不包含完整执行步骤。
阶段 2：主体流程层（按需动态披露，触发后载入）
存储内容
YAML 下方完整 Markdown 正文：
- 完整分步执行 SOP（Procedural Knowledge 程序性知识）
- 工具调用顺序、校验规则、错误重试逻辑
- 输出格式规范、代码变更约束、人工确认规则
触发条件
Reasoner 识别用户需求匹配该 Skill 的name/description，才把这一大段流程注入上下文；任务结束后，该层内容从临时上下文释放。
核心作用
告诉 AI 完整 “怎么做这件事”，支撑 Progressive Closure 渐进收敛迭代；
特点
不常驻，匹配需求才加载，占用大量 Token，用完即释放。
阶段 3：附属资源延迟加载层（子步骤触发才调取）
存储内容
和 Skill.md 配套的外部资源文件夹：skill-name/scripts/、skill-name/references/、模板代码、规范文档、示例配置
触发条件
Skill 主体流程执行到指定子步骤，才由 Tool 读取并临时加入上下文；比如执行 “生成单元测试” 走到「运行测试、修复报错」环节，才加载项目测试框架参考文档。
核心作用
超大型参考资料不占用基础上下文，仅在必须使用时临时读取；进一步压缩平均 Token 消耗；
特点
最晚加载、生命周期最短，仅单次子步骤可见。
三层完整协作流程举例（生成单元测试）
- 常驻阶段：上下文里只有
generate-unit-test简短元数据，Reasoner 识别你的需求匹配此技能； - 披露阶段：动态加载 Skill.md 全部测试生成流程（读文件→建用例→装依赖→跑测试）；
- 延迟加载阶段：执行到修复报错步骤时，临时读取项目 Jest/Vitest 规范文档，用完丢弃。
三层设计核心收益
- 贴合 Progressive Disclosure 渐进披露思想，避免全量加载所有技能造成上下文爆炸；
- 区分陈述性知识（资源文档，第三层）与程序性知识（流程 SOP，第二层）；
- 大幅降低 API 输入 Token，减少计费，同时降低长上下文带来的模型幻觉、逻辑断裂问题。