<!-- title: Skill瘦身实战：渐进式披露三层加载法 -->

## 概述

本教程聚焦 Claude Code Skills 的核心设计原则——**渐进式披露（Progressive Disclosure）**。你将学会用三层加载架构把一个臃肿的巨型 Skill 重构为「骨架 + 按需加载」的结构，让 100 个常驻 Skill 只吃掉约 3000 Token，单个 Skill 触发时只加载必要内容。适合已经写过几个 Skill、但发现它们越来越臃肿、上下文成本失控的 Claude Code 中级用户。

## 前置条件

- 已安装 Claude Code（建议 v2.1.145+，支持 `${CLAUDE_SKILL_DIR}`、动态上下文注入等新特性）
- 会用任意编辑器写 Markdown，理解 YAML frontmatter
- 有一个可实验的 git 仓库
- 装了 `python3` 与 `git`（实战案例脚本依赖）

## 一、为什么「把所有内容塞进 SKILL.md」是反模式

很多初学者写 Skill 的第一反应是：把团队的代码审查规范、各种语言的 checklist、反面示例代码，一股脑全写进 `SKILL.md`。结果文件涨到 1500 行，每次触发就把一大坨内容灌进对话——**而官方文档明确指出：Skill 一旦加载，它的内容会跨轮次常驻上下文，每一行都是反复发生的 Token 成本。**

这是渐进式披露要解决的根本矛盾：**如何让几百个 Skill 同时可用，却不为「未使用的内容」消耗上下文。**

答案是一个三级层次结构，每一级只在需要时加载：

| 层级 | 内容 | 何时加载 | 体积目标 |
|------|------|----------|----------|
| Level 1 | YAML frontmatter（`name`、`description`） | 启动时常驻 | description < 200 字符最优（约 30 Token） |
| Level 2 | SKILL.md 正文 | 被触发时加载 | 目标 < 500 行 / < 1000 词 |
| Level 3 | `reference.md`、`scripts/`、`examples/` | Claude 按需读取 | 单文件无限制 |

关键直觉：**100 个安装的 Skill，Level 1 只消耗约 3000 Token（100 × 30），而完整的 Level 2 内容只加载给当前任务真正相关的那 1–3 个 Skill。** 把内容从 Level 2 推到 Level 3，就是把「常驻成本」变成「按需成本」。

## 二、第一层：用 description 当「门牌」，控制在 30 Token

启动时，Claude Code 会把**每一个**已安装 Skill 的 `name` 和 `description` 预加载进系统上下文。这意味着 description 不只是给人看的——它是 Claude 判断「现在该不该加载这个 Skill」的唯一依据。

description 的复合长度（description + when_to_use）在 Skill 列表里会被截断到 **1536 字符**。社区验证器给出的更激进的软目标是 **200 字符以内**，因为这能让 100 个 Skill 的常驻成本压到约 3000 Token。

写 description 的三条原则：

1. **把核心用例放最前面**——截断后仍要保留「这个 Skill 做什么」。
2. **写「何时用」，而不是「如何用」**——触发条件交给 description，操作步骤交给正文。
3. **避免营销词**——「强大」「智能」「全面」不传递任何触发信息。

```yaml
---
# ❌ 反模式：又长又空，前半句是废话
description: 这是一个非常强大和智能的代码审查 Skill，能够全面深入地分析各种语言的代码质量，帮助团队提升整体水平，适用于多种场景……

# ✅ 正模式：核心用例在前，触发条件在后，<200 字符
description: Review uncommitted changes against team conventions. Use when the user asks to review their diff, before committing, or wants a pre-PR quality check.
---
```

> **常见问题**：description 太短导致 Skill 不触发？补 `when_to_use` 字段，写入触发短语或示例请求，它会拼接到 description 后面参与匹配，但仍计入 1536 字符上限。

## 三、第二层：SKILL.md 正文只留「骨架与导航」

第二层是 Skill 被触发后才加载的正文。官方建议 **SKILL.md 控制在 500 行以内**，正文要「陈述做什么，而不是叙述怎么做、为什么」。

重构的核心动作是**把详细规则外迁到 Level 3 的 reference 文件，正文只保留：①任务步骤骨架 ②指向各 reference 的导航 ③必要的约束。**

下面是一个被重构后的 `code-review` Skill 目录结构：

```
code-review/
├── SKILL.md                      # 骨架 + 导航（~80 行）
├── reference/
│   ├── python-rules.md           # Python 团队规范（按需）
│   ├── typescript-rules.md       # TS 团队规范（按需）
│   └── security-checklist.md     # 安全审查清单（按需）
└── scripts/
    └── lint-diff.sh              # 确定性检查脚本（执行，不加载）
```

`SKILL.md` 示例：

