Claude Code 渐进式披露（Progressive Disclosure）
·
Claude Code 渐进式披露（Progressive Disclosure）
0. 定位声明
适用版本：Claude Code（Agent Skills 功能，2025 年 10 月 16 日正式发布）
前置知识：
- 理解 LLM 上下文窗口（Context Window）的基本概念
- 了解 Claude Code 的基本使用方式（会写 CLAUDE.md 或使用 /plugin 命令）
- 对 YAML 语法有基础认知
不适用范围：
- 不覆盖 Claude API 的 Prompt Caching 机制（两者均属于上下文优化，但实现层不同）
- 不适用于 MCP（Model Context Protocol）服务端的工具注册机制（虽理念相通，但实现独立）
- 不覆盖 Claude.ai 网页端的对话管理
1. 一句话本质
给完全不懂 AI 的人的解释：
想象你雇了 100 位顾问，每人都带着一箱资料进会议室。传统做法是让所有人把资料全倒在桌上——桌子会被压垮。渐进式披露是：先让每人只亮出一张名片，你需要哪位顾问的详细资料，再让他打开箱子。
技术本质（三句话）：
- 是什么：渐进式披露是 Claude Code Agent Skills 系统中的一种上下文加载策略，将技能（Skill）的可发现性元数据与完整执行指令分层存储，按需加载。
- 解决什么问题：解决"技能数量 × 完整指令体积"所造成的上下文窗口溢出问题——100 个技能若全量加载需约 500,000 tokens，超出 Claude 的上下文限制。
- 怎么用：通过在
SKILL.md文件中分离 YAML Frontmatter（元数据层）和 Markdown 正文（指令层），加上外部资源文件（资源层），构成三层按需加载架构。
2. 背景与根本矛盾
历史背景
2025 年 10 月 16 日，Anthropic 正式发布 Agent Skills 系统，使 Claude Code 具备了可组合、可扩展的专项能力模块。然而这一功能的核心工程挑战早于发布日期就已被社区开发者预见：技能越多，AI 越笨——这是所有"工具丰富型 Agent"都会遭遇的上下文污染问题。
在 Agent Skills 发布前，社区开发者（如 Daniel Miessler 的 Kai 项目）已在用 Hooks 机制手工实现"按需注入上下文"的模式，与 Anthropic 内部的设计方向不谋而合。
根本矛盾（Trade-off）
可发现性（Discoverability） vs. 上下文效率（Context Efficiency）
越多的技能描述 → Claude 越聪明 越多 tokens 加载 → 响应越慢/溢出
| 极端选项 A | 极端选项 B |
|---|---|
| 全量加载所有技能指令 | 不加载任何技能描述 |
| Claude 知道所有工具，选择最优 | Claude 无从得知技能存在 |
| 100 技能 × 5000 tokens = 500K tokens（上下文溢出） | 0 tokens（能力为零） |
渐进式披露是这两个极端之间的帕累托最优解：以 ~100 tokens 的元数据成本换取对 1000+ 技能的可发现性，仅在决策发生后才加载完整指令。
3. 核心概念与领域模型
关键术语表
| 术语 | 费曼式定义 | 正式定义 |
|---|---|---|
| Skill（技能） | 一个装着说明书和工具的文件夹，告诉 Claude 如何完成某类特定任务 | 包含 SKILL.md 及可选脚本/资源的目录单元，通过 Prompt Expansion 方式扩展 Claude 能力 |
| Skill Tool（技能工具） | Claude 工具箱里的"导航仪"，告诉 Claude 现在有哪些技能可用 | 一个特殊的元工具（Meta-tool），其 description 字段在运行时动态聚合所有可用技能的名称与描述 |
| Frontmatter（前置元数据） | 技能名片：名字 + 一句话介绍 + 权限声明 | SKILL.md 头部的 YAML 块，包含 name、description、allowed-tools、version 等字段 |
| SKILL.md 正文 | 技能的完整说明书，详细告知 Claude 该如何行动 | 技能被激活后注入对话上下文的 Markdown 指令文本（通常 3,000–5,000 字） |
| 资源文件（Resources） | 技能需要时才取出来的工具箱（脚本、模板、参考文档） | 存放于 /scripts、/references、/assets 目录下，按需加载的辅助文件 |
| CLAUDE.md | 整个项目的"地图入口"，告诉 Claude 该项目有什么值得关注的 | 项目级别的渐进式披露入口文件，提供代码库高层摘要并指向相关技能或文档目录 |
| 上下文窗口（Context Window） | Claude 的"工作记忆"，同一时刻能看到的信息总量 | LLM 单次推理可处理的最大 token 数，Claude 3.5/3.7 系列约为 200K tokens |
领域模型
┌────────────────────────────────────────────────────────────────┐
│ Claude 的上下文窗口 │
│ │
│ ┌─────────────────────────────┐ ┌────────────────────────┐ │
│ │ Skill Tool（元工具） │ │ 对话历史 + 用户请求 │ │
│ │ │ └────────────────────────┘ │
│ │ "pdf": 创建和处理 PDF... │ │
│ │ "docx": 创建 Word 文档... │ ← Phase 1：仅元数据 │
│ │ "pptx": 制作演示文稿... │ （~100 tokens 扫描所有技能） │
│ │ ... (N 个技能的名片) │ │
│ └──────────────┬──────────────┘ │
│ │ Claude 决策：任务需要 "pptx" 技能 │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ SKILL.md 完整指令注入 │ ← Phase 2：完整指令 │
│ │ （约 3,000–5,000 tokens） │ （仅加载被激活的技能） │
│ └──────────────┬──────────────┘ │
│ │ 执行中需要外部脚本 │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ /scripts/render.py 等 │ ← Phase 3：按需加载资源 │
│ │ /references/spec.md 等 │ （仅在执行中实际需要时） │
│ └─────────────────────────────┘ │
└────────────────────────────────────────────────────────────────┘
核心实体关系：
Project（项目）
└── CLAUDE.md ←──── 渐进式披露的项目入口（Layer 0）
└── .claude/
└── skills/
└── my-skill/
├── SKILL.md ←── Layer 1（Frontmatter）+ Layer 2（正文）
├── scripts/
│ └── *.py ←── Layer 3（可执行资源）
├── references/
│ └── *.md ←── Layer 3（参考文档）
└── assets/
└── * ←── Layer 3（静态资源）
技能发现路径（扫描优先级）：
~/.config/claude/skills/（用户全局技能）.claude/skills/（项目级技能）- Plugin 提供的技能
- Claude Code 内置技能
4. 对比与选型决策
上下文管理策略横向对比
| 策略 | 扫描开销 | 激活精确度 | 扩展上限 | 适用场景 |
|---|---|---|---|---|
| 渐进式披露（Skills） | ~100 tokens/全量扫描 | LLM 语义推理（无确定性保证） | 理论 1000+ 技能 | 通用型多技能场景 |
| 全量预加载 | N × 5000 tokens | 100%（全部可用） | ~10–20 技能（受上下文限制） | 技能数量少且高频使用 |
| CLAUDE.md 手动索引 | 按文件大小（可控） | 依赖 Claude 阅读遵循率 | 无理论上限 | 项目特定知识，需精确控制 |
| MCP 工具注册 | 固定的工具描述 tokens | 算法路由（确定性） | 受工具描述总长限制 | 需要结构化 API 调用的能力 |
选型决策树
你的能力扩展需求是什么？
│
├─ 需要 Claude 执行确定性操作（调用 API、写文件）
│ └── → 使用 MCP 工具注册
│
├─ 需要跨项目可复用的专项知识/工作流
│ ├─ 技能数量 < 5 且每次几乎都用
│ │ └── → 直接写入 CLAUDE.md（无需 Skills 开销）
│ └─ 技能数量 > 5 或使用频率不确定
│ └── → 使用 Agent Skills + 渐进式披露
│
└─ 需要项目特定的上下文（框架版本、团队规范、已知坑）
└── → CLAUDE.md + 指向具体文档的 IMPORTANT 指令
⚠️ 关键选型警告
Vercel 的 Agent Evals 测试发现：在 56% 的测试用例中，技能从未被激活，在无显式指令的情况下，技能效果与基准线无差异。这意味着渐进式披露依赖 LLM 的语义匹配，不能提供确定性保证。对于业务关键路径，应优先考虑 CLAUDE.md 显式指令或 MCP 工具。
5. 工作原理与实现机制
静态结构
SKILL.md 文件结构（二段式）
---
# ── Frontmatter（配置层，控制 HOW）──────────────────────────
name: my-skill # 必填：技能唯一标识符
description: > # 必填：Claude 决策依据，越清晰越好
当用户需要做 X 时使用此技能。
适用场景：A、B、C。
version: 1.0.0 # 可选
license: MIT # 可选
allowed-tools: "Bash, Read, Write" # 可选：沙箱内允许的工具
model: claude-opus-4 # 可选：覆盖默认模型
---
# ── Markdown 正文（指令层，控制 WHAT）───────────────────────
## 目的
[说明技能解决什么问题]
## 执行步骤
[详细的、按顺序的操作指南]
## 质量标准
[输出应满足的条件]
## 参考资源
[如需深度上下文，引用 ./references/ 下的文件]
为什么选择这种数据结构？
- YAML Frontmatter：机器可解析，支持结构化提取，仅需加载头部即可获取元数据，无需解析全文
- Markdown 正文：Claude 在预训练数据中大量接触 Markdown，对其有最佳的语义理解，格式化开销最低
- 文件系统目录：利用操作系统原生的文件索引能力，无需额外数据库或注册表
Skill Tool 的动态描述生成（关键设计）
// 伪代码：Skill Tool 的 description 字段在运行时动态构建
function buildSkillToolDescription(availableSkills) {
const skillList = availableSkills.map(skill =>
`"${skill.name}": ${skill.description}`
).join('\n');
return `Use a skill to complete specialized tasks.\nAvailable skills:\n${skillList}`;
}
// Skill Tool 在 Claude 的工具列表中的呈现
{
type: "prompt",
name: "Skill",
description: buildSkillToolDescription(loadedSkills) // 动态生成！
}
这与 Read、Bash 等静态工具的本质区别在于：Skill Tool 的 description 字段是运行时动态聚合的，而非固定字符串。这是渐进式披露的入口机制。
动态行为：三阶段加载时序
用户请求 Claude Code 运行时 Claude LLM
│ │ │
│ 发送请求 │ │
├─────────────────────────────►│ │
│ │ │
│ Phase 1: 元数据扫描（~100 tokens） │
│ │ 扫描所有 SKILL.md Frontmatter│
│ ├──────────────────────────────►│
│ │ 注入：Skill Tool（含所有技能名片）
│ │◄──────────────────────────────┤
│ │ │
│ │ Claude 决策：需要哪个技能？ │
│ │◄─────────────────────────────►│
│ │ tool_use: Skill("my-skill") │
│ │◄──────────────────────────────┤
│ │ │
│ Phase 2: 完整指令加载（<5k tokens） │
│ │ 读取 SKILL.md 完整正文 │
│ ├──────────────────────────────►│
│ │ 注入：技能指令作为 user 消息 │
│ │◄──────────────────────────────┤
│ │ │
│ Phase 3: 按需加载资源（可选） │
│ │ 执行中需要 scripts/render.py │
│ ├──────────────────────────────►│
│ │ 文件内容注入上下文 │
│ │◄──────────────────────────────┤
│ │ │
│ │ Claude 执行任务并返回结果 │
│◄─────────────────────────────┤◄──────────────────────────────┤
关键实现细节：技能被激活后，其 SKILL.md 正文以 user 消息的形式注入对话上下文（而非 system prompt），这使得技能指令能在对话中按需追加，而无需修改系统级配置。这是"Prompt Expansion"而非"Function Calling"——技能准备 Claude，而非直接执行动作。
关键设计决策分析
决策 1：用 LLM 语义匹配替代算法路由
- 实际选择：技能选择完全依赖 Claude 的 LLM 推理，没有嵌入向量、分类器或正则匹配
- 为什么这样设计：算法路由需要预定义意图分类，扩展成本高；LLM 能理解自然语言描述中的语义，支持模糊匹配和上下文感知
- Trade-off：获得了灵活性和零维护的意图识别，付出了确定性保证（56% 的测试中技能未被激活）
决策 2：技能描述写入 Skill Tool 的 description 而非 system prompt
- 实际选择：所有技能元数据聚合到 Skill Tool 的 description 字段，而非散布在 system prompt 中
- 为什么这样设计：这样 Skill Tool 成为单一的发现入口，运行时可动态修改，与其他工具（Read/Bash）在结构上保持一致
- Trade-off：统一了工具访问模式，但使 Skill Tool 的 description 长度与技能数量线性相关
决策 3：文件系统作为技能注册表
- 实际选择：技能通过文件系统目录被发现，而非中央注册服务
- 为什么这样设计：无服务端依赖，离线可用，git 版本控制天然适配，符合"配置即代码"的工程文化
- Trade-off：获得了简洁性和可移植性，付出了全局搜索和去重的能力（不同路径下同名技能需人工管理）
6. 高可靠性保障
技能激活可靠性问题
渐进式披露的可靠性瓶颈集中在 Phase 1 → Phase 2 的转换率（即技能是否被正确激活）。
影响激活率的因素：
- description 字段的清晰度和触发关键词覆盖
- 用户请求的措辞方式（与 description 语义距离）
- 当前上下文中的干扰信号
- Claude 版本差异（不同版本的意图识别精度不同）
可观测性指标：
| 指标 | 含义 | 正常范围 | 告警阈值 |
|---|---|---|---|
| 技能激活率 | 相关任务中技能被调用的比例 | 44%–80%（依赖 description 质量） | < 30% 需优化 description |
| Phase 2 加载延迟 | 从技能被选中到指令注入完成的耗时 | 0.5–2 秒 | > 5 秒需检查文件大小 |
| 上下文窗口使用率 | 技能加载后的 token 消耗比例 | < 30%（3–5 个活跃技能时） | > 70% 需拆分技能 |
| SKILL.md 文件大小 | 单个技能指令文本体积 | 2,000–5,000 tokens | > 8,000 tokens 需重构 |
容灾策略
技能未激活的降级方案：
# CLAUDE.md 中的显式备用指令
IMPORTANT: 处理 PDF 相关任务时，首先读取 .claude/skills/pdf/SKILL.md
通过 CLAUDE.md 的 IMPORTANT 指令，可为关键技能提供显式触发备用路径，弥补语义匹配的不确定性。
7. 使用实践与故障手册
7.1 生产级 SKILL.md 配置示例
版本环境：Claude Code（2025 年 10 月发布，agent skills 功能）
---
name: api-doc-generator
description: >
当用户需要为 REST API 接口生成 OpenAPI 规范文档、Markdown 接口文档
或 API 测试用例时，使用此技能。适用场景：新增接口文档、存量接口补全、
接口变更同步文档。
version: 1.2.0
license: MIT
allowed-tools: "Read, Write, Bash"
# 不指定 model 字段，继承全局配置（推荐做法，避免版本硬编码）
---
## 目的
为代码库中的 REST API 接口自动生成标准化文档。
## 执行步骤
### 第一步：理解接口
1. 读取用户指定的控制器/路由文件
2. 识别 HTTP 方法、路径参数、请求体、响应结构
### 第二步：生成文档（选择格式）
- OpenAPI 3.0：使用 `./references/openapi-template.yaml` 作为模板
- Markdown：按照 `./references/api-doc-standard.md` 中的规范
### 第三步：验证
- 检查所有必填字段是否覆盖
- 确认示例请求/响应的数据类型正确
## 输出规范
- 文件命名：`{模块名}-api.{格式后缀}`
- 存放路径：`docs/api/`
- 版本注释：在文件头部注明生成时间和对应代码提交哈希
关键配置项说明：
| 字段 | 作用 | 默认值风险 |
|---|---|---|
description |
Claude 激活决策的唯一依据 | 模糊描述导致激活率 < 30% |
allowed-tools |
限制技能沙箱内可用工具 | 不设置则继承全局工具权限（安全风险） |
model |
覆盖任务使用的模型 | 不设置则用全局默认（推荐不设置） |
version |
技能版本追踪 | 无默认值，不设置则无法溯源变更 |
7.2 故障模式手册
【故障 1：技能从不激活】
- 现象：明显应该触发技能的任务，Claude 直接回答而不调用 Skill Tool
- 根本原因：description 字段与用户自然语言表达的语义距离过远，或 description 过于简短、缺乏触发关键词
- 预防措施：在 description 中列举 3–5 个典型触发场景，使用"当用户需要…"的句式，覆盖不同措辞变体
- 应急处理：在 CLAUDE.md 中添加
IMPORTANT: 处理 [场景] 时，请先读取 .claude/skills/[技能名]/SKILL.md
【故障 2：Phase 3 资源加载失败】
- 现象：技能被激活，但执行到需要脚本时报错"文件不存在"
- 根本原因：SKILL.md 正文中引用了相对路径，但 Claude 的工作目录与预期不符；或资源文件未随技能一起提交到版本库
- 预防措施：资源引用统一使用技能根目录的相对路径（如
./scripts/render.py），并在 CI 中验证文件完整性 - 应急处理：在技能指令中提供内联的简化版备用逻辑，避免硬依赖外部文件
【故障 3：上下文窗口因多技能激活而溢出】
- 现象：多个相关技能同时被激活，导致可用于任务执行的 tokens 严重不足，输出被截断
- 根本原因：技能设计粒度过粗，单个技能 SKILL.md > 8,000 tokens，且多个技能的触发条件存在重叠
- 预防措施：单个 SKILL.md 控制在 5,000 tokens 以内；通过 description 明确区分各技能的触发边界；将通用指令抽取到 CLAUDE.md
- 应急处理：临时将 CLAUDE.md 中的全局指令精简，为活跃技能释放上下文空间
【故障 4：when_to_use 字段行为异常】
- 现象：设置了
when_to_use字段，但行为与预期不一致 - 根本原因：
when_to_use字段在官方文档中未正式记录，属于未稳定 API（⚠️ 存疑），可能随版本变更 - 预防措施：将触发条件统一写在
description字段中，不使用when_to_use - 应急处理：将
when_to_use内容迁移合并入description
【故障 5：技能在 CI/CD 环境中不可用】
- 现象：本地开发时技能正常激活，但在 CI 环境的 Claude Code 实例中技能不存在
- 根本原因：技能存放在
~/.config/claude/skills/（用户全局路径）而非项目目录.claude/skills/ - 预防措施：生产和协作场景的技能统一使用项目级路径
.claude/skills/，并提交到代码仓库 - 应急处理：将技能目录从全局路径软链或复制到项目路径
7.3 边界条件与局限性
- 语义激活无确定性保证：在 Vercel 的评测中，56% 的测试用例中技能从未被激活；对于业务关键路径，不应依赖自动激活
- 技能数量与扫描质量的权衡：超过 ~50 个技能时，Skill Tool 的 description 字段可能超过 5,000 tokens，开始影响 Claude 的意图识别精度（⚠️ 存疑，缺乏公开测试数据）
- 并发不安全：Skills 系统当前不支持并发调用，多个技能的 context 注入存在竞态风险
context:fork隔离开销：使用context:fork在独立上下文中运行技能可避免污染主对话，但引入额外的 token 开销- 技能更新对运行中会话无效：修改 SKILL.md 后，需要开启新会话才能生效；长会话中的技能版本存在漂移风险
8. 性能调优指南
性能瓶颈识别
渐进式披露的性能瓶颈通常在以下层次之一：
Layer 0（CLAUDE.md）: 文件过大 → 每次会话启动消耗过多 tokens
Layer 1（Frontmatter 扫描）: 技能数量过多 → Skill Tool description 膨胀
Layer 2（SKILL.md 加载）: 单文件过大 → 激活单技能消耗过多 tokens
Layer 3（资源加载）: 资源文件过大/过多 → 执行阶段 context 溢出
调优步骤（按优先级）
Step 1：控制 CLAUDE.md 体积（优先级最高，每次会话必须加载）
- 目标：≤ 60 行 / ≤ 2,000 tokens
- 验证方法：
wc -l CLAUDE.md；使用 token 计数工具估算 - 方法：将详细规范移入 SKILL.md 或
./docs/，CLAUDE.md 只保留索引和 IMPORTANT 指令
Step 2：优化 description 字段（影响激活率和扫描效率）
- 目标：description 在 50–200 字内精确覆盖触发场景
- 验证方法：用 5–10 个代表性请求测试激活率，应 ≥ 70%
- 方法：使用"当用户需要…时，使用此技能"句式；列举 3 个不同措辞的触发场景
Step 3：拆分大型技能（>5,000 tokens 的 SKILL.md）
- 目标：单个 SKILL.md 正文 ≤ 5,000 tokens，通用内容迁移至资源文件（Phase 3 按需加载）
- 验证方法：激活技能后，检查剩余可用 context 是否 ≥ 50%
- 方法：将大型参考文档移入
./references/，在 SKILL.md 中用"如需详情请读取 ./references/xxx.md"引用
调优参数速查表
| 优化项 | 推荐值 | 警戒值 | 调整风险 |
|---|---|---|---|
| CLAUDE.md 行数 | ≤ 60 行 | > 100 行 | 减少内容需确保关键指令不丢失 |
| 单个 SKILL.md 大小 | 2,000–5,000 tokens | > 8,000 tokens | 拆分需重新测试激活覆盖率 |
| 项目级技能数量 | ≤ 20 个 | > 50 个（⚠️ 存疑） | 增加技能数需监控激活精度 |
| 用户全局技能数量 | ≤ 30 个 | > 100 个 | 过多可能导致 Skill Tool description 溢出 |
| 单次资源文件大小 | ≤ 10,000 tokens | > 30,000 tokens | 超大文件考虑分段加载或外部检索 |
9. 演进方向与未来趋势
方向 1：结构化技能路由（确定性激活）
当前基于 LLM 语义推理的激活机制存在不确定性，社区和 Anthropic 均在探索更精确的路由方案。潜在方向包括：引入 when_to_use 字段的正式标准化（目前属于未文档化特性），以及基于嵌入向量的语义相似度预过滤（Phase 0.5）——在 LLM 决策前先用轻量模型缩小候选集。
对使用者的影响：若确定性路由成熟，技能激活率将从 44%–80% 提升至 90%+，可将渐进式披露应用于更多业务关键场景。
方向 2：技能组合与依赖图（Skills Composition）
目前技能之间相互独立，但社区已出现技能组合模式（主技能声明依赖子技能）。Anthropic 的 skill-creator 技能中已包含对技能间关系的指导，预示官方可能引入正式的依赖声明语法。
对使用者的影响：复杂工作流（如"生成文档 → 翻译 → 发布"）将可封装为有依赖关系的技能链，进一步减少手工协调成本。
10. 面试高频题
【基础理解层】（考察概念掌握）
Q：什么是 Claude Code 的渐进式披露？为什么需要它？
A：渐进式披露是 Agent Skills 系统中的上下文分层加载策略。技能信息被分为三层：Frontmatter 元数据（约 100 tokens 扫描所有技能）、SKILL.md 完整指令（约 3,000–5,000 tokens，仅在技能被激活时加载）、外部资源文件（按需加载）。需要它是因为：若 100 个技能的完整指令全量加载，需 500,000 tokens，超出上下文窗口容量，系统无法运行。渐进式披露将固定扫描开销降至约 100 tokens，实现 96.3% 的 token 节省。
考察意图：验证候选人对 LLM 上下文窗口约束的理解，以及对"按需加载"设计模式的认知。
【原理深挖层】（考察内部机制理解）
Q：Skill Tool 的 description 字段为什么是动态生成的，而不是静态字符串？这背后的设计意图是什么？
A：Skill Tool 的 description 在运行时通过遍历所有已加载技能的 Frontmatter 动态拼接生成。这样做有两个关键意图：第一，实现"元数据-指令"解耦——Claude 在工具列表中只看到技能名片（元数据），指令内容不进入初始上下文，直到技能被显式激活；第二，支持运行时技能注册——新增技能无需修改任何硬编码配置，文件系统扫描后自动进入可发现集合。本质上，这是一个把"工具列表"变成"技能市场"的设计——Skill Tool 不是一个工具，而是所有技能的统一入口。
考察意图：考察候选人对"元工具"（Meta-tool）设计模式的理解，以及对运行时动态配置的工程直觉。
【生产实战层】（考察工程经验）
Q：你在生产项目中使用 Claude Code Skills 时发现技能激活率很低（约 30%），如何系统地诊断和优化？
A：分三步走：
- 诊断：收集 10–20 个"理应触发"该技能的真实请求，统计实际激活次数，确认问题规模。用不同措辞重述相同请求，观察哪些表达能触发激活，找出语义距离。
- 优化 description：将测试中成功触发的表达归纳成关键词，重写 description，明确列举触发场景（“当用户需要A/B/C时”），覆盖多种自然语言变体；将触发条件也作为 description 的一部分，而非使用未文档化的
when_to_use字段。 - 兜底策略：对业务关键路径，在 CLAUDE.md 中添加
IMPORTANT指令显式指向技能文件，绕过 LLM 语义匹配，提供确定性触发路径。同时接受语义激活的概率性本质，对激活率要求 > 90% 的场景改用 MCP 工具而非 Skills。
考察意图：考察候选人在真实工程约束下（LLM 不确定性）的问题诊断能力，以及在"理想方案"失效时的降级思维。
11. 文档元信息
验证声明
本文档内容经过以下验证：
✅ 三阶段加载机制、Skill Tool 动态描述：
参考 leehanchung.github.io 对 Claude Code 源码的逆向分析（2025-10-26）
✅ 性能数据（96.3% token 节省、93% 延迟改善）：
来源 skills.deeptoai.com 的架构分析文章（数据来源于 Superpowers 案例研究）
✅ 56% 技能未激活数据：
Vercel Agent Evals 测试，由 alexop.dev 引用（2026-01-18 文章）
✅ Agent Skills 发布日期（2025-10-16）：
travisvn/awesome-claude-skills 社区记录
⚠️ 以下内容未经本地环境验证，仅基于文档推断：
- 第 8 节"项目级技能数量 > 50 个时激活精度下降"：缺乏量化测试数据，标注 ⚠️ 存疑
- `when_to_use` 字段的完整行为：官方未文档化，本文描述基于社区逆向分析
- 第 3 节中"技能发现路径扫描优先级"：基于社区文档，未经官方确认
知识边界声明
本文档适用范围：
- Claude Code（Agent Skills 功能，2025-10-16 正式发布后）
- 本地开发环境及 CI/CD 集成场景
- Claude Sonnet / Opus / Haiku 系列模型
不适用场景：
- Claude API 直接调用（无 Skills 系统）
- Claude.ai 网页端（Skills 功能可用，但操作界面不同）
- Claude Desktop（支持 Skills 但安装方式不同，见官方文档）
参考资料
官方文档：
- Claude Code 概述：https://docs.claude.com/en/docs/claude-code/overview
- Agent Skills 官方文档：（需通过 docs.claude.com 搜索 "Agent Skills"）
核心分析文章：
- 第一性原理深度解析（含源码分析）：
https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/
- 渐进式披露架构性能分析：
https://skills.deeptoai.com/en/docs/development/progressive-disclosure-architecture
- CLAUDE.md 精简实践：
https://alexop.dev/posts/stop-bloating-your-claude-md-progressive-disclosure-ai-coding-tools/
社区资源：
- 技能市场（awesome-claude-skills）：
https://github.com/travisvn/awesome-claude-skills
- Medium 学习笔记（含目录结构图）：
https://medium.com/@quanap5/claude-code-progressive-disclosure-insights-from-my-learning-5244bc9864aa
- 社区案例（Daniel Miessler，预测性构建）：
https://danielmiessler.com/blog/i-built-two-claude-code-features-before-anthropic-released-them
如有纰漏或者错误，欢迎指正。
欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！
更多推荐
9
0- 0
已为社区贡献10条内容
所有评论(0)