技能中的渐进式披露

技能里塞得越多就越有用——直到不再有用。一个 SKILL.md 想把每种内容类型、每种 schema、每种语气规则都写进去，可以轻松上百行。Agent 会一次性全加载。Token 预算被烧掉，真正和当前任务相关的部分淹没在噪音里。

我设计技能时，让主文件当路由器，不当垃圾桶。它告诉 agent 有哪些东西、什么时候再读其余部分。细节放在按需加载的引用里。这样上下文更紧、行为更可预期。

SKILL.md 当路由器

website-content 技能就是个好例子。主 SKILL.md 只说明技能做什么、有哪些内容类型、文件放哪。它不会把完整语气指南或完整内容 schema 内联进来，而是写：写东西之前先读 references/voice-guide.md 和 references/content-schemas.md；写页面级文案时再读 references/page-patterns.md。

所以当你让 agent 写一篇博客时，它加载技能、看到「写作条目 → 读 voice-guide 和 content-schemas」，然后才拉进那些文件。当你让它更新 about 页时，它再加载技能和 page-patterns。如果任务只是「改一下 newsletter 按钮文案」，agent 根本不用为 voice-guide 或 content-schemas 付 token。

这就是渐进式披露。顶层文件回答「这个技能能做什么、这次任务需要什么？」引用文件回答「具体怎么做？」只在任务需要时才加载后者。

为什么 token 用量能压住

上下文窗口很大，但不是白来的。你塞进模型前面的每个 token 本可以用于输出、链式思考或工具结果。技能有 200 行而当前请求只用到 30 行，你还是会发 200 行——在 agent 根本用不到的说明上烧预算。

拆成薄路由器 + 按需引用就改变了算式。路由器常驻上下文；引用按任务加载一次。稳态是「路由器 + 一两个引用文件」，而不是「一大坨」。对覆盖写作、项目、首页、about 和翻译交接的技能来说，这差别很大。

第二个好处：agent 更不容易把不同流程的说明混在一起。当一切在一个文件里时，模型可能误把「about 页」的约束用到写作条目上，或反过来。当技能写明「写写作条目时读 content-schemas 和 voice-guide」，边界就清楚了。Agent 走一条路径，而不是把所有路径搅在一起。

什么时候再拆一层

过度拆分时，渐进式披露的收益会递减。一两个段落的小引用增加导航成本，却省不了多少 token。那什么时候值得再加一层？

当单个引用变长时。 如果 content-schemas.md 要覆盖五种内容类型且写得很细，可以考虑拆成 content-schemas-writing.md 和 content-schemas-projects.md，让路由器按任务指向对应文件。语气也一样：如果语气指南变成一本小册子，就按内容类型或「规则 vs 示例」拆开。

当受众或工作流明显不同时。 如果同一个技能既用于「写一篇 post」又用于「跑翻译流水线」，且每个工作流需要的文档子集不同，路由器可以分叉：「新写作/项目条目读 A 和 B；翻译读 C 和 D。」这样每次运行都只带当前需要的部分。

当加载顺序重要时。 有些技能有依赖——比如「先读 schema 再读语气指南，才知道有哪些字段」。路由器可以写明顺序：「1. content-schemas，2. voice-guide，3. 继续。」这样 agent 不会从文件名猜顺序，也不会读错顺序。

当不需要时。 如果技能很小且几乎每个任务都需要几乎全部内容，一个文件就够了。渐进式披露是用来把大技能管住的工具。别把 50 行的技能硬拆成四个 15 行的文件。

结论

技能是给 agent 的操作说明。越能把什么时候做什么编码清楚，agent 越少猜、你越少重复。把「什么时候加载什么」写进主技能文件，它就变成路由器；引用承载细节。这样 token 用得少、任务边界清楚，何时再加一层也一目了然：引用变太大、工作流分叉、或顺序重要时。把技能做成渐进式披露，你和 agent 都会得到更清晰的信号。