本教程聚焦 Claude Code Skills 的核心设计原则——渐进式披露（Progressive Disclosure）。你将学会用三层加载架构把一个臃肿的巨型 Skill 重构为「骨架 + 按需加载」的结构，让 100 个常驻 Skill 只吃掉约 3000 Token，单个 Skill 触发时只加载必要内容。适合已经写过几个 Skill、但发现它们越来越臃肿、上下文成本失控的 Claude Code 中级用户。
${CLAUDE_SKILL_DIR}、动态上下文注入等新特性）python3 与 git（实战案例脚本依赖）很多初学者写 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，就是把「常驻成本」变成「按需成本」。
启动时，Claude Code 会把每一个已安装 Skill 的 name 和 description 预加载进系统上下文。这意味着 description 不只是给人看的——它是 Claude 判断「现在该不该加载这个 Skill」的唯一依据。
description 的复合长度（description + when_to_use）在 Skill 列表里会被截断到 1536 字符。社区验证器给出的更激进的软目标是 200 字符以内，因为这能让 100 个 Skill 的常驻成本压到约 3000 Token。
写 description 的三条原则：
---
# ❌ 反模式：又长又空，前半句是废话
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 被触发后才加载的正文。官方建议 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 示例：
---
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 哪一级，脚本路径都正确。第三层是渐进式披露的「终局收益」所在：内容可以无限大，但默认一个字符都不进上下文，只有当 Claude 在执行任务时主动 Read 它们，才被加载。
把那些「只在特定语言/特定场景才用得上」的大段规范拆出去。reference/python-rules.md 可以写到 300 行无妨——因为审查 TS 改动时，它永远不会被加载。
在 SKILL.md 里用相对路径链接引用它们，并在导航说明里写清「什么情况下读哪个文件」，Claude 才知道何时去加载。
凡是能用脚本确定性判断的（格式、行尾、TODO 计数、禁用 API 扫描），就别让 Claude 用「理解」去猜——脚本是「执行后看输出」，根本不占正文 Token。
scripts/lint-diff.sh 示例：
#!/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 用的。
用一个真实数字感受差异。假设团队有 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 越容易被压缩后整个丢弃。 把正文做小，就是在压缩后给自己留命。
mkdir -p ~/.claude/skills/review-standards/{reference,scripts}
cd ~/.claude/skills/review-standards
将上文第三节的 SKILL.md 内容保存到 SKILL.md。description 严格控制在 200 字符以内，正文只保留骨架与导航。
把原来堆在 SKILL.md 里的规则，按语言/场景拆成 reference/python-rules.md、reference/typescript-rules.md、reference/security-checklist.md。每个文件顶部写一句「适用场景」，方便 Claude 快速判断是否需要加载。
把 scripts/lint-diff.sh 写好并 chmod +x，在 SKILL.md 用 allowed-tools 预授权。
在任意 git 仓库做一处小改动，启动 claude，问：
帮我审查一下当前的改动
预期结果：Claude 自动加载 review-standards（因为 description 匹配「review diff」），动态注入真实 diff，按改动语言只读取对应的 reference/*.md，运行 lint-diff.sh，输出带文件:行号的问题清单。
也可以直接调用：/review-standards。
调试技巧：如果 Claude 没有去读 reference 文件，说明正文里的「导航说明」不够明确——强化「遇到 X 改动 → 读 Y 文件」的措辞，或把关键约束直接写进正文。
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。---
name: deep-research
description: Research a topic thoroughly across the codebase.
context: fork
agent: Explore
---
研究 $ARGUMENTS：用 Glob/Grep 找文件 → 分析 → 带文件引用总结。
${CLAUDE_SKILL_DIR}：把「让 Claude 去猜」变成「让真实数据直接进 prompt」，是正文瘦身的同时保持质量的核心手段。allowed-tools / disallowed-tools / Skill(name) 权限规则与 skillOverrides，决定瘦身后的 Skill 在团队中如何安全分发。/code-review、/debug 等官方 Skill 的 SKILL.md，是学习「骨架如何写得精炼」的最佳范本。[!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 等场景全覆盖。