Skill 渐进式披露

系列入口：如何使用 Agent。前置：Skill 内部结构。

一、一个反直觉的事实：写得更多，效果更差

刚上手的人常有个朴素冲动：既然规则有用，那我把所有规范、步骤、示例、背景知识全写进 CLAUDE.md，总该万无一失了吧？现实恰恰相反——文件越长，每次都在消耗宝贵的上下文窗口，真正重要的规则被淹没在大量当前用不上的细节里，模型反而抓不住重点。这就是典型的「信息给得越多越笨」。

渐进式披露（Progressive Disclosure）就是为解决这个矛盾设计的：让信息分层，只在需要时才进入上下文。

二、三层分别放什么

第 1 层：常驻入口（SKILL.md） 只放每次都需要的最小信息：这个 Skill 做什么、何时触发、主干步骤、以及「需要更多信息时去哪取」的路径。它应该短到能一眼扫完。

第 2 层：按需文档（references/） 详细的规则、边界情况、长示例、背景解释。这些不是每次任务都用得上，入口里写明「处理 X 时读取 references/x.md」，模型在遇到 X 时才加载。

第 3 层：可执行脚本（scripts/） 真正去做检查、生成、转换的代码。模型不需要把脚本逻辑读进脑子，只在需要时运行、看结果，把「知识」变成「动作」，最省上下文也最可靠。

三、为什么这样反而更准

渐进式披露同时解决两个问题：

1. 省 token：当前任务用不到的细节根本不进窗口，台面始终整洁。
2. 提命中：每一层信息密度都高，模型在任何环节看到的都是与当前问题强相关的内容，不被无关细节干扰。

这和人的工作方式一致：你不会每天上班先把整个部门手册背一遍，而是清楚「遇到 X 类问题去查第 3 章」，需要时才翻。

为了让你直观看到分层的效果，这里给一个改造前后的对照。某 Skill 最初把所有内容塞进一个入口：触发描述、主干步骤、十几条各种边界情况、几个长篇示例、以及一段处理特殊格式的说明，长达两三百行。结果是每次调用都整段加载，普通任务用不到其中大部分，而模型常在无关细节里跑偏。

按三层改造后：入口只保留触发描述、五条主干步骤、以及资源路径，缩到几十行；十几条边界情况和长示例移进 references/，入口标注「遇到对应场景再读」；特殊格式的处理逻辑写成脚本，需要时直接运行、只看结果。改造后，普通调用只加载精简入口，既快又聚焦；只有真正碰到复杂子情况，才付出额外读取成本。关键差别是：信息成本从「无论是否需要都照付」变成了「用多少付多少」。

还有一个更隐蔽的收益常被忽略：分层让主干更突出，模型对核心步骤的遵守反而更稳定。在大段混杂信息里，关键指令只是众多文字中的一小段；而在精简入口里，每一条主干都清晰可见。这就是为什么渐进式披露不仅省 token，还常常让执行结果本身更可靠。

四、怎么判断一条信息放哪层

用三个问题给信息分层：

问自己	放置层
是不是每次用这个 Skill 都需要？	第 1 层入口
只在特定子情况才需要？	第 2 层参考文档
是可以程序化执行的动作？	第 3 层脚本

一个简单的自检：写完入口后，如果发现某段话「大多数任务其实用不到」，那它就该下沉到 references；如果某段逻辑「干脆能写成脚本让它跑」，就别用自然语言占篇幅，直接脚本化。

实际分层时，最容易卡住的是「它好像有时用得到」这种中间情况。给你两个判断技巧：

• 看首次使用的必要性，而不是极端情况。 不要因为「万一遇到某个特殊场景」就把内容常驻。分层的意义正是让那种罕见场景按需付费。判断信息归属，应基于大多数典型调用，而不是最复杂的边缘例子。
• 拿不准时优先下沉。 当你在犹豫一段内容放入口还是参考文档，放进参考文档、入口给路径，通常更安全。因为入口臃肿的代价是每轮持续付出，而多一次按需读取的代价只在真正需要时发生，且很小。

