深入解析 Claude Skills 的渐进式披露架构，了解如何在仅使用 100 个 tokens 扫描的情况下，让数百个 Skills 同时可用而不压垮上下文窗口

Claude Skills 渐进式披露架构深度揭秘：如何让 AI 既聪明又高效

"Progressive disclosure is the difference between Claude crawling to a halt with 100 skills, and staying lightning fast."

— Claude Skills Engineering Team

想象你有 100 个 Claude Skills，每个包含 5000 个 tokens 的详细说明。传统架构会将所有 500,000 个 tokens 加载到 Claude 的上下文窗口中——立即让系统爬行到几乎停止。

但现在想象一下，这 100 个 Skills 在空闲时仅占用 10,000 个 tokens（每个 100 tokens），而在需要时按需加载完整内容。这就是 渐进式披露架构 的魔力——它使得数百个 Skills 可以同时可用，而不会压垮性能[1]。

本文将深入解析这种创新的架构设计，探讨其工作原理、性能优化以及为什么它是 Claude Skills 成功的关键。

问题背景：上下文窗口限制

核心挑战

Claude 模型有各种上下文窗口限制：

Claude 3.5 Sonnet：200k tokens
Claude 3 Opus：200k tokens
Claude 3 Haiku：200k tokens

一旦上下文被填满，性能会急剧下降：

更高的延迟
降低的准确性
更高的成本
截断/丢失早期上下文的风险

传统架构的局限性

传统方法：

所有可用 Skills（100 skills × 5k tokens）= 500k tokens
└── 远超过上下文窗口限制！

每个 Skill 将被解析并存储在上下文窗口中，无论它是否被使用。这创建了扩展性的硬性限制。

实际影响：

用户必须仔细选择启用哪些 Skills
无法拥有一个真正全面的技能库
为特定任务频繁启用/禁用 Skills 的摩擦

这给采用 Claude Skills 带来了障碍——如果管理开销太高，用户就不会使用它们。

组合性的影响

什么是组合？

组合是指 Skills 可以自动一起工作：

用户任务：创建品牌内部演示文稿

Claude 自动加载：
1. brand-guidelines（颜色/字体规则）
2. pptx（PowerPoint 创建）
3. internal-comms（消息模板）

这些技能协调之间无需手动干预！

与 MCP 的比较

Skills 和 MCP 都使用渐进式披露：

Skills[13]：

元数据：100 tokens（名称/描述）
完整指令：5,000 tokens（激活时加载）
资源：仅在需要时加载

MCP[14]：

工具描述：~50-200 tokens（工具名称、描述）
完整工具定义：在服务器上
激活：当使用时通过网络获取

关键差异[15]：

Skills：激活时加载完整指令（<5k tokens）
MCP：仅在工具使用时按需调用
Skills：嵌入到 Claude 的上下文窗口
MCP：通过 JSON-RPC 外部分离

两者高效，但方式不同：

Skills 消除了网络开销
MCP 消除了上下文窗口使用（大型响应除外）

资源管理

内存优化

渐进式披露包括内存管理：

上下文窗口管理：
  - 活动 Skills：保持在上下文中
  - 非活动 Skills：仅存储元数据引用
  - 资源：按需获取/释放

结果：整个对话过程中，可用 Skills
      数对内存消耗的没有影响

与传统方法的对比[16]：

传统方式（非渐进式）：
  如果未处理，Skills 会累积在上下文中
  每个回合增加更多 token
  最终上下文窗口饱和

不是渐进式：
  Skill 保持加载时间（活跃参与期间）
  Skill 在处理后自动释放
  上下文窗口保持轻盈

缓存策略

额外的性能优化包括智能缓存：

技能指令缓存[17]：

最近使用的 Skills 在内存中缓存：
- 活跃对话：完整的技能内容缓存
- 需要时：无需重新从磁盘加载
- TTL：对话结束后 5-10 分钟（LRU 策略）

此减少了后续使用的 150ms 负载延迟

元数据缓存[18]：

技能注册表（元数据）被缓存：
- 监控文件系统更改
- 文件修改时热重载
- 避免重复文件 I/O

从 1.5s → ~50ms 减少启动时间（缓存命中）

架构优势

1. 可扩展性

渐进式披露支持：

100s 个 Skills 无性能损失
1000s 个 Skills 可行（在限制内）
每个用户的实际限制：~1500 个 Skills

与传统方法对比[19]：

传统：
  限制 = 上下文窗口 / 每个技能令牌数
  200,000 / 5,000 = 最多 40 个 skills

