渐进式披露理论上只加载命中的Skill正文，但GitHub issue反馈实际不按预期工作，问题在框架还是Skill写法？

摘要：渐进式披露（Progressive Disclosure）在Skill类Agent框架中被寄予厚望：路由层只判断"该用哪个Skill"，正文按需加载，从而压缩上下文、降低token成本、减少指令冲突。但GitHub上持续出现的issue表明，实际运行中常出现"未命中的Skill正文也被注入""命中后正文未加载""多个Skill正文互相污染"等现象。本文提出一条贯穿全文的分析主线——把"路由命中"与"正文加载"视为两个可独立观测的阶段，用"耦合度"解释失效来源。全文依次界定问题、拆解框架侧机制、归纳Skill写法侧的六类反模式、给出可复现的分层诊断步骤与量化指标，并讨论该范式的边界条件与演进方向。笔者认为，多数issue并非单纯的框架bug或写法错误，而是二者在"触发语义"上的契约缺失所致。

目录

一、导语：一个被反复误读的"理论正确"

在Skill类Agent框架的文档里，渐进式披露通常被描述为一句近乎自明的话：系统先根据用户输入匹配元数据（名称、描述、触发词），只有命中的Skill才把正文注入上下文。这个描述在理论上无懈可击，因为它把"选择"和"装载"拆成了两步，天然具备成本优势。然而工程现实往往更接近另一种图景：开发者打开日志，发现未被命中的Skill正文赫然出现在prompt里，或者命中了却只拿到一段被截断的摘要。

GitHub上围绕此类现象的issue并不罕见，讨论也常陷入二元对立：一派认为"框架的路由实现有bug"，另一派认为"是你的Skill描述写得太宽泛"。笔者认为，这种对立本身就是分析框架的缺陷——它默认"框架"与"写法"是两个互斥的归因桶，而忽略了二者之间存在一个共享的语义契约层。路由是否命中，取决于框架如何解释Skill元数据；而元数据是否可被正确解释，又取决于写作者是否理解框架的解释规则。任何一端的偏差都会在另一端表现为"故障"。

因此本文不打算给出"是框架还是写法"的二选一答案，而是建立一条可操作的分析主线：把渐进式披露拆成"路由命中"与"正文加载"两个可独立观测的阶段，用二者的耦合程度来定位失效来源。这条主线贯穿后续所有章节，也是诊断步骤设计的依据。为便于读者延伸阅读，文末附有若干框架文档与教程链接。

二、背景与问题定义：渐进式披露到底承诺了什么

2.1 概念溯源与准确定义

渐进式披露并非Agent时代的新发明。人机交互领域早在Nielsen的可用性启发式原则中就提出：界面应优先呈现高频信息，次要信息按需展开，以降低认知负荷（Nielsen, 1994）。这一思想后来被迁移到信息架构与API设计中，形成了"分层暴露"的通用模式。在Skill框架语境下，本文将其定义为：系统在每一轮推理前，仅将当前任务所需的Skill正文纳入上下文，未命中的Skill只保留轻量元数据。这个定义包含三个可检验的承诺：选择性、按需性、可逆性（下一轮可切换）。

本文评述：这三个承诺在文档中往往被合并表述为"按需加载"，但它们的失效机制完全不同。选择性失效表现为"该进的没进"，按需性失效表现为"不该进的进了"，可逆性失效表现为"上一轮的正文残留到下一轮"。混淆三者，是issue讨论长期无法收敛的根源之一。

2.2 问题边界：哪些现象属于本文讨论范围

为避免讨论泛化，需要先划定边界。本文聚焦于"Skill正文的注入行为与路由判定不一致"这一类现象，具体包括四种可观测形态：其一，未命中Skill的正文出现在上下文中；其二，命中Skill的正文缺失或被截断；其三，多个Skill正文同时注入造成指令冲突；其四，跨轮次残留导致上下文膨胀。不在此列的现象包括：模型自身幻觉、工具调用失败、网络超时等与披露机制无直接因果的问题。

