4.1 渐进式披露与上下文预算

为什么这件事值得单独讲

Skill 最容易被忽视的成本是上下文。上下文被占满的后果不是「变慢」，而是质量断崖式下降：模型开始遗忘早先的指令、忽略你的硬规则、输出前后矛盾。

一个设计不良的 Skill，会在每次被加载时悄悄吃掉几千到几万 token。所以「怎么拆」不是洁癖，是性能问题。

三级加载的预算模型

再回顾一次加载层级，但这次看成本：

层级 内容 常驻？ 成本量级
L1 name + description 是（所有 Skill） 约 100 词/技能
L2 SKILL.md 正文 命中后 目标 ≤ 5k 词
L3 scripts/ — ≈ 0（执行不读取）
L3 references/ 按需 只算被读的那一份
L3 assets/ — ≈ 0（不读入）

推论一：装 100 个 Skill 的常驻成本 ≈ 100 段 description ≈ 一万词量级。所以「装得多」不怕，怕的是「每个 description 都写成长文」。

推论二：scripts/ 和 assets/ 是免费的。凡是能用脚本固化的逻辑，都该搬进去——既省 token 又更可靠。

推论三：references/ 是可分摊的。它只在需要时被读一份，不会全量加载。

拆分的三条硬标准

把一段内容留在 SKILL.md，还是移到 references/？用这三条判断：

标准一：每次执行都会用到吗？

  • 每次都用 → 留 SKILL.md（例如：输出格式、硬规则、主流程）
  • 只在特定分支用 → 移 references（例如：处理「异常单据」的详细规则）

标准二：它是「指令」还是「资料」？

  • 指令（要做 A 再做 B，禁止 C） → 留 SKILL.md
  • 资料（字段清单、参数表、政策原文） → 移 references

标准三：超过 1 万字了吗？

  • 单份文件超过约 1 万字（或 10k 词） → 必须移出，并在 SKILL.md 里给出搜索模式。

大文件怎么处理：给搜索模式

超过 1 万字的 reference，别指望模型「通读」。要在 SKILL.md 里明确告诉它怎么定位。例如在 SKILL.md 的「参考资料」小节里写：

  • 文件：references/schema.md —— 全部 87 张表的结构说明（约 2.5 万字）。
  • 要求：不要通读。查表时先定位章节，例如：
grep -n "^## " references/schema.md        # 列出所有表名与行号
grep -n "订单表" references/schema.md      # 直接搜表名
  • 拿到行号后，只读取该表对应的一小节。

注意：这里给的 grep 命令是给 AI 用的，所以要写成可以直接复制执行的形态，并说明「先定位再读」，而不是「读一下这个文件」。

反模式清单

反模式 后果 正确做法
2 万字 API 文档塞进 SKILL.md 每次加载吃满预算，其他 Skill 被挤 移 references/，给 grep 模式
把所有示例都留正文 冗长，重点被淹没 只留 1～2 个正反例，其余移出
一个万能 everything.md 每次读一份超长文档 按主题拆成 5～8 份小文件
同一信息 SKILL.md 和 references 各写一遍 两份必然不同步，模型随机取一份 只保留一处
写「请参考 references 目录下的资料」 模型不知道具体读哪个文件 逐一点名文件 + 何时读
给 assets/ 里的模板写详细说明 模板本就不该被读入 只写「复制并替换占位符」

一个实操案例：从 1 个大文件拆到 4 个

拆分前（单个 SKILL.md，约 2.2 万字）：

finance-helper/
└── SKILL.md   ← 含：主流程 + 87 张表结构 + 32 个错误码 + 报表模板说明 + 历史背景

问题：每次加载都吃 2 万字预算；模型还会被无关的表结构干扰。

拆分后：

finance-helper/
├── SKILL.md                  ← 约 1200 字：概述 + 流程 + 硬规则 + 资源索引
├── references/
│   ├── schema.md             ← 87 张表结构（含 grep 定位提示）
│   ├── error-codes.md        ← 32 个错误码与处置
│   └── business-rules.md     ← 业务口径与历史背景
├── scripts/
│   └── query.py              ← 查询脚本（零上下文成本）
└── assets/
    └── report-template.xlsx  ← 报表模板（零上下文成本）

效果：常驻成本从 2.2 万字降到 1200 字，且每次任务只加载真正需要的那一份 reference。

预算自检清单

  • [ ] SKILL.md 正文 ≤ 5k 词
  • [ ] 正文里每段内容都符合「每次都用到」
  • [ ] 超过 1 万字的 reference 都给了 grep / 定位模式
  • [ ] 没有重复信息（SKILL.md 与 references 不重叠）
  • [ ] 每个资源文件都被正文点名，且写明何时读
  • [ ] 能固化成脚本的逻辑已经搬进 scripts/
  • [ ] assets/ 里没有「需要被读懂」的文件

上一篇：四、Skill 的进阶与工程化 ｜ 下一篇：4.2 脚本、依赖与跨平台

整理人：WorkBuddy