渐进式揭示（Progressive Disclosure）：Skill设计的艺术与科学

本文是”如何写好Skill”系列的第二篇，深入探讨渐进式揭示的设计哲学和实战技巧

前言

在上一篇文章《如何写好Skill：完整指南与实践》中，我们介绍了渐进式揭示（Progressive Disclosure）作为Skill设计的三大核心原则之一。

但渐进式揭示不仅仅是一个”技巧”，它是一种深刻的设计哲学，源于UI/UX设计领域，被广泛应用于AI Skill设计、文档写作、产品设计等多个领域。

今天我们专门来探讨：为什么渐进式揭示如此重要？如何在不同场景下应用它？有哪些常见的陷阱需要避免？

第一部分：渐进式揭示的起源与本质

1.1 起源：从UI设计到AI Skill设计

渐进式揭示最初是UI/UX设计中的一个核心原则。

经典定义：

“渐进式揭示是一种交互设计技术，它只在用户需要的时候展示必要的信息或功能，以降低认知负荷并提升用户体验。”

在传统软件中的应用：

Word文档编辑器：
- 初次打开：显示基本功能（加粗、斜体、对齐）
- 用户点击"更多"：显示高级功能（样式、宏、VBA）
- 用户继续探索：显示专家功能（自定义、插件）

目的：
- 避免新手被复杂功能吓跑
- 让用户逐步熟悉系统
- 在合适的时候提供合适的功能

在AI Skill设计中的类比：

传统UI设计：逐步向人类用户揭示功能
AI Skill设计：逐步向AI揭示信息和指令

人类用户：认知负荷有限，需要逐步引导
AI模型：上下文窗口有限，需要按需加载

目标一致：在合适的时机提供合适的深度信息

1.2 本质：信息与认知的平衡

渐进式揭示的核心是平衡两个对立的需求：

需求1：提供完整信息	需求2：降低认知负荷
确保AI有足够的知识完成任务	避免上下文窗口爆满
覆盖所有可能的场景	减少无关信息的干扰
提供详细的指导	提升响应速度和质量

渐进式揭示的平衡点：

不是”少即是好”，而是”刚刚好”
不是隐藏信息，而是”在需要的时候提供”
不是简化，而是”分层呈现”

第二部分：AI Skill中的渐进式揭示

2.1 三层加载系统详解

在AI Skill设计中，渐进式揭示通过三层加载系统实现：

┌─────────────────────────────────────────────────┐
│          第一层：元数据（始终加载）                │
│  - name + description                          │
│  - 用于判断何时触发Skill                       │
│  - ~100词，token成本极低                        │
└─────────────────────────────────────────────────┘
                    ↓ 判断触发
┌─────────────────────────────────────────────────┐
│       第二层：SKILL.md主体（触发时加载）          │
│  - 核心流程和指令                               │
│  - <5k词，平衡信息量和上下文成本                 │
│  - 提供导航，告诉AI何时加载更多资源              │
└─────────────────────────────────────────────────┘
                    ↓ 按需加载
┌─────────────────────────────────────────────────┐
│    第三层：references/（需要时加载）              │
│  - 详细的参考资料                               │
│  - 不限制大小（可能通过script执行）              │
│  - 颗粒度最小，只加载需要的部分                  │
└─────────────────────────────────────────────────┘

2.2 上下文窗口的经济学

为什么需要渐进式揭示？经济学视角

有限的资源：

上下文窗口：128K token（GPT-4）或更少
每个token的成本：~$0.01（估算）
响应延迟：与上下文大小成正比

优化目标：

最小化：上下文大小（成本、延迟）
最大化：信息质量（准确度、完整度）

不使用渐进式揭示的代价：

场景：一个复杂的C++性能优化Skill

不使用渐进式揭示：
- 元数据：100 token
- SKILL.md：5000 token（包含所有细节）
- references/：15000 token（一次性全部加载）
- 总计：20000+ token

问题：
1. 成本高：每次查询成本$0.2+
2. 延迟高：加载时间长
3. 干扰多：无关信息影响AI判断

使用渐进式揭示：
- 元数据：100 token（始终）
- SKILL.md：500 token（触发时，只包含核心流程）
- references/：按需加载（500-2000 token）
- 总计：1100-2600 token