这个边界划定的意义在于，它把"框架还是写法"的争论转化为一个可测量的命题：在给定输入下，路由判定结果与正文注入结果是否一致。一致则说明披露机制本身工作正常，问题在别处；不一致则进入下一层的耦合分析。这种"先证伪再归因"的顺序，比先入为主地指责某一方更可靠。

三、框架侧机制拆解：路由与加载的四层耦合

3.1 四层结构：元数据索引、召回、重排、装载

多数Skill框架的内部流程可以抽象为四层：元数据索引层负责扫描Skill目录、解析frontmatter；召回层根据用户输入与元数据的相似度产生候选集；重排层对候选做阈值过滤或模型裁决；装载层把最终选中的Skill正文拼入prompt。这四层中，任何一层的行为都可能被上层配置或下层写法影响，形成耦合。

笔者认为，issue中大量"不按预期工作"的反馈，本质上是观测点缺失导致的：框架通常只暴露最终prompt，而不暴露中间四层的判定结果。开发者看到的是"正文进了/没进"，却看不到"召回了几条、重排打了多少分、阈值是多少"。没有中间观测，归因只能靠猜，猜的结果自然分裂为"框架bug"与"写法问题"两派。

3.2 耦合点一：召回层的相似度计算对描述文本高度敏感

召回层若采用向量相似度或关键词匹配，其输出直接由Skill描述文本决定。描述写得越宽泛，召回集越大；描述写得越具体，漏召风险越高。这看似是"写法问题"，但框架侧的默认阈值、分词策略、是否做同义词扩展，同样决定了最终结果。二者在此处强耦合，无法单独归因。

本文评述：一个常被忽视的事实是，召回层的目标是"不漏"，重排层的目标是"不滥"，二者职责不同。若框架把阈值逻辑放在召回层，就会迫使写作者用描述文本去承担过滤职责，这是职责错配。合理的做法是召回层放宽、重排层收紧，并在文档中明确告知写作者"描述只需覆盖语义，无需承担过滤"。

3.3 耦合点二：重排裁决的确定性差异

部分框架在重排层引入小模型做裁决，这带来一个工程难题：裁决结果可能随温度参数、prompt模板版本、甚至模型服务端更新而漂移。开发者复现issue时若未固定这些变量，就会得到"时好时坏"的观测，进一步加剧归因困难。相比之下，纯规则重排（如关键词命中数、优先级字段）确定性更高，但灵活性不足。

3.4 耦合点三：装载层的截断与拼接顺序

装载层常被误认为"只是拼字符串"，但它至少涉及三个决策：单Skill正文是否有长度上限、多Skill命中时如何排序、正文与系统指令的拼接位置。任何一个决策都可能制造"看起来像路由失败"的现象。例如，某Skill正文超过上限被截断，开发者看到的是"命中但内容不全"，容易误判为路由只加载了摘要。

本文评述：装载层的截断策略应当显式暴露，而非静默执行。静默截断是issue的高发区，因为它把"配置问题"伪装成了"机制问题"。一个低成本的改进是：截断时在正文末尾插入可检索的标记（如"内容因长度限制截断"），让开发者一眼分辨。

3.5 耦合点四：缓存与跨轮次状态

为降低延迟，部分框架会缓存上一轮的Skill选择结果，或在会话级保留已加载正文。这在多轮对话中可能造成"上一轮命中的Skill正文残留到本轮"，表现为"未命中却出现正文"。这类现象与写法无关，纯属框架状态管理问题，但在issue中常被误读为路由失效。

笔者认为，缓存本身不是问题，问题在于缓存键的设计。若缓存键只包含用户输入而不包含会话状态与Skill版本，就会在Skill更新后继续返回旧正文，制造"内容与描述不符"的错觉。可验证的改进是：缓存键至少包含Skill内容哈希，内容变更即失效。

四、Skill写法侧：六类触发反模式

4.1 反模式一：描述过宽导致的"语义虹吸"

当Skill描述使用"处理各类文档""辅助编程任务"这类高度概括的表述时，它会在向量空间中覆盖大片区域，把本不属于它的请求也召回。这并非框架bug，而是描述文本承担了它不该承担的召回职责。可验证的判据是：统计该Skill在无关请求上的召回率，若显著高于同类Skill，即为过宽。

4.2 反模式二：触发词堆砌与负向排除缺失