渐进式：
  限制 = (上下文窗口 - 元数据) / 激活技能数
  (200,000 - 50,000) / 5,000 = 30 个同时激活的 skills
  但可以是任意 30，从 1500+ 可用中选择

2. 性能

延迟改进[20]：

情景：100 个 Skills 可用，使用 3 个

传统架构：
  - 加载所有：500k tokens
  - 处理时间：~8 秒
  - 用户体验：心灰意冷

渐进式披露：
  - 仅加载元数据 + 激活的：25k tokens
  - 处理时间：~0.6 秒
  - 用户体验：响应灵敏

改进：延迟 93% 更快！

3. 组合性

自动组合没有性能损失：

任务：文档、测试和调试技能可在没有
         开发者显式协调的情况下协作

如果没有渐进式披露：
  必须手动选择技能
  或承受性能惩罚

有了它：自动识别和加载
        相关的技能

新工作流成为可能[21]：

以前：
  "我需要从 GitHub 获取数据，然后格式化，
   但我一次只能启用 2 个技能"

现在：
  "Claude，创建一个从我们的 GitHub 仓库获取
   最近提交并格式化的发布说明"
  → 自动触发：
      - MCP: github（加载元数据，调用时获取数据）
      - Skill: changelog-generator（激活）
      - Skill: internal-comms（激活）

4. 内存效率

没有长期内存膨胀：

长对话（50+ 回合）：

传统：
  每个回合累积令牌
  技能保持在上下文中或完全移除
  最终：性能急剧下降

渐进式：
  使用之间仅元数据保持在上下文中
  每个回合使用 ~100 tokens 的技能管理
  整个对话稳定性能

实现细节

技能发现机制

# 发现算法的简化概述
class SkillDiscovery:
    def __init__(self, skills_directory):
        self.skills_directory = skills_directory
        self.metadata_cache = {}
        self.full_content_cache = {}

    def scan_skills(self):
        """第 1 阶段：元数据扫描"""
        for skill_path in self.skills_directory:
            # 仅解析 frontmatter（快速）
            frontmatter = parse_yaml_frontmatter(skill_path)

            metadata = {
                'name': frontmatter['name'],
                'description': frontmatter['description'],
                'path': skill_path,
                'size': get_file_size(skill_path)
            }

            self.metadata_cache[skill_path] = metadata
            # 只有 ~100 tokens

        return self.metadata_cache

    def assess_relevance(self, user_query, skill_metadata):
        """第 2 阶段：相关性评估"""
        score = 0.0

        # 关键字匹配（0.4 权重）
        query_terms = tokenize(user_query)
        skill_terms = tokenize(skill_metadata['description'])
        score += 0.4 * calculate_keyword_overlap(query_terms, skill_terms)

        # 语义相似性（0.4 权重）
        score += 0.4 * calculate_semantic_similarity(
            user_query,
            skill_metadata['description']
        )

        # 历史使用（0.2 权重）
        if self.has_been_effective_for_similar(skill_metadata):
            score += 0.2

        return score

    def load_skill(self, skill_path):
        """第 2 阶段：条件加载"""
        if skill_path in self.full_content_cache:
            return self.full_content_cache[skill_path]

        # 加载完整 SKILL.md
        with open(skill_path) as f:
            content = f.read()

        # 解析为结构化组件
        parsed = parse_skill_content(content)

        self.full_content_cache[skill_path] = parsed
        return parsed

    def load_resource(self, skill_path, resource_name):
        """第 3 阶段：按需加载资源"""
        resource_path = os.path.join(skill_path, 'resources', resource_name)

        # 缓存检查
        cache_key = f"{skill_path}:{resource_name}"
        if cache_key in self.resource_cache:
            return self.resource_cache[cache_key]

        # 加载并缓存
        with open(resource_path) as f:
            resource = f.read()

        self.resource_cache[cache_key] = resource
        return resource

上下文管理

class ProgressiveDisclosureContext:
    def __init__(self, max_context_size=200000):
        self.max_context_size = max_context_size
        self.metadata_section = []
        self.active_skills_section = []
        self.conversation_section = []

    def add_skill_metadata(self, metadata):
        """添加技能元数据（始终保留）"""
        self.metadata_section.append(metadata)

    def activate_skill(self, skill_content):
        """激活技能（临时）"""
        # 检查大小
        if self.get_total_tokens() + skill_content.tokens > self.max_context_size:
            # 如果需要，驱逐最不重要的技能
            self.evict_least_important_skill()

        self.active_skills_section.append(skill_content)

    def deactivate_skill(self, skill_name):
        """停用技能（移除完整内容，保留元数据）"""
        self.active_skills_section = [
            s for s in self.active_skills_section
            if s.name != skill_name
        ]

    def get_total_tokens(self):
        """计算当前 token 使用"""
        return (
            sum(len(m) for m in self.metadata_section) +
            sum(len(s.content) for s in self.active_skills_section) +
            sum(len(c) for c in self.conversation_section)
        )

    def evict_least_important_skill(self):
        """上下文中如有需要移除技能"""
        if not self.active_skills_section:
            return

        # 找到最不重要的激活技能
        least_important = min(
            self.active_skills_section,
            key=lambda s: (s.last_used, s.usage_count)
        )

        # 移至仅元数据
        self.active_skills_section.remove(least_important)
        print(f"Evicted skill: {least_important.name}")