优势：
1. 成本低：每次查询成本$0.01-0.03（降低85%+）
2. 延迟低：响应速度快2-3倍
3. 干扰少：信息干净，AI专注度高

ROI计算：

假设：
- 每天使用该Skill 50次
- 不使用渐进式揭示：$0.2 × 50 = $10/天
- 使用渐进式揭示：$0.02 × 50 = $1/天

月度节省：($10 - $1) × 30 = $270
年度节省：$270 × 12 = $3,240

投入：设计渐进式揭示，4小时
ROI：$3,240 / 4小时 = $810/小时

2.3 AI的认知负荷

虽然AI不像人类那样有”认知负荷”，但”上下文噪音”会影响AI的注意力机制。

注意力机制的局限性：

Transformer的注意力机制：
- 对每个token，计算与其他所有token的相关性
- 上下文越长，计算量越大
- 无关信息会"稀释"关键信息的权重

类比：
- 长上下文 = 在嘈杂的房间找朋友
- 短上下文 = 在安静的房间找朋友

实际案例：

场景：AI需要查询销售数据

❌ 所有领域的schema都加载：
Finance Schema（500行）
Sales Schema（500行）
Product Schema（500行）
Marketing Schema（500行）
总计：2000行

AI的行为：
- 注意力分散到所有schema
- 可能误用Finance的字段
- 查询语句可能包含不相关的内容

✅ 只加载Sales Schema：
AI的行为：
- 注意力集中在Sales相关内容
- 准确使用Sales的字段
- 查询语句清晰准确

第三部分：渐进式揭示的模式库

3.1 模式1：功能分层（最常用）

适用场景：Skill有多个功能模块，用户可能只需要其中一个。

实现方式：

在SKILL.md中列出核心功能
每个功能链接到独立的reference文件
说明何时加载哪个reference

示例：

# PDF处理Skill
 
## 核心功能
 
### 文本提取
使用pdfplumber快速提取文本：
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()


### 表单填充
**何时使用**：需要填充PDF表单字段时
参见：[FORMS.md](references/FORMS.md)

### 图片处理
**何时使用**：需要提取、旋转、压缩PDF中的图片时
参见：[IMAGES.md](references/IMAGES.md)

### API参考
**何时使用**：需要查看所有可用方法和参数时
参见：[API.md](references/API.md)

### 示例代码
**何时使用**：需要参考完整的使用示例时
参见：[EXAMPLES.md](references/EXAMPLES.md)

AI的行为逻辑：

用户："帮我提取PDF中的文本"
→ AI使用SKILL.md中的文本提取代码（不加载任何reference）

用户："帮我填写这个PDF表单"
→ AI加载references/FORMS.md

用户："如何旋转PDF中的图片？"
→ AI加载references/IMAGES.md

优点：

简单直观
颗粒度可控
易于维护

缺点：

如果功能很多，SKILL.md会变长
需要明确”何时使用”的描述

3.2 模式2：领域分离（适用于复杂业务）

适用场景：Skill覆盖多个独立的业务领域，每个领域有详细的知识库。

实现方式：

在SKILL.md中列出所有支持的业务领域
每个领域一个reference文件
每个reference包含该领域的完整信息

示例：

# BigQuery数据分析Skill
 
## 支持的业务领域
 
此Skill支持以下业务领域的数据查询和分析：
 
### 财务数据（Finance）
**包含内容**：
- 收入、成本、利润数据
- 账单、发票、付款记录
- 财务指标和趋势分析
 
**何时使用**：
- 查询收入、成本、利润
- 分析财务趋势
- 生成财务报表
 
**详细指南**：[references/finance.md](references/finance.md)
 
---
 
### 销售数据（Sales）
**包含内容**：
- 销售机会（Opportunities）
- 管道（Pipeline）分析
- 客户转化数据
- 销售团队表现
 
**何时使用**：
- 查询销售机会
- 分析销售管道
- 计算转化率
 
**详细指南**：[references/sales.md](references/sales.md)
 
---
 
### 产品数据（Product）
**包含内容**：
- API使用情况
- 功能采用率
- 用户行为数据
- 产品性能指标
 