```markdown
---
name: code-review
description: Review uncommitted changes against team conventions. Use when the user asks to review their diff, before committing, or wants a pre-PR quality check.
allowed-tools: Bash(git diff *) Bash(bash ${CLAUDE_SKILL_DIR}/scripts/*)
---

## 当前改动
!`git diff HEAD`

## 审查步骤
1. 按改动文件的主语言，加载对应规则文件
2. 逐条核对规则，标记违反点（文件:行号）
3. 运行 `bash ${CLAUDE_SKILL_DIR}/scripts/lint-diff.sh` 复核格式问题
4. 输出：问题清单 + 风险等级 + 修复建议

## 规则文件（按需加载）
- Python 改动 → 读 [reference/python-rules.md](reference/python-rules.md)
- TypeScript 改动 → 读 [reference/typescript-rules.md](reference/typescript-rules.md)
- 任何涉及鉴权/输入处理/密钥的改动 → 读 [reference/security-checklist.md](reference/security-checklist.md)

## 约束
- 只评论改动行，不重写未请求的代码
- 风险必须给出文件:行号定位
```

注意三件事：

- **`!`git diff HEAD``** 是动态上下文注入：Claude Code 在把正文发给 Claude 之前先执行命令，用真实 diff 输出替换这一行。Claude 看到的是实际改动，而不是命令本身——这是「让正文保持精简却仍基于真实数据」的关键手段。
- **`${CLAUDE_SKILL_DIR}`** 解析为 Skill 所在目录，无论 Skill 装在 personal / project / plugin 哪一级，脚本路径都正确。
- **正文里不再写规则细节**，只写「遇到 Python 改动就去读 python-rules.md」。规则文件只在真正需要时才进上下文。

## 四、第三层：reference 与 scripts 的按需加载

第三层是渐进式披露的「终局收益」所在：内容可以无限大，但默认**一个字符都不进上下文**，只有当 Claude 在执行任务时主动 `Read` 它们，才被加载。

### 4.1 reference 文件：放「详尽但低频」的内容

把那些「只在特定语言/特定场景才用得上」的大段规范拆出去。`reference/python-rules.md` 可以写到 300 行无妨——因为审查 TS 改动时，它永远不会被加载。

在 `SKILL.md` 里用相对路径链接引用它们，并在导航说明里写清「什么情况下读哪个文件」，Claude 才知道何时去加载。

### 4.2 scripts 文件：放「确定性的机器检查」

凡是能用脚本确定性判断的（格式、行尾、TODO 计数、禁用 API 扫描），就别让 Claude 用「理解」去猜——**脚本是「执行后看输出」，根本不占正文 Token。**

`scripts/lint-diff.sh` 示例：

```bash
#!/usr/bin/env bash
# 扫描暂存改动中的常见问题，输出 文件:行号:问题
set -euo pipefail
git diff --cached --unified=0 | grep -nE '^\+' \
  | grep -iE 'password|secret|api_key|TODO|FIXME' \
  | sed 's/^/suspect: /' || echo "no obvious issues"
```

`SKILL.md` 里通过 `allowed-tools: Bash(bash ${CLAUDE_SKILL_DIR}/scripts/*)` 预授权执行，免去逐次确认。

> **安全护栏**：若担心 Skill 里的 shell 注入有风险，可在 `settings.json` 设 `"disableSkillShellExecution": true`，所有 `!`cmd`` 会被替换为 `[shell command execution disabled by policy]`。注意它对 bundled / managed Skill 不生效——这是给企业 managed settings 用的。

## 五、压测对比：重构前后的 Token 经济学

用一个真实数字感受差异。假设团队有 5 个常用语言规范、总计 1400 行规则：

| 方案 | Level 1 常驻 | 触发后 Level 2+3 加载 | 审查一个纯 Python PR |
|------|-------------|----------------------|---------------------|
| 反模式（全塞 SKILL.md） | ~30 Token | **1400 行全部进上下文** | 加载了用不上的 TS/Go/Rust 规则 |
| 三层架构 | ~30 Token | SKILL.md 80 行 + python-rules.md | 只加载 Python 规则 |

更关键的是**自动压缩后的存活率**。官方文档说明：对话被压缩以释放上下文时，Claude Code 会重新挂接每个 Skill 最近一次的调用，**每个 Skill 只保留前 5000 Token**，且所有重新挂接的 Skill **共享 25000 Token 总预算**，从最近调用的开始填充。

也就是说：**你一次会话里加载的 Skill 越多、每个越大，老 Skill 越容易被压缩后整个丢弃。** 把正文做小，就是在压缩后给自己留命。

## 六、实战案例：把臃肿的 review-skill 重构成三层架构

### 步骤 1：建立目录骨架

```bash
mkdir -p ~/.claude/skills/review-standards/{reference,scripts}
cd ~/.claude/skills/review-standards
```

### 步骤 2：写瘦身的 SKILL.md

将上文第三节的 `SKILL.md` 内容保存到 `SKILL.md`。description 严格控制在 200 字符以内，正文只保留骨架与导航。

### 步骤 3：拆分规则文件

把原来堆在 SKILL.md 里的规则，按语言/场景拆成 `reference/python-rules.md`、`reference/typescript-rules.md`、`reference/security-checklist.md`。每个文件顶部写一句「适用场景」，方便 Claude 快速判断是否需要加载。