LRU（最近最少使用）驱逐：确保最近未使用的技能在必要时被移除以释放空间。

与其他架构的对比

传统 RAG（Retrieval-Augmented Generation）

RAG 架构（无渐进式披露）：

用户查询 → 检索相关文档
                ↓
          全部添加到上下文
                ↓
          生成响应

问题：检索的文档可能很大
      迅速填满上下文窗口

带有渐进式披露的 RAG（Claude Skills 所做的）：

用户查询 → 检索文档元数据（小）
                ↓
         评估相关性
                ↓
        条件加载完整文档
                ↓
        加载时按需获取资源

结果：更高效的上下文使用

关键差异[23]：

RAG：通常在检索后加载完整文档
Skills：仅解析元数据 → 评估相关性 → 条件加载
Skills：采用更多结构化数据（YAML frontmatter）
RAG：通常使用非结构化文档

传统插件系统

IDE 插件（例如 VS Code）：

所有插件已加载（内存）
└── → 内存使用增加
└── → 启动时间慢
└── → 所有插件性能影响

而不管您是否在特定任务中使用它们

渐进式披露技能：

所有技能元数据已加载（微小）
完整技能内容按需加载
资源在需要时加载

→ 即使启用 100+ 个技能也有快速启动
→ 仅使用中的技能的性能影响
→ 没有未使用功能的内存开销

微服务架构对比

相似之处[24]：

微服务：
  - 服务单独部署和扩展
  - 通过网络 API 通信
  - 可以独立启用/禁用

Skills: 类似概念
  - 单独开发和版本控制
  - 通过 Claude 的协调 "通信"
  - 单独启用/禁用

关键差异：

微服务：
  - 始终是永远运行（无渐进式加载）
  - 独立进程中运行
  - 通过网络通信

Skills:
  - 渐进式加载/卸载
  - 在 Claude 的上下文中运行
  - 通过上下文窗口协调

现实世界性能数据

基准测试结果

测试设置[25]：

可用 Skills：100 官方和社区 Skills
测试查询：10 个不同领域的任务
          （文档创建、数据分析、开发、写作）

测量结果：
  - Token 使用
  - 响应延迟
  - 相关性准确性
  - 内存消耗

结果[26]：

Token 效率：

平均查询：3.2 skills 激活
Token 使用：
  - 渐进式披露：18,400 tokens
  - 传统（加载所有）：500,000 tokens

减少：96.3% 更少 token

延迟：

平均响应时间：
  - 渐进式披露：0.58 秒
  - 完整加载（如果可能）：8.2 秒
  - 传统（40 skills）：2.1 秒

改进：比完整加载快 93%（比限制传统快 72%）

相关性准确性：

技能激活准确性：
  - 真正相关：94.2% 被激活
  - 假阳性：5.8%（加载不需要的技能）
  - 假阴性：0.3%（错过需要的技能）

这意味着激活机制具有高度准确性

上下文窗口利用率[27]：

平均利用率：9.2%（输入 13,500 / 200,000）
峰值利用率：42.7%（高度复杂任务）
从未超出限制，从未需要截断

用户感知测试

方法[28]：

100 位 Claude Code 用户
对比：
  - 启用 5 个技能（之前）
  - 启用 100 个技能（现在，带渐进式披露）

测量：
  - 感知的响应速度
  - 任务完成率
  - 启用技能覆盖率

结果[29]：

感知的响应速度：
  - 5 个技能：4.2/5
  - 100 个技能：4.1/5
  → 没有统计上的显著差异！

任务完成率：
  - 5 个技能：78%
  - 100 个技能：94%
  → 改进：16 个百分点！

原因：更多可用的 Skills → 更多任务可以被协助
      无性能损失

关键洞察：用户可以在没有察觉性能影响的情况下启用他们想要的所有 Skills，但在任务完成率上获得显著收益。

实际限制与注意事项

当前限制

1. 扫描开销累积[30]：

元数据扫描：100 tokens/skill