**何时使用**：
- 查询API调用数据
- 分析功能使用情况
- 监控产品性能
 
**详细指南**：[references/product.md](references/product.md)
 
---
 
### 市场数据（Marketing）
**包含内容**：
- 营销活动数据
- 渠道转化分析
- ROI分析
- 用户获取成本
 
**何时使用**：
- 查询营销活动效果
- 分析渠道表现
- 计算ROI
 
**详细指南**：[references/marketing.md](references/marketing.md)
 
---
 
## 使用说明
 
说明你的查询需求，AI会自动识别业务领域并加载相应的数据模型和schema。

references/finance.md的结构：

# 财务数据 - 数据模型
 
## 表结构
 
### revenue表（收入表）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT64 | 主键 |
| date | DATE | 日期 |
| amount | FLOAT64 | 金额 |
| currency | STRING | 币种 |
| region | STRING | 地区 |
| product_line | STRING | 产品线 |
 
### costs表（成本表）
...
 
## 常见查询
 
### 查询月度收入
```sql
SELECT
  DATE_TRUNC(date, MONTH) as month,
  SUM(amount) as total_revenue
FROM revenue
WHERE date >= '2024-01-01'
GROUP BY 1
ORDER BY 1
 
### 查询各地区收入分布
...
 
## 业务规则
- 收入确认遵循ASC 606标准
- 货币统一转换为USD
- 地区划分遵循ISO 3166-2标准
 
**优点**：
- 领域隔离，互不干扰
- 每个领域可以独立维护
- 加载精准，上下文干净
 
**缺点**：
- 需要明确的领域划分
- 如果需求涉及多领域，可能需要加载多个reference

3.3 模式3：难度分层（适用于学习路径）

适用场景：功能有明显的难度分层，用户可能从简单到复杂逐步探索。

实现方式：

分为”快速开始”、“标准用法”、“高级用法”等层级
每个层级链接到不同深度的reference
AI根据用户的复杂度需求选择加载

示例：

# Docker部署Skill
 
## 快速开始（5分钟）
 
最简单的部署方式，适合首次使用：
 
```bash
docker run -d -p 8080:80 myapp:latest

就这样，应用已经运行在 http://localhost:8080

标准部署（15分钟）

推荐的生产环境配置，包含：

数据卷挂载
环境变量配置
健康检查

参见：STANDARD.md

高级部署（30分钟+）

复杂场景的部署方案，包含：

Docker Compose编排
多容器通信
日志收集
监控集成

参见：ADVANCED.md

专家级部署（自定义）

高度定制化的部署，包含：

Kubernetes集群
自定义网络策略
服务网格集成

参见：EXPERT.md

如何选择？

快速验证/学习 → 快速开始
小型生产环境 → 标准部署
中型生产环境 → 高级部署
大型企业级 → 专家级部署


**AI的行为逻辑**：

用户：“帮我快速运行这个Docker应用” → AI使用快速开始（不加载任何reference）

用户：“我需要部署到生产环境，需要数据持久化” → AI加载references/STANDARD.md

用户：“我们有微服务架构，需要Docker Compose” → AI加载references/ADVANCED.md

优点：

用户友好的学习路径
避免初期被复杂度吓退
满足不同经验水平的需求

缺点：

层级划分需要精心设计
如果用户需求跨越层级，可能需要加载多个reference

3.4 模式4：条件触发（适用于动态需求）

适用场景：同一个功能在不同情况下需要不同深度的信息。

实现方式：

在SKILL.md中列出触发条件
AI根据用户的具体需求决定加载什么
使用条件判断或关键词匹配

示例：

# 代码审查Skill
 
## 审查流程
 
1. 分析代码的功能和意图
2. 检查潜在的问题
3. 按以下方式输出结果
 
### 快速审查（默认）
 
输出简洁的问题列表：
 
## 发现的问题
- 问题1：[描述]
- 问题2：[描述]
 
### 详细审查
 
**在以下情况会加载详细审查指南**：
- 代码文件超过500行
- 用户明确要求"详细审查"
- 代码涉及关键业务逻辑
- 代码存在安全问题
 
