释题：循序渐进。想象一下一本 500 页的手册，通过目录页、章节、附录三层结构，我们可以把 token 利用率提升 98%。—— 这就是循序渐进的内涵。本节中隐藏了三个神秘关键词：目录、路由和契约。你可以在阅读中，自己寻找并体会这三个关键词的内涵。你好，我是黄佳。 前两讲我们学习了 SKILL.md 的基本结构（第 9 讲）和任务型 Skills 的设计方法（第 10 讲），也理解了 Skills 在 Agent 生态中的核心定位—— **可操作知识** 。但真实场景中，专业能力往往很复杂，比如一个财务分析 Skill，它需要包含财务指标计算公式、不同行业的基准数据、各种报表模板、分析脚本以及案例示例。 如果把这些全部塞进一个 SKILL.md，会有两个问题。
- Token 爆炸：每次激活都要加载几千 tokens。
- 信息噪声：用户问“收入增长率怎么算”，Claude 却要阅读关于成本分析、现金流、资产负债表的全部内容。
渐进式披露（Progressive Disclosure ，也即是渐进式的加载啦 ） 就是解决这个问题的架构模式。但渐进式披露的意义远不止节省 token。从企业本体论的视角看，它是 知识管理（Knowledge Management）在 AI 架构中的技术映射 ——如何让正确的知识在正确的时刻到达正确的执行者手中。 这一课干货内容极多，思考题也多，请大家做好头脑被新知识冲击的准备。我们开始了。
渐进式披露的设计哲学
让我们用图书馆来类比渐进式披露的设计哲学。走进一个图书馆找资料时，你不会一次把所有书都读一遍。你是先看目录找到相关分类，再选一本具体的书，最后翻到需要的章节深入阅读。信息是逐层展开的，而不是一次性全部载入大脑。
Skill 的渐进式披露设计也是一样：第一层只扫描 description 作为“目录”，第二层在触发时加载 SKILL.md 主文件作为“章节”，第三层再按需加载被引用的具体文件作为“附录”。结构化分层替代信息堆叠，让系统在规模变大时依然高效、可控。
认知经济学：上下文窗口是稀缺资源
在讨论 token 节省之前，让我们建立一个更深层的认知框架。
上下文窗口是 LLM 的“工作记忆”。 人类的工作记忆大约能同时处理 7±2 个信息块（Miller’s Law）。LLM 的上下文窗口虽然大得多（200K tokens），但它也是 有限的稀缺资源 ，而且有一个更严重的问题—— 注意力稀释效应。
这就是渐进式披露的经济学基础：
渐进式披露的本质 ：以最小的 token 投入获得最高的任务完成质量——这就是知识的 投资回报率（Knowledge ROI） 。
Token 节省效果方面。让我们用数字说话。假设一个复杂的 Skill 是这样的：
不同场景下的 Token 消耗（大概估算哈）。
不难发现，大多数请求只需要部分资源，渐进式披露在这些场景下大幅节省 tokens。
财务分析 Skill：三层架构详解
我们今天要设计的这个财务分析 Skill，本质上是一个结构化的财务能力包：当用户提出与收入、成本、利润、增长率、毛利率、ROE/ROA 或整体财务表现相关的问题时，它会被激活，先在主文件中完成问题识别和分析路径判断，再按需加载对应的公式说明、行业基准数据或报告模板，必要时调用脚本进行确定性计算，最后输出结构清晰、口径一致的分析结果。
它的目标不是给投资建议，而是在明确数据前提下，提供可复现、可解释、可结构化的财务分析支持，用最少的上下文投入完成高质量的专业判断。
下面来看看这个Skill的三层渐进式的架构设计，我们用看书时经常采用的目录、章节、附录来对渐进式架构做类比。
层级 1：目录页（Entry Point）
这是 Skills 系统扫描阶段读取的内容—— 只有 description 。
---
name: financial-analyzing
description: Analyze financial data, calculate ratios, and generate reports. Use when the user asks about revenue, costs, profits, margins, financial metrics, or needs financial analysis.
---
目录页的设计原则是，description 足够丰富，让 Claude 能准确判断相关性。但不要太长，因为 所有 Skill 的 description 共享 15,000 字符的总预算 。如果 Skill 数量多导致 description 被截断，可以通过 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量调整。
层级 2：章节（Main Content）
章节指的是SKILL.md 的正文部分—— 激活后才加载 。
## Financial Analysis Skill
### Quick Start
基础的财务分析流程...
### Available Analyses
#### Revenue Analysis
For detailed formulas, see `reference/revenue.md`
#### Cost Analysis
For detailed formulas, see `reference/costs.md`
#### Profitability Analysis
For detailed formulas, see `reference/profitability.md`
### When to Load Additional Resources
- 需要具体公式 → 加载对应的 reference/*.md
- 需要行业基准 → 加载 data/benchmarks.json
- 需要报告模板 → 加载 templates/*.md
这一部分的设计原则是主文件提供“路线图”，通过文件引用指向详细内容，然后Claude 根据用户请求决定加载哪些具体内容。
层级 3：附录（On-Demand Resources）
只有当 SKILL.md 中引用了这些文件，Claude 才会去读取这一类文件。
.claude/skills/financial-analyzing/ # 标准 Skill 目录
├── SKILL.md # 主文件（总是加载）
├── reference/ # 参考资料
│ ├── revenue.md # 收入分析公式
│ ├── costs.md # 成本分析公式
│ └── profitability.md # 盈利分析公式
├── templates/ # 报告模板
│ ├── quarterly_report.md
│ └── annual_report.md
├── data/ # 数据文件
│ └── industry_benchmarks.json
└── scripts/ # 分析脚本
├── calculate_ratios.py
└── generate_report.sh
这一部分内容的设计原则是文件名要有描述性（revenue.md 而非 ref1.md）——Claude 根据文件名判断是否需要加载。
所有辅助文件都在 Skill 自己的目录内，随 Skill 一起分发。相关内容放在一起，并按功能域组织子目录。例如脚本有自己独立存放的目录，Claude 可以执行它，但不需要去“理解”（这样也就节省了Token）。
财务分析 Skill：项目设计细节
下面我们还原这个财务分析Skill的构建细节，从零构建一个完整的财务分析 Skill。
这个Skill标准部署结构如下：
your-project/.claude/skills/financial-analyzing/
├── SKILL.md # 主 Skill 文件
├── reference/
│ ├── revenue.md # 收入分析
│ ├── costs.md # 成本分析
│ └── profitability.md # 盈利分析
├── templates/
│ └── analysis_report.md # 分析报告模板
└── scripts/
└── calculate_ratios.py # 比率计算脚本
课程示例文件在 .claude/skills/financial-analyzing/ 中。
主文件SKILL.md设计如下。
---
name: financial-analyzing
description: Analyze financial data, calculate financial ratios, and generate analysis reports. Use when the user asks about revenue, costs, profits, margins, ROI, financial metrics, or needs financial analysis of a company or project.
allowed-tools:
- Read
- Grep
- Glob
- Bash(python:*)
---
## Financial Analysis Skill
You are a financial analyst. Help users analyze financial data, calculate key metrics, and generate insightful reports.
### Quick Reference
| Analysis Type | When to Use | Reference |
|--------------|-------------|-----------|
| Revenue Analysis | 收入、营收、销售额相关 | `reference/revenue.md` |
| Cost Analysis | 成本、费用、支出相关 | `reference/costs.md` |
| Profitability | 利润、毛利率、净利率相关 | `reference/profitability.md` |
### Analysis Process
#### Step 1: Understand the Question
- What financial aspect is the user asking about?
- What data do they have available?
- What format do they need the answer in?
#### Step 2: Gather Data
- Request necessary financial data from user
- Or read from provided files/sources
#### Step 3: Calculate Metrics
For specific formulas and calculations:
- Revenue metrics → see `reference/revenue.md`
- Cost metrics → see `reference/costs.md`
- Profitability metrics → see `reference/profitability.md`
To run calculations programmatically:
```bash
python scripts/calculate_ratios.py <data_file>
### Step 4: Generate Report
Use the template in `templates/analysis_report.md` for structured output.
## Output Guidelines
1. Always show your calculations
2. Explain what each metric means
3. Provide context (industry benchmarks when available)
4. Give actionable recommendations
## Important Notes
- Never make up financial data
- Ask for clarification if data is incomplete
- Flag any unusual numbers that might be errors
这个Skill包括一个Quick Reference 表格，让 Claude 快速定位需要哪个参考文件。使用相对路径指向资源，进行清晰的文件引用，并通过脚本调用说明告诉 Claude 如何使用计算脚本。同时只允许 Read、Grep、Glob 和特定的 Bash 命令。
仔细观察上面的 SKILL.md 设计，你会发现它本质上是一个 路由器 ——根据用户请求的类型，将 Claude 导向不同的资源文件：
用户请求 → SKILL.md（路由判断） → 目标资源
│
├─ "收入相关" → reference/revenue.md
├─ "成本相关" → reference/costs.md
├─ "利润相关" → reference/profitability.md
├─ "要报告" → templates/analysis_report.md
└─ "要计算" → scripts/calculate_ratios.py
这个路由的 关键设计技巧 是 Quick Reference 表格。它用最少的 token（3 行表格 ≈ 50 tokens）告诉 Claude 五个方向的路由。如果没有这个表格，Claude 需要阅读整个 SKILL.md 的 Step 3 才能知道“收入问题去找 revenue.md”——这就是 信息密度 的差异。
写好路由表格的经验法则包括。
- 用“用户可能说的关键词”作为路由条件（而非“文件内容的技术名称”）
- 每个路由条目一行，不要超过 10 个条目（超过就需要分层）
- 高频路由放前面
除主文件之外，这个Skill中还包括下面几个参考文件，也就是附录。
参考文件：reference/revenue.md
这是渐进式披露的 层级 3 资源 ——只有当用户问到收入相关问题时，Claude 才会根据 SKILL.md 中 Quick Reference 表格的路由指引加载这个文件。它包含收入增长率、同比/环比、ARPU 等核心公式和异常信号判断标准。
# Revenue Analysis Reference
## Key Metrics
### Revenue Growth Rate
Revenue Growth Rate = (Current Period Revenue - Previous Period Revenue) / Previous Period Revenue × 100%
**Interpretation:**
- > 20%: High growth
- 10-20%: Moderate growth
- < 10%: Low growth
- < 0%: Declining
### Year-over-Year (YoY) Growth
YoY Growth = (This Year Revenue - Last Year Revenue) / Last Year Revenue × 100%
### Quarter-over-Quarter (QoQ) Growth
QoQ Growth = (This Quarter - Previous Quarter) / Previous Quarter × 100%
## Revenue Composition Analysis
### Revenue by Product/Service
Product Revenue Share = Product Revenue / Total Revenue × 100%
### Revenue by Region
Regional Revenue Share = Regional Revenue / Total Revenue × 100%
## Average Revenue Metrics
### Average Revenue Per User (ARPU)
ARPU = Total Revenue / Number of Users
### Average Revenue Per Account (ARPA)
ARPA = Total Revenue / Number of Accounts
## Red Flags to Watch
1. **Revenue concentration** > 30% from single customer
2. **Declining growth rate** over 3+ consecutive quarters
3. **Large discrepancy** between booked and recognized revenue
4. **Unusual seasonality** patterns
参考文件：reference/profitability.md
这是与 revenue.md 平级的另一个按需加载文件，聚焦盈利能力分析。包含毛利率、营业利润率、净利率三大 Margin 指标，以及 ROI、ROA、ROE 三大 Return 指标，并附带行业基准数据供对比参考。
# Profitability Analysis Reference
## Margin Metrics
### Gross Profit Margin
Gross Margin = (Revenue - Cost of Goods Sold) / Revenue × 100%
**Industry Benchmarks:**
| Industry | Typical Range |
|----------|--------------|
| Software/SaaS | 70-85% |
| Retail | 20-50% |
| Manufacturing | 25-35% |
| Services | 50-70% |
### Operating Profit Margin
Operating Margin = Operating Income / Revenue × 100%
Operating Income = Revenue - COGS - Operating Expenses
### Net Profit Margin
Net Margin = Net Income / Revenue × 100%
Net Income = Revenue - All Expenses - Taxes
## Return Metrics
### Return on Investment (ROI)
ROI = (Gain from Investment - Cost of Investment) / Cost of Investment × 100%
### Return on Assets (ROA)
ROA = Net Income / Total Assets × 100%
### Return on Equity (ROE)
ROE = Net Income / Shareholders’ Equity × 100%
## Profitability Red Flags
1. **Gross margin declining** while revenue grows (pricing pressure)
2. **Operating margin < 0** (not operationally profitable)
3. **ROE significantly higher than ROA** (high leverage risk)
4. **Net margin < industry average** for 3+ years
报告模板：templates/analysis_report.md
模板文件是渐进式披露中的特殊资源——它不提供“知识”，而是提供“输出格式”。当用户要求“生成分析报告”时，Claude 加载这个模板来确保输出结构统一、专业。这就是企业知识管理中“标准化输出”的技术映射。
# Financial Analysis Report Template
## Executive Summary
[One paragraph summarizing key findings and recommendations]
## Company/Project Overview
- **Name**: [Entity name]
- **Period Analyzed**: [Date range]
- **Data Sources**: [Where data came from]
## Key Metrics
| Metric | Value | Industry Avg | Assessment |
|--------|-------|--------------|------------|
| Revenue Growth | X% | Y% | Above/Below |
| Gross Margin | X% | Y% | Above/Below |
| Net Margin | X% | Y% | Above/Below |
| ROI | X% | Y% | Above/Below |
## Detailed Analysis
### Revenue Analysis
[Findings about revenue trends, composition, growth]
### Cost Analysis
[Findings about cost structure, efficiency]
### Profitability Analysis
[Findings about margins, returns]
## Trend Analysis
[How metrics have changed over time]
## Recommendations
### Immediate Actions
1. [High priority recommendation]
2. [High priority recommendation]
### Medium-term Improvements
1. [Medium priority recommendation]
### Long-term Strategy
1. [Strategic recommendation]
## Risk Factors
- [Key risk 1]
- [Key risk 2]
## Appendix
[Supporting calculations, data tables, charts]
计算脚本：scripts/calculate_ratios.py
脚本是 Skills 与 Tools 的桥梁——它把“知识”（公式）变成了“行动”（代码）。Claude 不需要理解计算逻辑，只需执行 python calculate_ratios.py data.json 即可获得准确结果。这比让 LLM 自己做数学运算更可靠、更省 token。
#!/usr/bin/env python3
"""
Financial Ratios Calculator
Usage:
python calculate_ratios.py <data_file>
Data file format (JSON):
{
"revenue": 1000000,
"cogs": 400000,
"operating_expenses": 300000,
"net_income": 150000,
"total_assets": 2000000,
"shareholders_equity": 800000,
"previous_revenue": 900000
}
"""
import json
import sys
def calculate_ratios(data):
"""Calculate common financial ratios."""
ratios = {}
# Revenue Growth
if 'previous_revenue' in data and data['previous_revenue'] > 0:
ratios['revenue_growth'] = (
(data['revenue'] - data['previous_revenue'])
/ data['previous_revenue'] * 100
)
# Gross Margin
if 'cogs' in data:
gross_profit = data['revenue'] - data['cogs']
ratios['gross_margin'] = gross_profit / data['revenue'] * 100
# Operating Margin
if 'cogs' in data and 'operating_expenses' in data:
operating_income = data['revenue'] - data['cogs'] - data['operating_expenses']
ratios['operating_margin'] = operating_income / data['revenue'] * 100
# Net Margin
if 'net_income' in data:
ratios['net_margin'] = data['net_income'] / data['revenue'] * 100
# ROA
if 'net_income' in data and 'total_assets' in data:
ratios['roa'] = data['net_income'] / data['total_assets'] * 100
# ROE
if 'net_income' in data and 'shareholders_equity' in data:
ratios['roe'] = data['net_income'] / data['shareholders_equity'] * 100
return ratios
def main():
if len(sys.argv) < 2:
print("Usage: python calculate_ratios.py <data_file>")
sys.exit(1)
with open(sys.argv[1], 'r') as f:
data = json.load(f)
ratios = calculate_ratios(data)
print("\n=== Financial Ratios ===\n")
for name, value in ratios.items():
print(f"{name.replace('_', ' ').title()}: {value:.2f}%")
if __name__ == '__main__':
main()
上述这些参考文件、脚本会按需进行引用。
渐进式加载实战演示
让我们看看用户不同请求时，Skill 是如何渐进式加载的。
首先，先介绍一个技巧，在会话内部，你可以通过/context 命令来查看当前所消耗的Token和上下文内存的具体情况。
下面我们再来比较不同的渐进式加载情景。
场景 1：简单问题
用户 ：毛利率怎么计算？
Claude 加载过程 ：
- 扫描 Skills → 发现
financial-analyzing匹配 - 加载 SKILL.md → 看到 “Profitability → see
reference/profitability.md” - 加载
reference/profitability.md→ 找到毛利率公式 - 回答用户
Token 消耗 ：~100（扫描）+ 800（主文件）+ 600（profitability.md 部分）= ~1500 tokens
其他文件（revenue.md、costs.md、templates、scripts） 完全没有加载 。
如图所示，此时，Claude只读取了 .claude/skills/financial-analyzing/reference/profitability.md这一个文件的83行。
场景 2：完整分析
用户 ：帮我分析data目录中的财务数据，生成一份完整的分析报告。
Claude 加载过程 ：
- 扫描 Skills，发现
financial-analyzing匹配 - 加载 SKILL.md
- 分析任务需要，加载所有 reference/*.md
- 需要报告格式，加载 templates/analysis_report.md
- 需要计算 ，执行 scripts/calculate_ratios.py
Token 消耗 ：全部资源都用到了。
两个场景的关键对比如下。
由此我们可以看出渐进式披露的价值：大部分请求只需要部分资源，平均节省 50-80% tokens。
渐进式的设计模式与最佳实践
首先谈 文件组织模式 ，有按功能分类和按使用频率分类两种。如果你的 Skill 有多种类型的资源（知识+模板+脚本），用功能分类；如果只有不同深度的知识文档，用频率分类。
按功能分类（推荐）：
.claude/skills/my-skill/
├── SKILL.md # 入口 + 路由（< 500 行）
├── reference/ # 知识库（公式、规范、基准）
├── templates/ # 输出模板（报告、代码骨架）
├── examples/ # 示例集（输入输出样本）
├── scripts/ # 可执行脚本（计算、生成、验证）
└── data/ # 静态数据（JSON、CSV）
按使用频率分类（适合知识型 Skill）：
.claude/skills/my-skill/
├── SKILL.md # 核心内容（高频，总是加载）
├── QUICKREF.md # 快速参考（高频，常被加载）
├── DETAILED.md # 详细说明（中频，按需加载）
└── ADVANCED.md # 高级用法（低频，很少加载）
其次是 主文件设计原则 。主文件应该控制在 500 行以内 （官方建议：Keep SKILL.md under 500 lines. Move detailed reference material to separate files.）。然后应该提供路线图，用 Quick Reference 表格做个快速路由，而非让 Claude 逐行扫描。
什么内容放主文件，什么内容放引用文件？答案是 高频内容内联，低频内容外链。 最常用的信息直接放在主文件（80/20 法则——80% 请求只需 20% 内容）；偶尔用到的详细信息放在引用文件，用契约式引用。
此时终于说到本文第三个神秘关键字了。到底啥是 契约式引用 ？ SKILL.md 引用辅助文件时，不要只写一个路径——要写一个 契约 ，让 Claude 知道什么时候该加载、加载后能得到什么：
# ❌ 弱引用（Claude 不知道何时该加载）
See `reference/revenue.md` for more details.
# ✅ 契约式引用（Claude 清楚加载条件和预期内容）
## Revenue Analysis
When the user asks about revenue growth, ARPU, or revenue composition:
→ Load `reference/revenue.md` for calculation formulas and industry benchmarks
契约式引用三要素包括：
- 触发条件 ：什么情况下应该加载（“当用户问到 X 时”）
- 文件路径 ：去哪里找
- 内容预期 ：加载后能得到什么（“计算公式和行业基准”）
这和第 6 讲子代理流水线中的“交接契约”是同一个工程思想： 下游消费者需要知道上游提供什么，而不只是知道上游在哪里。
引用文件命名也有所讲究，要清晰，切忌模糊，重复。
# 好的命名
reference/revenue.md # 清晰表明内容
reference/profitability.md # 清晰表明内容
templates/quarterly_report.md # 清晰表明用途
# 差的命名
reference/ref1.md # 不知道是什么
docs/misc.md # 太模糊
file.md # 毫无信息
脚本适合封装 复杂但确定性的逻辑 。脚本的好处是 Claude Code可以直接执行它，而不需要“理解”“每一行代码，因此可以减少 Token 消耗（不需要把逻辑放在 prompt 中），便于测试和维护（独立的代码文件）。
# 适合脚本
- 财务比率计算（公式固定）
- 数据格式转换（规则明确）
- 文件批量处理（重复性高）
# 不适合脚本
- 开放性分析（需要判断）
- 创意性任务（需要灵活性）
- 交互式决策（需要反馈）
脚本不仅能做计算，还能 生成可视化结果 。Claude官方提供了一种强大的模式：Skill 中的脚本生成交互式 HTML 文件，在浏览器中打开。
用户请求 → Skill 激活 → Claude 执行脚本 → 生成 HTML → 浏览器打开
下面是一个代码库可视化 Skill的示例。
.claude/skills/codebase-visualizer/
├── SKILL.md # 指令：调用 visualize.py
└── scripts/
└── visualize.py # 生成交互式目录树 HTML
SKILL.md 只需要告诉 Claude 运行脚本：
---
name: codebase-visualizer
description: Generate an interactive tree visualization of your codebase. Use when exploring a new repo or understanding project structure.
allowed-tools: Bash(python *)
---
Run the visualization script from your project root:
\```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .
\```
This creates `codebase-map.html` and opens it in your default browser.
这个示例的工程价值在于，Claude 不需要理解 HTML/CSS/JS 的实现细节（节省 token），脚本用 Python 标准库即可，无需安装额外依赖。同样的模式还能用于依赖关系图、测试覆盖率报告、API 文档、数据库 schema 可视化。
这体现了渐进式披露的极致——Claude 只需要知道“运行什么命令”（10 tokens），而非“如何生成 HTML”（2000+ tokens）。
内容拆分的工程方法论
学完了架构和实战，我们来解决一个更根本的问题：面对一坨知识， 怎么决定什么放 SKILL.md、什么放引用文件、什么放脚本？
请看下面的知识拆分决策树。
这棵树背后真正体现的，是 核心语义内联，确定逻辑外包，结构独立，数据延迟，示例分离 等大原则 。
当你按照这个思路拆分 Skill，你构建的就不再是一份长文档，而是一套有层级的能力结构。这也是渐进式加载能够真正发挥作用的前提。
官方建议 SKILL.md 控制在 500 行以内 。为什么是 500 行？
- 500 行 ≈ 2000-3000 tokens ，是一个 Skill 激活后的合理上下文开销。
- 加上 Claude 自身的系统提示和对话上下文，总 token 数保持在可控范围。
- 超过 500 行意味着你可能把“参考资料”混进了“路由指令”。
超过 500 行时的重构信号和对策如下：
拆分决策树和目录结构不是随意设计的——它们映射到 企业知识管理的经典范式。
想想看，上面这个映射的工程启示有哪些？
- SKILL.md = 部门 SOP 首页 。好的 SOP 首页不会把所有操作细节都列出来——它提供概览和导航，让使用者快速找到需要的章节。SKILL.md 的 Quick Reference 表格就是这个导航。
- reference/ = 知识库 。企业知识库的特点是内容丰富但使用频率低，按需查阅而非每次通读。Skill 的 reference 文件同理——只有 Claude 判断需要时才加载。
- templates/ = 标准化输出 。企业用模板确保报告、邮件、文档的格式一致。Skill 的模板同理——Claude 不需要每次都“创造”一个报告格式。
- scripts/ = 自动化工具 。企业用脚本和工具自动化重复性操作。这里的关键洞察是， 脚本把“知识”变成了“行动“ ——它是 Skills（知识层）和 Tools（行动层）的桥梁。
这引出了一个重要话题：Skills 和 Tools 到底是什么关系？它们如何协作？下面继续探讨。
Skills 与 Tools 的本质关系
在第 9 讲对Skill进行定义的环节中，我们曾初步区分了 Skills（“经验”）和 Tools（“手”）。现在，让我们深入分析它们之间的三种协作模式。
第一层关系是 Skills 约束 Tools， Skills 通过 allowed-tools 约束 Tools ， 实现 最小权限原则 。
allowed-tools:
- Read # 允许读取
- Grep # 允许搜索
- Glob # 允许查找
# 没有 Write、Edit、Bash → 不允许修改
这不是简单的权限控制——这是 知识约束行动 的范式。一个代码审查 Skill “知道”审查只需要看代码不需要改代码，所以它只给 Claude 只读工具。一个文档生成 Skill “知道”需要创建新文件但不应修改旧文件，所以它给 Write 但不给 Edit。
第二层关系是 Skills 编排 Tools 。Skill 中的 scripts/ 目录存放的脚本，本质上是 预编译的 Tool 调用序列 。
# scripts/calculate_ratios.py
# 这个脚本 = Read(data_file) + 计算逻辑 + Print(results)
# Claude 不需要理解计算逻辑，只需要：
# 1. Bash("python scripts/calculate_ratios.py data.json")
# 2. 读取输出结果
没有脚本时，Claude 需要自己组合多个 Tool 调用来完成任务：
手动编排（没有脚本）：
1. Read(data.json) → 获取数据
2. Claude 内部计算 → 消耗推理 token
3. 可能出错 → 需要多轮修正
有脚本时，Claude 只需一次 Tool 调用：
脚本编排（有脚本）：
1. Bash(python calculate.py data.json) → 直接获得结果
脚本是“预编译”的知识 ——它把人类专家的领域逻辑固化为代码，让 Claude 不需要在运行时“重新发明轮子”。
第三层关系是 Tools 反哺 Skills。 第 10 讲介绍的!command“ 语法展示了反向关系—— Tools 的输出反哺 Skills 的上下文 ：
---
name: pr-summary
description: Summarize changes in a pull request
---
## Context
- PR diff: !`gh pr diff` # Tool 输出 → 注入 Skill 上下文
- Changed files: !`git diff --name-only`
这是 Tools 反哺 Skills 的预处理模式：Shell 命令在 Skill 加载之前执行，输出直接注入 SKILL.md 内容，Claude 收到的是 已经包含实时数据的知识 。
把上述三层关系做个总结我们可以得到下面的 Skills × Tools 共生公式。
本讲小结
好的，本讲内容就到这里了。我希望你记住的要点就是 渐进式披露 是 Skills 的核心架构模式——按需加载，节省 tokens。它的 三层架构是 目录页（description）→ 章节（SKILL.md）→ 附录（引用文件）。而且辅助文件和.claude/skills/<name>/SKILL.md 都放在同一目录内。
SKILL.md 是路由器， 通过Quick Reference 表格用最少 token 完成路由判断。引用文件的“契约式”写法，即 契约式引用会 告诉 Claude 何时加载、加载什么、得到什么。这里有一个 500 行法则 ，超过就该重构——把参考、模板、示例移到辅助文件。通过 脚本封装 来封装确定性逻辑，Claude 执行但不需要理解脚本中的内容。
课程学到这里，我们已经掌握了两种上下文管理策略，分别是 Skill的渐进式披露（按需加载）+ 子代理隔离（纯净上下文） 。它们互相补充，解决不同的问题。我最后给出 两种上下文管理策略表的对比。
组合使用 ：一个子代理可以通过 skills 字段预加载 Skill，而该 Skill 内部仍然用渐进式披露组织内容。两种策略是互补的。
如果你现在还没写过复杂 Skill，这一讲不要求你一次吃透，先记住三个词： 目录、路由、契约 。等你真正写过一个“知识+模板+脚本+数据”的 Skill，再回头看这三个词，会像突然点亮地图一样。
思考题
- 如果你的 Skill 有 20 个参考文件，你会如何组织，才能让 Claude 快速找到需要的内容？
- 什么样的内容应该放在 SKILL.md 主文件，什么样的应该放在引用文件？
- 渐进式披露和我们之前学的子代理“隔离上下文”有什么相似之处？
- 你有一个 Skill 的 SKILL.md 现在是 800 行，包含：100 行核心指令、200 行 API 规范、300 行代码示例、200 行错误处理模板。用拆分决策树重构它——画出重构后的目录结构，写出 SKILL.md 中对每个文件的“契约式引用”。
- 设计一个“可视化输出”类型的 Skill：选择你项目中的一个分析需求（测试覆盖率/依赖关系/API 调用链），设计 SKILL.md + scripts/ 的目录结构，说明 Claude 只需要知道什么（最少 token），脚本负责什么（最多逻辑）。
- 用“认知经济学”分析你项目中一个现有 Skill（或设计一个新的）：画出 token 投入 vs 任务完成质量的曲线。哪些知识是关键知识（高边际收益）？哪些是冗余知识（接近零收益）？如何通过渐进式披露把 ROI 最大化？
- 分析 Skills × Tools 的三层关系在你项目中的应用：你的 Skill 需要约束哪些 Tools？有哪些确定性逻辑适合封装为脚本（预编译知识）？有哪些实时数据适合用
!command“ 预加载（Tools 反哺）？你可以自己设计出你的 Skills × Tools 协作图。
下一讲预告
我们已经掌握了 Skills 的结构和渐进式披露架构。下一讲，我们将学习 Skills 与 SubAgent 的配合实战 ，通过递进式的项目设计（API 生成器 Skill + SubAgent 配合），掌握 Skills 的高级组件架构和 SubAgent 配合执行的各种模式。
欢迎你在留言区和我交流讨论。如果这一讲对你有启发，别忘了分享给身边更多朋友。