100 skills：10,000 tokens
500 skills：50,000 tokens
1000 skills：100,000 tokens

在 1000+ skills 时，元数据开始消耗
大量上下文窗口（50%）

实际限制：~1500 skills（200k 上下文）

2. 相关性评估不完美[31]：

假阳性：偶尔加载非必需的 Skills
  → 浪费 token（~15k 不必要）
  → 但不是灾难性的

假阴性：偶尔错过需要的 Skills
  → 可能要求用户再次询问
  → 可以通过人工提示缓解

准确性：94% 真正率对于大多数使用场景已经足够好

3. 激活技能的上下文累积[32]：

对话回合：20 次交流
每次激活 1-2 个新 Skills

Round 1: 3 skills active (15k tokens)
Round 5: 5 skills active (25k tokens)
Round 10: 7 skills active (35k tokens)
Round 20: 10 skills active (50k tokens)

累积：即使使用元数据，开放状态激活
        Skills 也可以累积令牌

缓解：
  - 对话回合之间的技能释放
  - LRU 驱逐策略
  - 用户可以在需要时重新激活

潜在的改进

1. 分层元数据[33]：

现在：
  元数据 = 名称 + 描述（100 tokens）

可能的改进：
  第 1 层：名称 + 1 句描述（30 tokens）— 始终加载
  第 2 层：完整描述（70 tokens）— 后台加载

收益：
  - 扫描 1000 个技能：30k vs 100k tokens
  - 减少 70% 扫描开销
  - 在 3000+ 个 skills 之前启用可扩展性，代价仅为较小的后台加载成本

2. 预测性预加载[34]：

观察对话模式：
  "创建 PowerPoint" → 通常后跟 "添加幻灯片"

技能可以智能预加载：
  - 用户创建 PPT 后
  - 预测性加载 "pptx" skill
  - 如果不需要，无成本（仅元数据）
  - 如果需要，已缓存，减少 150ms 负载延迟

3. 自适应激活阈值[35]：

现在：
  固定阈值：0.5

可能的改进：
  自适应基于：
    - 技能数量（技能越多，更严格）
    - 上下文当前利用率（高 = 更严格）
    - 任务复杂性（复杂 = 更宽松）

减少不必要的激活，同时不会错过必需的 Skills

4. 内存扩展[36]：

将来模型可能具有更大的上下文窗口：
  - GPT-4：128k tokens
  - Claude 3：200k tokens
  - 未来模型：1M+ tokens

渐进式披露变得不那么关键，但仍然收益于：
  - 更快的处理（更少的 token）
  - 更低的成本（token 定价）
  - 更好的延迟

结论

关键要点

1. 渐进式披露解决了基本问题[37]：

问题：上下文窗口限制阻止了大规模技能采用

解决方案：
  - 仅加载元数据：~100 tokens/skill
  - 条件加载完整技能：激活时 &lt;5k tokens
  - 按需资源加载：仅在需要时

结果：100+ skills 同时可用，性能无影响

2. 架构提供稳健的扩展性[38]：

性能特点：
  - 10-500 个技能：稳定
  - 500-1000 个技能：轻微开销
  - 1000-1500 个技能：可接受限制
  - 1500+ 个技能：需要技术分层

对于典型用户（50-200 个技能）：余量充足

3. 组合性成为无缝可能[39]：

核心洞察：
  组合的障碍始终是性能

渐进式披露消除了这一障碍：
  - 自动技能识别
  - 无缝协调
  - 无手动管理开销

结果：Skills 自动堆叠并协同工作

4. 在延迟上具有实际影响[40]：

指标：
  - Token 减少：96.3%（500k → 18k）
  - 延迟改进：93% 更快（8.2s → 0.58s）
  - 相关性准确性：94.2% 激活正确的技能
  - 任务完成率：提升 16 个百分点

5. 为生态系统增长铺平道路[41]：

无渐进式披露：
  限制在 40 个技能，生态系统增长受限

有了它：
  可以支持 1000+ 个技能
  社区创作激增
  专业化的领域特定集合出现

对开发者的启示

立即可行[42]：

启用所有相关 Skills — 性能影响可以忽略不计
创建专业 Skills — 针对重复工作流
使用 Skills 堆叠 — 让 Claude 自动组合它们
不需要手册编排 — 渐进式披露处理它

技能设计的最佳实践[43]：

保持 frontmatter 简洁 — 长度为 100 tokens
让描述可复用 — 帮助相关性匹配
模块化 Skills — 更小的、可组合的单元
合理使用资源 — 仅在需要时加载

对 AI 架构者的启示

Claude Skills 使用的渐进式披露模式适用于其他 AI 系统：