与过宽相反，部分写作者在描述中堆砌大量触发词，试图"确保命中"，结果反而稀释了语义焦点。更关键的是缺少负向排除：没有说明"本Skill不处理什么"。在召回层，负向信息往往比正向信息更能收窄候选集。本文评述：负向排除应成为Skill描述的标配字段，而非可选补充。

4.3 反模式三：正文与元数据语义不一致

元数据说"用于日志分析"，正文却大篇幅讲部署流程。这种不一致会让重排层的模型裁决产生困惑：按元数据应命中，按正文语义却不应命中。若框架的重排依赖正文摘要，就会出现"描述命中但正文被排除"的现象，开发者看到的是"命中了却没加载"，实为语义冲突。

4.4 反模式四：单文件过大触发静默截断

把整个操作手册塞进一个Skill文件，是最常见的写法问题之一。它同时触发两个后果：装载层截断导致内容不全，以及上下文膨胀挤占其他Skill的空间。可操作的改法是按任务阶段拆分Skill，让每个文件的正文控制在合理长度内，并在元数据中标注适用阶段。

4.5 反模式五：隐式依赖未声明

某Skill的正文假设另一个Skill已加载（例如引用了其定义的变量或流程），但元数据中未声明依赖。当框架只加载前者时，正文中的引用悬空，模型只能猜测，表现为"加载了但行为异常"。这类问题在issue中常被描述为"Skill不生效"，实为依赖契约缺失。

4.6 反模式六：版本漂移与描述腐化

Skill正文随项目演进不断修改，但描述文本长期未更新，导致元数据与实际能力脱节。这类"描述腐化"在长期维护的项目中尤为普遍，且难以通过单次测试发现。笔者认为，应把描述文本纳入代码评审范围，与正文同版本管理。

小结：六类反模式的共同点是——它们都让"元数据语义"与"正文语义"或"框架解释规则"之间产生偏差。换句话说，写法问题的本质不是"写得不规范"，而是"写作者与框架对触发语义的理解不一致"。这正好呼应了本文主线：失效发生在契约层，而非某一端。

五、关键数据与典型案例：issue文本的量化观察

5.1 数据来源与预处理说明

本节数据为模拟整合数据，用于说明分析方法而非断言具体项目的真实比例。构造方式如下：从公开的Skill框架仓库issue中按关键词（"skill""progressive""not loaded""context"）检索，人工标注现象类型，再按本文四层结构归类。预处理步骤包括：剔除纯提问无复现步骤的issue、合并重复描述、将多现象issue按主现象归类。样本量为模拟的240条，标注一致性经双人复核。

需要强调，上述比例为模拟数据，仅用于展示"现象—归因层"的映射方法。真实项目应基于自身日志重新统计，因为不同框架的默认配置差异极大，直接套用比例会得出错误结论。

5.2 典型案例的复盘逻辑

以一个典型issue为例：用户报告"只应加载A Skill，但B Skill正文也出现了"。按本文主线拆解，先查路由日志确认B是否被召回；若未召回却出现正文，则查缓存与跨轮次状态；若被召回，则查B的描述是否过宽。三步之内即可定位到具体层，而不是在"框架还是写法"之间反复争论。这种复盘逻辑的价值在于它把主观判断转化为可执行的检查项。

本文评述：issue讨论的低效，很大程度上源于缺少统一的复盘模板。若框架在报错时自动附带"召回集、重排分、装载长度、缓存命中"四项元信息，绝大多数issue可以在首次回复中定位。这比要求用户提供完整复现脚本更现实。

六、可操作路径：分层诊断的七步法

6.1 七步流程

基于前文的四层耦合分析，笔者整理出一套可复用的诊断流程。它的设计原则是"从外到内、先证伪后归因"，每一步都产出可记录的观测值，避免凭印象下结论。

Step 1  固定变量：模型版本、温度、prompt模板、Skill版本哈希
Step 2  记录输入：用户原始输入（不做改写）
Step 3  抓取召回集：候选Skill列表及相似度分数
Step 4  抓取重排结果：阈值、裁决输出、最终选中集
Step 5  抓取装载结果：每个Skill正文的实际注入长度与位置
Step 6  比对一致性：路由判定 vs 注入结果，标记偏差类型
Step 7  单变量回归：仅改描述或仅改配置，验证偏差是否消失

