上下文预算:为什么必须懒加载
Claude Sonnet / Opus 的上下文窗口很大(200K),但真正"高质量注意力区"只有最靠前和最靠后的几千 tokens。把所有 Skill 的细节塞进 System Prompt,相当于把 10 本手册同时摊在桌上——Claude 有,但用不起来。
| 方案 | 上下文占用 | 命中准确度 | 成本 |
|---|---|---|---|
| 全塞 System Prompt | 200K tokens(满载) | 召回高 / 精度低 | 每次都付 |
| Skill 无渐进披露 | 激活后 50K tokens | 召回中 | 每次激活都付 |
| Skill + 渐进披露 | 激活 200 tokens,触发时再加 2K | 精度高 | 只为用到的部分付 |
三级加载模型
─── Level 1 ── Metadata(激活期) ─────────────────────
加载来源: SKILL.md 的 frontmatter + 开头 1-2 段
触发条件: Skill 对 Claude 可见时(启动 Session)
典型大小: 50-200 tokens
任务: 让 Claude "知道有这个能力"
─── Level 2 ── Body(匹配期) ────────────────────────
加载来源: SKILL.md 正文工作流 + 决策点
触发条件: 用户请求命中 description → Claude 主动 read 整份 SKILL.md
典型大小: 500-2000 tokens
任务: 给 Claude 主流程 + 边界判断规则
─── Level 3 ── Details(执行期) ─────────────────────
加载来源: references/*.md + scripts/*.* 的输出
触发条件: Claude 读到 "查 references/X"、"跑 scripts/Y"
典型大小: 每次 100-5000 tokens
任务: 现场取用精确知识,用完即弃
一个 SKILL.md 如何分配三层
以"金融年报分析 Skill"为例,看什么放哪一层。
--- # Level 1 — Metadata name: sec-10k-analyzer description: 分析 SEC 10-K 年报,给出健康度评分 + 风险摘要。 --- # SEC 10-K 年报分析(Level 2 — Body 开始) ## 工作流 (必读) 1. 下载 10-K: `scripts/fetch_10k.py <ticker>` 2. 解析核心指标(见下方"指标清单") 3. 评分(见下方"评分规则") 4. 输出 Markdown 报告 ## 指标清单 - 营收增速(YoY) - 毛利率 / 经营现金流 / 自由现金流 - 负债率(Debt/Equity) - ROE / ROIC ## 评分规则 (决策点) - 基础评分逻辑见 `references/scoring.md` - 行业特定调整见 `references/industry/*.md` - 遇到金融股,强制读 `references/banking-adjustments.md` ## 异常 (Level 3 触发点) - 10-K 缺失现金流量表 → `references/missing-cashflow.md` - 会计准则切换(IFRS → US GAAP)→ `references/gaap-transition.md`
Level 3 的 references 列表:
references/
├── scoring.md ← 详细评分算法
├── banking-adjustments.md ← 银行股专用
├── missing-cashflow.md ← 异常处理
├── gaap-transition.md ← 会计准则切换
└── industry/
├── tech.md
├── retail.md
├── energy.md
└── healthcare.md ← 9 个行业,每个 3-5K 字
算账:激活期 100 tokens,匹配后 800 tokens,跑一次具体分析再加 1-2 个 reference(2K tokens)——总计 3K。同样信息量如果塞 System Prompt 是 50K,15 倍压缩。
怎么触发 Level 3:显式引用 + grep 友好
Skill 要让 Claude"自己想到要去读 references/X"。两种触发方式:
方式 1: 显式引用(推荐)
## 决策点
- 当公司属于银行业时,必须读 `references/banking-adjustments.md`
- 遇到负债率 > 5,读 `references/high-leverage.md`
Claude 读到 "必须读 X",就真的会去 read 那个文件。最可靠,推荐所有关键路径都用显式引用。
方式 2: grep 友好(补强)
给 references 里的文件起语义化的名字,让 Claude 在找答案时能自己 grep。
❌ references/doc1.md ✅ references/banking-adjustments.md ✅ references/retail-seasonality.md
文件名本身就像 tag。Claude 遇到"这是零售公司,要考虑季节性",一看目录里有 retail-seasonality.md,自然会读。
长文档拆分原则
按主题拆,不按章节拆
不要
chapter1.md / chapter2.md——Claude 不知道哪章有要找的内容。按主题 scoring.md / ratios.md / cash-flow.md。文件开头放"本文涵盖什么"
给一个 2-3 行摘要,Claude grep 到后先读摘要判断是不是要的,不用读完全文。
保持单文件 < 5000 行
超过这个长度,Claude 读进上下文就占 30K+。拆成 2-3 个主题更优。
给同义词加关键词行
在文档顶部写 "Keywords: negative equity, insolvency, 资不抵债"。中英混写用户都能命中。
脚本的 Level 3 位置
scripts 也是 Level 3——SKILL.md 不需要列脚本源码,只需要告诉 Claude"遇到 X 时运行 scripts/Y.py"。Claude 通过 Bash 工具执行,结果注入上下文。
## 工作流第 3 步
计算 Altman Z-score:
```bash
python scripts/z_score.py --revenue 120M --liabilities 80M --equity 30M
```
脚本输出形如 `{"z_score": 2.34, "risk": "gray_zone"}`,据此判断风险等级。
脚本返回结构化数据
scripts 的 stdout 应该是 JSON 或 YAML,方便 Claude 解析。避免"打印一大段人类可读日志"——那会占几千 tokens 且 Claude 解析易出错。
scripts 的 stdout 应该是 JSON 或 YAML,方便 Claude 解析。避免"打印一大段人类可读日志"——那会占几千 tokens 且 Claude 解析易出错。
反例:一个违反渐进披露的 SKILL.md
--- name: bad-sql-skill description: SQL 工具 --- # SQL 全能助手 ## 所有表结构 (这里复制粘贴了数据仓库 200 张表的 DDL,总计 30000 行) ## 所有业务规则 (这里塞了 150 条业务规则说明,总计 15000 行) ## 使用 用户想查什么,就写 SQL。
问题:
- description 没分级,命中太宽
- 表结构、业务规则全在 SKILL.md,匹配期一次性吃 45K tokens
- 没有决策点引导,Claude 必须扫完整份文档才能开始写 SQL
- 更新成本高——改 1 张表要动主 SKILL.md
改造后
--- name: dw-sql description: 基于公司 data warehouse 生成 Snowflake SQL。 激活:用户描述数据查询需求且提及业务指标或表名。 不处理:DDL、权限、Postgres。 --- # DW SQL 助手 ## 工作流 1. 识别用户问的业务概念(如"DAU"、"订单"、"渠道") 2. 查 `references/concepts/{concept}.md` 找对应表 + 口径 3. 查 `references/tables/{table}.md` 确认 schema 4. 写 SQL,附口径说明 ## 表目录 见 `references/tables/INDEX.md`。 ## 业务规则速查 见 `references/rules/INDEX.md`。
references/
├── concepts/
│ ├── dau.md
│ ├── revenue.md
│ └── ...
├── tables/
│ ├── INDEX.md ← 200 张表的一行摘要目录
│ ├── orders.md
│ └── users.md
└── rules/
├── INDEX.md
└── rule_001.md ...
激活期 100 tokens,匹配期 600 tokens,跑一个查询读 2-3 个 reference 约 2K——原来 45K 被压到 2.7K,精度反而提升。
渐进披露的"体检清单"
- ✅ description 是否 < 200 字,明确"何时激活 / 不做什么"?
- ✅ SKILL.md 正文 < 500 行?
- ✅ 大段的规范、表结构、API 文档是否都在 references/?
- ✅ SKILL.md 里是否有"遇到 X 去读 Y"的显式引用?
- ✅ references 文件名是否语义化、grep 友好?
- ✅ scripts 的输出是否结构化 JSON?
- ✅ 有没有在正文里塞进"完整代码",应该挪到 scripts/?
本章小结
- 渐进披露三级:Metadata 激活可见 / Body 匹配加载 / Details 触发加载
- 核心目标:让激活期几乎不花 token,执行期只花当次任务需要的
- 触发 Level 3 靠显式引用 + grep 友好命名,不能光靠 Claude 猜
- 长文档拆分按主题、加 Keywords、单文件 < 5K 行
- scripts 封装可复用逻辑,stdout 输出结构化数据