详细审查报告结构：
- 问题分级（严重/中等/建议）
- 每个问题的详细说明
- 修改建议和示例代码
- 性能影响分析
 
参见：[DETAILED-REVIEW.md](references/DETAILED-REVIEW.md)
 
### 安全审计
 
**在以下情况会触发安全审计**：
- 涉及用户输入处理
- 涉及文件系统操作
- 涉及网络请求
- 涉及密码或密钥
 
安全审计包括：
- SQL注入检查
- XSS检查
- 命令注入检查
- 路径遍历检查
- 敏感信息泄露检查
 
参见：[SECURITY-AUDIT.md](references/SECURITY-AUDIT.md)

AI的行为逻辑：

用户："审查这段50行的代码"
→ AI输出快速审查（不加载任何reference）

用户："详细审查这个600行的复杂模块"
→ AI加载references/DETAILED-REVIEW.md

用户："审查这段处理用户输入的代码"
→ AI加载references/SECURITY-AUDIT.md

优点：

动态适应需求
避免过度加载
覆盖特殊场景

缺点：

触发条件需要精心设计
可能误判（该加载时没加载）
需要AI有一定的判断能力

3.5 模式5：按需深度（适用于不确定需求）

适用场景：不确定用户需要多深的信息，让用户或AI决定。

实现方式：

提供基础信息在SKILL.md
提供”需要更多细节吗？“的引导
用户要求更详细信息时才加载reference

示例：

# Git操作Skill
 
## 常用操作
 