还有一个要避免的反向问题：过度分层。把每次都要用的主干也拆得七零八落，导致模型一进入 Skill 就要先读四五个文件才能开始，反而增加成本和跳转。分层是手段不是目的，标准始终是「让信息加载尽量贴合真实使用时机」——高频的别过度藏，低频的别常驻。

可以给你一个简单的落点口诀，帮助快速决策：天天用，放门口（入口）；偶尔查，放书架（参考）；动手做，交给机器（脚本）。 大部分信息据此都能快速归位。

五、同样的思想也适用于规则组织

渐进式披露不是 Skill 独有的。规则文件分层其实是同一个道理：保持根规则精简，把详细背景拆到 memory/notes 按需引用。核心原则始终是一条——常驻的尽量少，详细的按需取，动作优先脚本化。 掌握这条，你设计任何知识资产都不会再陷入「越写越长、越长越笨」的循环。

为什么这套设计对模型和人都自然？因为它顺应了「注意力是稀缺资源」这个共同事实。人处理信息同样有「窗口」——一次能专注的内容有限，把无关材料摊在眼前只会分心；我们依赖索引、目录、摘要，正是为了在需要时才深入，而不是一次加载全部。模型的上下文窗口在机制上更严格（有硬上限、注意力会被稀释），但底层逻辑一致。

理解这一点，你就不会把渐进式披露当成某种需要硬背的技巧，而是把它看作「对稀缺注意力的尊重」。无论是写规则、做 Skill、还是组织任何给 Agent 的资料，只要你始终想着「对方此刻真正需要哪一小部分」，自然会做出克制而清晰的设计。这也是从新手堆砌信息，走向高手精准供给信息的分水岭。

六、一个完整 Skill 的分层实战

光看原则和片段还不够，这里用一个更完整的 Skill 例子，演示你在实际设计时如何一步步决定信息位置。场景：团队要做一个 release-check（发版检查）Skill，发版流程比提交检查更复杂，涉及多个环节和不少边缘情况。

第一步：先识别哪些是「每次发版都要走」的主干。 梳理后稳定核心是：确认版本号 → 核对本次包含的改动 → 跑完整测试与构建 → 检查配置与环境 → 确认回滚方案 → 生成发版记录。这六步每次都需要，构成第 1 层入口主干，保持精简、按顺序列出。

第二步：把「只在特定情况才需要」的细节挑出来下沉。 比如「涉及数据库变更时要额外检查迁移脚本」「跨多个服务一起发版时的顺序与口径」「移动端发版特有的商店审核注意事项」——这些并非每次遇到，放进 references/ 不同文件，入口只写「遇到数据库变更时读 references/db-migration.md」之类的明确指向。它们不占常驻空间，只在对应分支触发时加载。

第三步：把「确定性动作」脚本化。 像「列出两次版本之间的全部改动」「校验版本号格式」「检查配置在各环境是否一致」这类要求准确、可重复的动作，写成脚本。模型不读脚本逻辑，只在对应步骤调用、拿结构化结论，既可靠又省上下文。

第四步：把产出格式交给模板。 发版记录有固定栏目（版本 / 变更摘要 / 风险 / 回滚方案 / 检查结果），做成模板，保证每次输出统一、不缺项。

走一遍这个过程你会发现，分层决策其实是在回答一系列很实际的问题：这一步是不是每次都做（入口）？这个细节是不是只在某种情况下才用（参考）？这个动作是不是要求确定可重复（脚本）？产出是不是需要固定形态（模板）？ 当你这样梳理时，信息会自然落到合适位置，不需要死记结构规范。

还要注意一个节奏：复杂 Skill 不必一次设计完美。可以先把主干入口写出来、在真实发版里用一次；每当遇到一个「当初没覆盖的具体情况」，再把它补进对应参考文件或脚本。这样 Skill 随每一次真实使用长全，比闭门设计一个庞大目录更贴合实际，也更易维护。这和前面反复强调的「先建立、再使用、持续整理」完全一致。

这个例子也顺带说明了渐进式披露在复杂场景的价值：如果把上面所有细节——数据库变更、多服务口径、移动端审核、各种脚本逻辑——全塞进入口，入口会膨胀到无法维护，且每次哪怕是最简单的发版也要整段加载。分层之后，简单发版只走精简主干，复杂情况才按需深入，系统在不同复杂度下都能保持高效。好的分层让 Skill 既能够承载很丰富的知识，又不会让简单使用为复杂内容买单。