这套流程的关键在Step 6与Step 7。Step 6把现象映射到四层中的具体一层，Step 7则通过单变量控制验证归因是否成立。若改描述后偏差消失，说明写法侧是主因；若改配置后消失，说明框架侧是主因；若两者都无效，则需检查缓存与版本漂移。

6.2 量化指标建议

为使诊断可比较，建议维护三个指标：路由准确率（命中集与人工标注期望集的一致比例）、注入一致率（注入正文与命中集的一致比例）、上下文冗余率（未命中正文占注入总长度的比例）。三者结合可以区分"路由错"与"装载错"，也能量化渐进式披露的实际收益。

笔者认为，冗余率是最被低估的指标。很多团队只关注"有没有命中"，却忽略了"注入了多少无用内容"。在长上下文模型成本仍不可忽视的当下，冗余率直接对应token开销，是评估披露机制是否真正生效的硬指标。

6.3 写法侧的落地清单

诊断确认写法为主因后，可按以下清单整改：描述聚焦单一任务域、显式写出不适用范围、正文与描述语义对齐、单文件控制在合理长度、声明跨Skill依赖、描述与正文同版本评审。每项都可转化为评审检查项，避免"知道但做不到"。

延伸阅读方面，可参考Anthropic关于Agent Skills的工程博客与官方文档，以及OpenAI的prompt工程指南中关于上下文管理的章节；视频教程可检索"progressive disclosure agent skills"相关讲解。这些资料对理解框架设计意图有帮助，但具体阈值仍需以所用框架的文档为准。

七、对比与局限：与其他上下文管理策略的取舍

7.1 与全量注入、检索增强的对比

渐进式披露并非唯一选择。全量注入实现简单、无路由误差，但上下文成本随Skill数量线性增长；检索增强（RAG）在粒度上更细，可按段落召回，但需要额外的索引与切分工程。三者的取舍本质是"路由误差"与"上下文成本"之间的权衡。

本文评述：三者并非互斥。一个务实的组合是"渐进式披露做粗筛、检索增强做细选"，即在Skill层先路由，再在Skill内部按段落召回。这样既控制了上下文，又降低了单Skill过大带来的截断风险。代价是需要维护两级索引，适合Skill规模较大的团队。

7.2 局限与边界条件

本文的分析主线也有边界。其一，它假设框架暴露了中间层观测；若框架完全不透明，七步法只能退化为黑盒对比测试。其二，它假设Skill数量达到需要路由的规模；若只有三五个Skill，全量注入反而更省心。其三，它未覆盖多模态Skill与工具型Skill的特殊性，这些场景的触发语义可能依赖参数而非文本描述。

笔者认为，承认边界比宣称普适更有价值。工程实践中，最危险的往往不是方法本身有局限，而是使用者误以为它无往不利。明确"何时不适用"，本身就是方法成熟度的一部分。

八、结论与展望：从"隐式契约"到"显式协议"

回到最初的问题：问题在框架还是Skill写法？本文的答案是——多数情况下，问题在二者之间的契约层。框架定义了如何解释元数据，写作者定义了元数据表达什么，二者若未就"触发语义"达成一致，任何一端单独优化都难以根治。把路由与加载拆成可观测的两阶段，用耦合度定位失效层，是比二元归因更可靠的路径。

展望未来，笔者认为该范式会朝"显式协议"演进：Skill元数据将包含结构化的适用域、排除域、依赖声明与版本哈希；框架将暴露标准化的路由与装载事件；诊断工具将能自动比对路由判定与注入结果。届时，"框架还是写法"的争论会自然消解，因为契约本身变得可检验。

对从业者而言，当下最务实的动作是：先建立观测，再谈归因；先量化冗余率，再谈优化。渐进式披露的价值不在于它"理论上正确"，而在于它能否在真实负载下稳定兑现选择性、按需性与可逆性这三个承诺。兑现了，它就是有效的上下文治理手段；兑现不了，再优雅的理论也只是文档里的一句话。

主要参考文献