1.3 渐进式披露——技能包的设计哲学
📋 多工具适用说明
渐进式披露是来自人机交互领域的通用设计原则，适用于所有 AI 编程工具。
本节以 Claude Code 的三级加载机制为详细示例。各工具实现方式不同：
| 工具 | 发现（Level 1） | 激活（Level 2） | 深度（Level 3） |
|---|---|---|---|
| Claude Code | description（~100 token） | SKILL.md 正文 | references/ 辅助文件 |
| Windsurf | globs 匹配发现 | instructions 内容 | 规则内嵌套参考 |
| Cursor | 手动触发 | Command Prompt 内容 | 无独立资源层 |
概念通用，但只有 Claude Code 有完整的三级文件结构。
引言
想象你走进一家餐厅。
服务员不会一上来就递给你一本 200 页的菜单，把所有菜品、配料、卡路里、过敏原信息全摆在你面前。他先问你想吃什么类型的——中餐还是西餐？确定了方向，再给你看对应的菜单。点完菜了，如果你追问配料细节，他才去后厨确认。
先给方向，再给菜单，最后给细节。 这就是渐进式披露。
从人机交互说起
渐进式披露（Progressive Disclosure）是人机交互领域的经典设计原则，在 1990 年代被正式化。核心理念：不要一次性展示所有信息，先展示必需的，再按需展开。
你每天都在体验它：
| 场景 | Level 1（概览） | Level 2（详情） | Level 3（深度） |
|---|---|---|---|
| 右键菜单 | 看到可用操作 | 点击执行 | 弹出高级设置 |
| 手机设置 | 主分类列表 | 点击看选项 | "高级"区 |
| 搜索引擎 | 10 条摘要 | 点开看全文 | 查看原始论文 |
AI 代理的独特约束
AI 代理面对的问题更严格。它们的"屏幕"是上下文窗口——一个固定大小的 token 预算。
技能包的三级渐进式披露（Claude Code 示例）
Claude Code 的技能包设计正是渐进式披露的精确实现——三个加载层次，对应三种信息粒度：
算一笔账
假设你有 30 个技能包：
| 加载方式 | Token 开销 |
|---|---|
| 全量加载（无渐进式披露） | 30 × 3000 = 90,000 token |
| 渐进式披露 Level 1 | 30 × 100 = 3,000 token |
| 渐进式披露 Level 2（调用 2 个） | 3,000 + 2 × 3000 = 9,000 token |
节省 90%——87,000 token 留给了真正重要的对话内容。
各工具如何实现渐进式披露？
Claude Code：完整三级文件结构
独立目录 + SKILL.md + references/，三级完全分离。最完整的实现。
Windsurf：单文件内规则块
# Level 1 + 2 在同一文件
python-rules:
globs: "src/**/*.py" # Level 1：路径匹配发现
instructions: | # Level 2：激活时加载
Python 代码规范...
完整的 API 文档参见内部链接 # Level 3：按需读取Windsurf 将 Level 1 和 Level 2 合并到同一文件，Level 3 通过规则内的链接引用。
Cursor：两级结构
Command Prompt 模板是 Level 2，通过手动触发。没有独立的 Level 1（无自动发现）和 Level 3（无辅助文件目录）。
通用理解
无论工具如何实现，渐进式披露的核心原则相同：
- 不要一次性加载所有内容——先加载索引，再按需加载详情
- 区分"始终需要"和"偶尔需要"——始终加载核心信息，偶尔加载详细信息
- Token 预算有限——每一行加载的内容都在消耗 AI 的"注意力"
description 的全部重量
Level 1 中，技能包只暴露 description 字段（以 Claude Code 为例）。这几十个字承担了整个触发机制。
写好 description 是技能包创作中最关键的一步——它是渐进式披露的第一级，也是唯一始终运行的一级。
⚠️ 描述写不好，技能包就不存在
如果描述不能传达"何时有用"，AI 就不会知道何时调用它。一个写不好的技能包不是一个"不够好"的技能包——它是一个不存在的技能包。
对比：
| 描述质量 | 示例 | 效果 |
|---|---|---|
| 太模糊 | "帮助部署" | AI 不确定何时该用，经常不触发 |
| 太宽泛 | "管理应用的生命周期" | AI 在不相关场景也触发 |
| 恰好 | "部署到生产或预发布环境。当说'部署'、'上线'、'发布到线上'时使用" | 精准匹配用户意图 |
渐进式披露如何影响技能包写作
从这个哲学出发，推导出四条写作原则：
- 描述是第一印象——把最重要的触发词写在最前面
- 主文件前部是黄金区——压缩后只保留前 5000 token，最重要的指令放最前面
- 辅助文件是深度通道——完整 API 规范放到辅助文件（Claude Code 用
references/），不要塞进主文件 - 不要越级——不要在描述里写步骤（Level 1 做 Level 2 的事），不要在主文件里写完整规范（Level 2 做 Level 3 的事）
本节小结
📌 本节核心要点
- 渐进式披露（通用概念）：先给方向，再给菜单，最后给细节——来自人机交互的经典原则
- 三级加载（Claude Code 示例）：发现层（~100 token）→ 激活层（<5000 token）→ 资源层（按需）
- 各工具实现各异：CC 有完整三级目录，Windsurf 用单文件规则块，Cursor 两级结构
- Token 节省：30 个技能包从 90,000 token 降到 3,000 token（Level 1），节省 97%
- 描述是关键：description 是技能包被发现的唯一入口，写不好等于不存在
- 写作原则（通用）：描述是第一印象、前部是黄金区、辅助文件是深度通道、不要越级
思考题
- 你能想到日常使用的产品中，哪些地方用到了渐进式披露？它们的三级分别是什么？
- 如果一个技能包的 description 写成"帮助开发"，会出现什么问题？你会怎么改？
- 你之前写过的 AI 指令中，有没有"越级"的情况——比如在简要描述中就放了详细步骤？
下一节预告
理论够了，该动手了！下一节我们写第一个技能包——只需要 5 行，但它能让你立刻感受到"按需加载"的魔力。