### 步骤 4：脚本化确定性检查

把 `scripts/lint-diff.sh` 写好并 `chmod +x`，在 SKILL.md 用 `allowed-tools` 预授权。

### 步骤 5：验证

在任意 git 仓库做一处小改动，启动 `claude`，问：

```
帮我审查一下当前的改动
```

**预期结果**：Claude 自动加载 `review-standards`（因为 description 匹配「review diff」），动态注入真实 diff，按改动语言只读取对应的 `reference/*.md`，运行 `lint-diff.sh`，输出带文件:行号的问题清单。

也可以直接调用：`/review-standards`。

**调试技巧**：如果 Claude 没有去读 reference 文件，说明正文里的「导航说明」不够明确——强化「遇到 X 改动 → 读 Y 文件」的措辞，或把关键约束直接写进正文。

## 七、整体工作流程图

```mermaid
flowchart TD
    A[启动 Claude Code] --> B[Level 1: 预加载所有 Skill 的 name+description<br/>约 30 Token/个]
    B --> C{用户提问}
    C -->|匹配某 Skill 的 description| D[Level 2: 加载该 Skill 的 SKILL.md 正文<br/>目标 < 500 行]
    C -->|不匹配| Z[正常对话, 无额外加载]
    D --> E[动态注入 !`git diff` 等真实数据]
    E --> F{任务需要细则?}
    F -->|是| G[Level 3: 按需 Read reference/*.md<br/>只加载相关语言规范]
    F -->|确定性检查| H[执行 scripts/*.sh<br/>只看输出, 不占正文 Token]
    G --> I[输出结果]
    H --> I
    D -.自动压缩.-> J[每 Skill 保留前 5000 Token<br/>共享 25000 Token 预算<br/>正文越小越容易存活]
    J --> C
```

## 八、控制「谁能调用」与「加载到哪里」

瘦身之外，还有两个 frontmatter 字段配合渐进式披露使用：

- **`disable-model-invocation: true`**：禁止 Claude 自动加载，只能用户手动 `/调用`。description 也不进常驻上下文——零常驻成本。适合 `/deploy`、`/send-message` 这类有副作用的动作。
- **`context: fork` + `agent: Explore`**：把 Skill 放进隔离的子代理上下文执行，Skill 正文成为子代理的 prompt，**完全不带主会话历史**，进一步隔离上下文消耗。适合「研究」「深度检索」类 Skill。

```yaml
---
name: deep-research
description: Research a topic thoroughly across the codebase.
context: fork
agent: Explore
---
研究 $ARGUMENTS：用 Glob/Grep 找文件 → 分析 → 带文件引用总结。
```

## 九、训练营适用性评估

- **适用类型**：Claude Code 中级实战训练营、企业 AI 工程化训练营（强调 Token 成本与可维护性）、Skill 工程化专题课。
- **教学时长**：约 90 分钟（30 分钟讲三层架构与 Token 经济学 + 45 分钟动手重构 + 15 分钟压测对比与答疑）。
- **前置衔接**：建议放在「Skill 入门（创建第一个 Skill）」之后、「Skill Evals 度量」之前，作为「让 Skill 可规模化」的承上启下章节。
- **学员产出**：每人交付一个从臃肿版重构为三层架构的 Skill，并附 Token 消耗对比报告。

## 延伸阅读

- **Skill 内容生命周期与自动压缩**：理解 5000 Token / 25000 Token 预算如何在长会话中影响 Skill 存活，是做瘦身的底层动机。
- **动态上下文注入与 `${CLAUDE_SKILL_DIR}`**：把「让 Claude 去猜」变成「让真实数据直接进 prompt」，是正文瘦身的同时保持质量的核心手段。
- **Skill 权限模型**：`allowed-tools` / `disallowed-tools` / `Skill(name)` 权限规则与 `skillOverrides`，决定瘦身后的 Skill 在团队中如何安全分发。
- **Bundled skills 源码**：阅读 `/code-review`、`/debug` 等官方 Skill 的 SKILL.md，是学习「骨架如何写得精炼」的最佳范本。

## 参考来源

1. [Extend Claude with skills — Claude Code Docs](https://code.claude.com/docs/en/skills) — 官方 Skill 开发权威文档，涵盖 frontmatter 字段全集、渐进式披露、动态上下文注入、生命周期与压缩预算
2. [Equipping agents for the real world with Agent Skills — Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Agent Skills 开放标准与「启动时预加载 name+description」设计动机
3. [Progressive Disclosure Architecture — DeepWiki (spences10/claude-skills-cli)](https://deepwiki.com/spences10/claude-skills-cli/2.1-progressive-disclosure-architecture) — 三层加载系统的 Token 经济学量化数据（30 / 680 Token、1000 词软目标）
4. [Claude Agent Skills Landing Guide — claudecn](https://claudecn.com/en/blog/claude-agent-skills-landing-guide/) — Skill 目录结构与 SKILL.md frontmatter 落地实践

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)