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
---

核心作用

1. 所有 Skill 的元数据全程常驻 System Prompt 上下文（全部 Skills 合计约 20k tokens）；
2. 给 Reasoner 提供「意图匹配索引」，用户发需求时，快速判断该调用哪个技能；
3. 仅保留极简标识，无详细流程，控制基础上下文体积。

特点

永久载入、极低 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 消耗；

特点

最晚加载、生命周期最短，仅单次子步骤可见。

---

三层完整协作流程举例（生成单元测试）

1. 常驻阶段：上下文里只有generate-unit-test简短元数据，Reasoner 识别你的需求匹配此技能；
2. 披露阶段：动态加载 Skill.md 全部测试生成流程（读文件→建用例→装依赖→跑测试）；
3. 延迟加载阶段：执行到修复报错步骤时，临时读取项目 Jest/Vitest 规范文档，用完丢弃。

三层设计核心收益

1. 贴合 Progressive Disclosure 渐进披露思想，避免全量加载所有技能造成上下文爆炸；
2. 区分陈述性知识（资源文档，第三层）与程序性知识（流程 SOP，第二层）；
3. 大幅降低 API 输入 Token，减少计费，同时降低长上下文带来的模型幻觉、逻辑断裂问题。