七、落地时的常见问题

Q：模型会不会不知道要去读参考文档，导致漏用？ 关键是入口要写清楚「遇到 X 就读 references/x.md」，触发条件具体。验证时故意构造 X 场景，确认它会顺着路径读取。如果经常漏，可适当在主干里强化提示，但仍优于把内容全常驻。

Q：脚本输出又长又复杂，会不会反而占窗口？ 所以脚本设计时应让它输出精简、结构化的结论，而不是把内部过程全打印出来。脚本省的是「不必理解逻辑」，但它的输出仍占窗口，保持结果简洁同样重要。

Q：三层必须严格分开吗，参考和脚本能混用吗？ 不必教条。实际 Skill 里参考文档可能引用脚本、模板也可放在资源目录。重要的是背后的原则——按使用时机控制加载，而不是机械地追求形式上的三层。

Q：我该先写全再拆，还是一开始就分层？ 简单内容一开始未必需要分层，避免过度设计；当你发现入口变长、低频内容混入时再重构。不过已知的长文档、脚本逻辑，可以从一开始就直接放到对应资源文件。

Q：分层后调试问题会不会更麻烦，不知道它读了哪层？ 可以让它在执行时简要说明读取了哪些资源，便于追踪；而且分层让问题更容易定位——触发问题查描述、主干问题查入口、细节问题查对应参考。相比一个巨型文件，分层通常是让排查更清晰，而不是更混乱。

Q：团队多人维护这些分层文件，怎么避免冲突？ 保持每个文件职责单一、入口作为唯一总览，约定好谁负责哪类内容，并把结构说明写清楚。良好的分层本身也降低了多人同时改同一个大文件产生冲突的概率。

Q：渐进式披露和上下文压缩是一回事吗？ 相关但不同：压缩是任务运行中对已有历史的被动/主动精简；渐进式披露是在设计知识资产时，预先安排好信息的分层与按需加载。前者偏运行时补救，后者偏事前设计，目标都是让窗口聚焦。

九、把它当成一种长期习惯，而不是一次性技巧

最后说一点方法论层面的事，帮助你真正用好渐进式披露。它最有价值的地方，不是某次重构省下多少 token，而是当你在写任何知识资产时都默认先问「这是不是现在就需要」——这个习惯一旦建立，规则、记忆、Skill 都会自然保持精简，而不会随时间重新膨胀成难维护的长文。

要维持这个习惯，可以借助一个很简单的回顾动作：每隔一段时间，或当某个文件明显变长时，回头看一遍——哪些内容已经过期、哪些大多数场景根本用不到、哪些其实可以脚本化。把这些下沉或清理，让信息结构重新贴合当下的真实使用。这和整理工作区、清理桌面是同一个道理，频率不必高，但要有。

还需要接受一个现实：信息分层不是一次设计完就永久有效的静态结构，而是要随项目演进持续微调的活系统。 流程会变、技术栈会升级、当初合理的分层以后可能不再合适。把它当成需要定期照看的资产，而不是写完就放在一边，才能长期享受它带来的清晰与高效。当这种「按需供给、定期整理」内化成你的本能，你在这个领域的信息组织能力就已经相当成熟了，也会自然迁移到规则、记忆乃至更复杂的多 Agent 协作中。

八、把原则用到其他知识资产上

这套思路的应用范围其实更广：规则文件保持精简入口、详情下沉；记忆里高频事实放显眼处、详情按需；甚至你给 Agent 组织任何信息，都可以问「它是不是现在就需要」。掌握「按需求时机供给信息」这个内核，你就不会在任何知识资产上重蹈「越堆越长、越长越差」的覆辙。这也是上下文工程与 Skill 设计共享的同一条底层方法论。

总结

别把所有知识塞进 CLAUDE.md：用「精简入口常驻、详细文档按需读、动作脚本化运行」的三层渐进式披露，让模型在每个环节只看到当下需要的信息——写得更克制，Agent 反而更聪明。