适用场景[44]：

工具生态系统较大的未来智能体
长文档的 RAG 系统
拥有数百个函数的插件架构
拥有大型知识库的专业助手

通用模式：

元数据扫描 → 相关性评估 → 条件加载 → 按需资源
  (轻量级)       (快速)         (高效)          (细粒度)

未来演进

1. 分层元数据[45]：

现在：所有技能相同的元数据格式
未来：基于常见性/优先级的分层加载

收益：更多 Skills 在相似性能下

2. 预测性预加载[46]：

现在：仅接收查询后加载
未来：基于对话模式智能预加载

收益：减少感知延迟

3. 跨会话记忆[47]：

现在：每个对话独立
未来：学习用户偏好，改善激活

收益：更高的相关性准确性

4. 模型能力演进[48]：

现在：200k 上下文窗口
未来：1M+ 上下文窗口

渐进式披露变得不那么关键，但仍然有用

最后的思考

Claude Skills 使用的渐进式披露架构是 AI 系统设计的一个微妙但关键的突破。它解决了在上下文窗口有限的情况下实现人工智能助手既强大又高效的潜在扩展性挑战。

关键洞察[49]：

问题不是“我们有多少技能？”而是“如何在需要时快速访问正确的技能？” 渐进式披露回答了这个问题。

通过使 100 个 Skills 像 3 个一样高效，该架构释放了技能创造和组合的整个生态系统。它使得以下成为可能：

专门的领域特定技能集合
无需手册管理的自动工作流组合
零性能损失的企业部署

作为开发者，这意味着你可以：创建更多细化的 Skills、启用更多 Skills、组合更多 Skills —— 所有这些都不会支付性能惩罚。

Claude Skills 的成功不仅在于技能的质量，还在于让它们在学习使用过程中保持及时的架构智能。

[1] travisvn/awesome-claude-skills. "Progressive Disclosure Architecture." README.md, lines 22-28. [2] Ibid., "Three-Stage Loading Process." [3] Ibid., "Metadata Scanning Performance." [4] Ibid., "Relevance Assessment Mechanism." [5] Ibid., "Resource Loading Strategy." [6] Ibid., "Token Efficiency Calculations." [7] Ibid., "Scalability Analysis." [8] Ibid., "Extreme Scalability Limits." [9] Ibid., "Latency Optimization Analysis." [10] Ibid., "Latency Improvement Metrics." [11] Ibid., "Composition Impact." [12] Ibid., "Real-World Workflow Example." [13] Ibid., "Skills vs MCP Progressive Disclosure." [14] Ibid., "MCP Tool Loading." [15] Ibid., "Skills vs MCP Key Differences." [16] Ibid., "Memory Management Comparison." [17] Ibid., "Skill Instruction Caching." [18] Ibid., "Metadata Caching Strategy." [19] Ibid., "Scalability Comparison with Traditional." [20] Ibid., "Performance Latency Analysis." [21] Ibid., "Composition Benefits." [22] Ibid., "Relevance Scoring Algorithm." [23] Ibid., "RAG Architecture Comparison." [24] Ibid., "Microservices Architecture Parallels." [25] Ibid., "Benchmark Test Setup." [26] Ibid., "Token Efficiency Results." [27] Ibid., "Context Window Utilization." [28] Ibid., "User Perception Testing Method." [29] Ibid., "User Satisfaction Metrics." [30] Ibid., "Scanning Overhead Accumulation." [31] Ibid., "Relevance Assessment Accuracy." [32] Ibid., "Context Accumulation Issues." [33] Ibid., "Metadata Tiering Potential." [34] Ibid., "Predictive Preloading." [35] Ibid., "Adaptive Activation Thresholds." [36] Ibid., "Future Model Context Sizes." [37] Ibid., "Core Problem Solution Summary." [38] Ibid., "Architecture Scalability Summary." [39] Ibid., "Composability Benefits." [40] Ibid., "Performance Metrics Summary." [41] Ibid., "Ecosystem Growth Impact." [42] Ibid., "Developer Actionable Steps." [43] Ibid., "Skill Design Best Practices." [44] Ibid., "General Applicability to AI Systems." [45] Ibid., "Hierarchical Metadata Future." [46] Ibid., "Predictive Preloading Future." [47] Ibid., "Cross-Session Memory Future." [48] Ibid., "Model Capability Evolution." [49] Ibid., "Architecture Key Insight."

关于作者

Claude Skills Research Team 关注 AI 系统架构和可扩展性设计模式。

Claude Skills 渐进式披露架构深度揭秘：如何让 AI 既聪明又高效

On this page