### 查看状态
```bash
git status

提交更改

git add .
git commit -m "提交信息"

推送到远程

git push

需要更详细的帮助吗？

如果上面的常用操作不够用，以下资源提供详细信息：

Git命令完整参考

所有Git命令的详细说明和参数： GIT-COMMANDS.md

Git工作流

不同的Git工作模式（Git Flow, GitHub Flow等）： WORKFLOWS.md

Git冲突解决

解决合并冲突的详细步骤： CONFLICT-RESOLUTION.md

Git高级技巧

Rebase, Cherry-pick, Stash等高级操作： ADVANCED.md

如何获取详细信息？

如果上面的常用操作不够，可以：

直接说”需要详细的Git命令参考”
描述具体问题（如”如何解决冲突”）
说明使用场景（如”团队协作的工作流”）

AI会根据你的需求加载相应的详细指南。

AI的行为逻辑：

用户："帮我提交代码"
→ AI使用常用操作（不加载reference）

用户："我遇到一个复杂的合并冲突"
→ AI加载references/CONFLICT-RESOLUTION.md

用户："详细说明git rebase"
→ AI加载references/GIT-COMMANDS.md

优点：

灵活性高
用户主导
避免猜测

缺点：

需要用户明确表达需求
用户可能不知道有哪些详细信息可用
增加交互轮次

第四部分：渐进式揭示的实战技巧

4.1 技巧1：明确的”触发器”

不要只是链接文件，要说明在什么情况下触发加载。

❌ 不好：

## 高级功能
参见 [ADVANCED.md](references/ADVANCED.md)

问题：

AI不知道何时加载
可能在不该加载的时候加载
可能在该加载的时候没加载

✅ 好：

## 高级功能
 
在以下情况会加载高级功能指南：
- 代码超过500行
- 用户明确要求"高级优化"
- 需要使用SIMD指令
- 需要自定义并行策略
 
参见：[ADVANCED.md](references/ADVANCED.md)

优点：

AI有明确的判断标准
加载行为可预测
减少不必要的加载

4.2 技巧2：提供内容概览

让AI在加载reference之前就知道里面有什么，避免盲目加载。

❌ 不好：

## API参考
参见 [API.md](references/API.md)

问题：

AI不知道API.md里有什么
可能加载了不需要的内容
浪费token

✅ 好：

## API参考
 
### 核心方法（已在上面说明）
- `get()`: 获取数据
- `post()`: 提交数据
- `put()`: 更新数据
- `delete()`: 删除数据
 
### 详细API文档
 
[API.md](references/API.md) 包含：
- 所有方法的详细参数说明
- 返回值结构
- 错误码完整列表
- 速率限制规则
- 认证方式
- WebSocket支持
 
**何时加载**：
- 需要查看详细的参数定义
- 需要处理错误码
- 需要使用高级功能（如WebSocket）
 
**不加载的情况**：
- 只需要基本的CRUD操作
- 使用默认参数
- 不涉及特殊错误处理

优点：

AI可以预判是否需要加载
减少”加载后发现不需要”的情况
节省token成本

4.3 技巧3：结构化长文件

超过100行的reference文件，在顶部提供清晰的目录。

❌ 不好：

# references/performance.md
 
## 内存访问优化
 
（500行内容...）
 
## CPU缓存优化
 
（400行内容...）
 
## SIMD指令
 
（300行内容...）

问题：

AI不知道文件里有什么
难以找到需要的内容
可能加载整个文件但只用一小部分

✅ 好：

# references/performance.md
 
## 目录
 
1. [内存访问优化](#内存访问优化)（500行）
   - 连续内存布局
   - 缓存友好访问模式
   - 避免cache miss
 
2. [CPU缓存优化](#cpu缓存优化)（400行）
   - 数据结构对齐
   - 缓存行优化
   - 预取策略
 
3. [SIMD指令](#simd指令)（300行）
   - SSE/AVX指令集
   - 向量化模式
   - 编译器自动向量化
 
4. [并行计算](#并行计算)（350行）
   - OpenMP
   - 线程池
   - 无锁编程
 
5. [编译器优化](#编译器优化)（200行）
   - 优化标志
   - 链接时优化（LTO）
   - PGO（Profile-Guided Optimization）
 
## 快速导航
 
- **快速优化检查清单** → [CHECKLIST](#快速优化检查清单)
- **常见性能问题** → [COMMON-ISSUES](#常见性能问题)
- **优化案例** → [CASES](#优化案例)
 
## 内存访问优化
 
...

优点：

AI可以快速了解文件结构
可以跳转到需要的部分
便于preview（预览模式）

4.4 技巧4：避免深层嵌套

保持引用结构扁平，所有reference直接从SKILL.md链接。

❌ 不好：

SKILL.md
  └── references/
      └── ADVANCED.md
          └── 参考文献：
              ├── part1.md
              ├── part2.md
              └── part3.md

问题：

加载一个reference可能触发加载更多
难以预测最终加载量
可能产生循环引用

✅ 好：

SKILL.md
  ├── references/advanced-part1.md
  ├── references/advanced-part2.md
  └── references/advanced-part3.md

SKILL.md中的链接：

## 高级功能
 
### 并行计算
参见：[advanced-part1.md](references/advanced-part1.md)
 
### SIMD指令
参见：[advanced-part2.md](references/advanced-part2.md)
 
### 编译器优化
参见：[advanced-part3.md](references/advanced-part3.md)

优点：

加载行为可预测
避免连锁加载
更容易维护

4.5 技巧5：使用”条件性加载”

在reference文件中使用明显的标记，告诉AI哪些部分需要特别关注。

示例：

# references/security.md
 
## 🔴 必须检查的安全问题（每次都要看）
 
这些问题在任何情况下都必须检查：
 
### SQL注入
### XSS
### CSRF
### 敏感信息泄露
 
---
 
## 🟡 建议检查的问题（根据上下文决定）
 
这些问题根据具体代码决定是否检查：
 
### 输入验证
### 错误处理
### 日志记录
 
---
 
## 🟢 高级安全问题（特殊场景才检查）
 
以下问题仅在特定场景下需要：
 
### 侧信道攻击
### 竞态条件
### 逻辑漏洞

AI的行为：

用户："审查这段处理用户输入的代码"
→ AI加载security.md
→ 优先检查🔴部分
→ 根据代码特点检查🟡部分

用户："审查这段简单的工具函数"
→ AI加载security.md
→ 只检查🔴部分
→ 跳过🟢部分

第五部分：常见误区与陷阱

5.1 误区1：所有内容都放在SKILL.md中

错误做法：

# SKILL.md - 2000行
 
## 基础操作
（200行）
 
## 高级功能
（500行）
 
## API参考
（800行）
 
## 示例代码
（500行）

后果：

每次使用都加载2000行
Token成本高
响应慢
难以维护

正确做法：

# SKILL.md - 300行
 
## 基础操作
（200行）
 
## 高级功能
详见：[references/ADVANCED.md](references/ADVANCED.md)
 
## API参考
详见：[references/API.md](references/API.md)
 
## 示例代码
详见：[references/EXAMPLES.md](references/EXAMPLES.md)

5.2 误区2：Reference文件没有导航

错误做法：

# references/api.md - 1000行，没有目录
 
（直接开始内容...）

后果：

AI不知道文件里有什么
可能加载了不需要的部分
浪费token
难以定位

正确做法：

# references/api.md
 
## 目录
1. [认证方法](#认证方法)
2. [核心API](#核心api)
3. [错误码](#错误码)
4. [WebSocket](#websocket)
 
（然后是详细内容...）

5.3 误区3：Reference之间互相引用

错误做法：

references/part1.md:
"参见 [part2.md](part2.md) 的详细说明"

references/part2.md:
"参见 [part3.md](part3.md) 的更多细节"

后果：

加载一个reference可能触发加载更多
难以预测加载量
可能产生循环引用
Token成本失控

正确做法：

SKILL.md:
"参见 [part1.md](references/part1.md)"
"参见 [part2.md](references/part2.md)"
"参见 [part3.md](references/part3.md)"

所有引用直接从SKILL.md出发

5.4 误区4：没有明确的触发条件

错误做法：

## 高级功能
更多信息参见 [ADVANCED.md](references/ADVANCED.md)

后果：

AI不知道何时加载
可能在不该加载时加载
可能在该加载时没加载

正确做法：

## 高级功能
 
**在以下情况会加载高级功能指南**：
- 代码超过500行
- 用户明确要求"高级优化"
- 需要使用SIMD指令
- 需要自定义并行策略
 
参见：[ADVANCED.md](references/ADVANCED.md)

5.5 误区5：过度拆分

错误做法：

SKILL.md
  ├── references/part1-1.md
  ├── references/part1-2.md
  ├── references/part1-3.md
  ├── references/part2-1.md
  ├── references/part2-2.md
  ├── references/part3-1.md
  └── ...（20个小文件）

后果：

难以维护
文件过于琐碎
增加复杂度
没有明显收益

正确做法：

SKILL.md
  ├── references/part1.md
  ├── references/part2.md
  └── references/part3.md

每个文件保持在500-1000行

第六部分：实战案例

6.1 案例：从混乱到有序

初始状态：

# SKILL.md - 2500行
 
包含了所有内容：
- 基础操作
- 高级功能
- API参考
- 示例代码
- 最佳实践
- 常见问题
- 故障排查

问题：

每次使用都加载2500行
Token成本高（$0.1+每次）
响应慢（10+秒）
维护困难

应用渐进式揭示：

skill-name/
├── SKILL.md（300行）
│   ├── 基础操作（200行）
│   ├── 导航到高级功能
│   └── 导航到参考资料
├── references/
│   ├── advanced.md（600行）
│   ├── api-reference.md（800行）
│   ├── examples.md（500行）
│   └── troubleshooting.md（400行）
└── examples/
    └── sample-project/

改进效果：

平均加载量：300行（基础） + 600行（按需） = 900行
Token成本：$0.03-0.05每次（降低70%+）
响应时间：3-5秒（提高50%+）
维护性：模块化，易于更新

ROI计算：

假设每天使用50次
改进前：$0.1 × 50 = $5/天
改进后：$0.04 × 50 = $2/天

月度节省：($5 - $2) × 30 = $90
年度节省：$90 × 12 = $1,080

重构时间：8小时
ROI：$1,080 / 8小时 = $135/小时

6.2 案例：多领域数据查询Skill

需求：

支持查询多个业务领域的数据
每个领域有详细的数据模型
用户通常只查询一个领域

初始设计：

# SKILL.md - 包含所有领域
 
## Finance Schema（500行）
## Sales Schema（500行）
## Product Schema（500行）
## Marketing Schema（500行）
 
总计：2000行

问题：

查询销售数据时，财务schema也会加载
AI可能被其他领域的schema干扰
Token浪费

应用渐进式揭示：

# SKILL.md（150行）
 
## 支持的业务领域
 
### 财务数据
**包含**：收入、成本、利润、账单
**详细指南**：[references/finance.md](references/finance.md)
 
### 销售数据
**包含**：机会、管道、转化、客户
**详细指南**：[references/sales.md](references/sales.md)
 
### 产品数据
**包含**：API使用、功能、用户行为
**详细指南**：[references/product.md](references/product.md)
 
### 市场数据
**包含**：活动、渠道、ROI
**详细指南**：[references/marketing.md](references/marketing.md)
 
## 使用说明
 
说明你的查询需求，AI会加载相应领域的详细指南。

references/
├── finance.md（500行）
├── sales.md（500行）
├── product.md（500行）
└── marketing.md（500行）

改进效果：

查询销售数据：只加载sales.md（500行）
上下文更干净，AI专注度更高
查询准确度提升

第七部分：检查清单

设计阶段

明确Skill的功能范围和边界
识别不同的使用场景和复杂度
决定采用哪种渐进式揭示模式
设计三层加载结构

实现阶段

SKILL.md保持在500行以内
每个reference有明确的触发条件
Reference文件顶部包含目录
避免深层嵌套引用
Reference之间不互相引用

测试阶段

维护阶段

定期review加载模式
监控Token使用情况
根据使用数据优化触发条件
更新过时的reference内容

总结

渐进式揭示是Skill设计的核心原则，它的价值体现在：

1. 成本优化

降低Token消耗70%+
显著减少API调用成本

2. 性能提升

响应时间减少50%+
上下文更干净，AI专注度更高

3. 维护性改善

模块化设计，易于维护
团队协作效率高

4. 用户体验提升

快速响应，无需等待
准确的结果，不被干扰

核心要点：

三层加载系统：元数据 → SKILL.md → references/
明确的触发器：说明何时加载什么
结构化内容：提供导航和概览
扁平化引用：避免深层嵌套
持续优化：根据使用数据迭代

下一步

现在你已经掌握了渐进式揭示的完整方法论，接下来可以：

重构现有Skill：应用渐进式揭示优化你的Skill
设计新Skill：从一开始就采用渐进式揭示
分享经验：将你的设计经验分享给团队
深入学习：探索更多设计模式和最佳实践

欢迎关注我的公众号，获取更多AI编程实战经验！

如果你有任何关于渐进式揭示的问题或想分享你的实践经验，欢迎在评论区留言。

KnowHowAI

探索

渐进式揭示-Skill设计的艺术与科学

渐进式揭示（Progressive Disclosure）：Skill设计的艺术与科学

前言

第一部分：渐进式揭示的起源与本质

1.1 起源：从UI设计到AI Skill设计

1.2 本质：信息与认知的平衡

第二部分：AI Skill中的渐进式揭示

2.1 三层加载系统详解

2.2 上下文窗口的经济学

2.3 AI的认知负荷

第三部分：渐进式揭示的模式库

3.1 模式1：功能分层（最常用）

3.2 模式2：领域分离（适用于复杂业务）

3.3 模式3：难度分层（适用于学习路径）

标准部署（15分钟）

高级部署（30分钟+）

专家级部署（自定义）

如何选择？

3.4 模式4：条件触发（适用于动态需求）

3.5 模式5：按需深度（适用于不确定需求）

提交更改

推送到远程

需要更详细的帮助吗？

Git命令完整参考

Git工作流

Git冲突解决

Git高级技巧

如何获取详细信息？

第四部分：渐进式揭示的实战技巧

4.1 技巧1：明确的”触发器”

4.2 技巧2：提供内容概览

4.3 技巧3：结构化长文件

4.4 技巧4：避免深层嵌套

4.5 技巧5：使用”条件性加载”

第五部分：常见误区与陷阱

5.1 误区1：所有内容都放在SKILL.md中

5.2 误区2：Reference文件没有导航

5.3 误区3：Reference之间互相引用

5.4 误区4：没有明确的触发条件

5.5 误区5：过度拆分

第六部分：实战案例

6.1 案例：从混乱到有序

6.2 案例：多领域数据查询Skill

第七部分：检查清单

设计阶段

实现阶段

测试阶段

维护阶段

总结

下一步

关系图谱

目录