SKILL.md正文建议压在5K token以内，超了就被截断，哪些内容该留在正文、哪些必须拆到references？

技能包工程 · 上下文预算 · 渐进式披露 · 检索契约

摘要：面向以 SKILL.md 为入口的技能包（skill package）工程实践，本文提出“注意力预算—检索成本”双约束分析主线：正文 5K token 并非随意设定的容量上限，而是模型有效注意力区间、上下文窗口占用与检索往返成本三者共同作用下的工程折中。文章给出可操作的切分判据（触发频率、决策必要性、可验证性、失效半衰期四维打分）、正文骨架模板、references 目录契约、渐进式披露的加载时序，以及一套可自动化的 token 计量与截断回归流水线。核心结论是：正文承载“路由与约束”，references 承载“证据与长尾”，二者以稳定锚点与显式加载指令耦合，才能在截断发生时保持技能可用性不塌陷。

目录

一、问题的提出：5K 不是玄学阈值

在技能包（skill package）工程中，SKILL.md 通常被约定为整个技能的唯一入口文件：它被注入到系统提示或工具描述中，承担“告诉模型这个技能是什么、何时用、怎么用、边界在哪”的职责。实践中广泛流传一条经验规则——正文建议压在 5K token 以内，超出部分会被截断。这条规则常被当作口口相传的“玄学”，但它其实可以从三个可观测的工程事实中推导出来：注入通道的硬上限、模型对长前缀的有效注意力衰减、以及检索式加载的往返成本。

先厘清“截断”一词的歧义。在多数技能加载框架中，截断至少可能发生在四个位置：（1）宿主系统对单个注入字段的字符或 token 硬限制；（2）模型上下文窗口在拼接系统提示、工具定义、历史对话后的剩余预算；（3）框架层对 SKILL.md 的预处理截断（例如只取前 N 个 token）；（4）模型自身在长上下文中对中段信息的利用率下降，即“有效截断”。前两者是确定性的、可计量的；后两者是概率性的、需要实验刻画。本文评述：把 5K 当作单一数字去争论“对不对”意义不大，真正有价值的是把它拆成“硬预算 + 软预算”，并针对每一层设计不同的防御策略。

由此引出本文的核心问题：在 5K 的软预算内，哪些内容必须留在正文以保证技能在截断发生时仍然可用，哪些内容应当外移到 references 目录并以显式加载指令按需读取？这不是简单的“长短切分”，而是一个关于信息架构的决策问题——正文是路由层与约束层，references 是证据层与长尾层。切分错误会导致两类典型故障：正文塞满细节导致关键约束被截断（“该说的没说”），或正文过度精简导致模型不知道 references 里有什么、何时该读（“该读的没读”）。

二、背景与概念界定：什么是 SKILL.md，截断发生在哪一层

2.1 技能包的基本结构

一个典型的技能包由入口文件、参考文档、脚本与资源组成。入口文件（通常命名为 SKILL.md）包含元信息（名称、描述、触发条件）、使用流程、约束与示例；参考文档目录（references/）存放长文档、规范原文、API 手册、案例库；脚本目录（scripts/）存放可执行工具；资源目录（assets/）存放模板与静态文件。这种分层并非某一家框架的独创，而是与“渐进式披露”（progressive disclosure）这一交互设计原则同构：先给最小必要信息，用户或模型表达进一步需求后再展开细节。

本文评述：渐进式披露在人类界面设计中用于降低认知负荷，在智能体系统中则同时承担降低 token 成本与降低注意力干扰的双重功能。但二者存在张力——披露得越晚，模型越可能在没有足够信息时做出错误决策。因此 references 的设计不能只考虑“存什么”，还必须考虑“模型如何知道它存在、何时该读、读了之后如何验证”。这三点构成了后文所说的“目录契约”。

2.2 截断的四层位置

关于 L4，长上下文语言模型的“中间遗忘”现象已有较多实证研究。Liu 等人 2023 年的工作系统测量了信息在上下文中的位置对检索准确率的影响，发现当关键信息位于长上下文中部时，模型表现显著低于位于开头或结尾的情形（Liu et al., 2023, Lost in the Middle）。此后多项基准复现了这一趋势，并指出其与任务类型、干扰项数量相关。本文评述：这一现象对 SKILL.md 的直接启示是——正文的尾部不应放置“一旦丢失就会导致错误执行”的硬约束；硬约束应当前置，并在流程节点处重复一次。5K 的软预算之所以合理，部分原因正是它把正文长度控制在了注意力衰减尚不严重的区间内。

2.3 为什么是 5K 量级

5K token 的量级可以从三个角度交叉验证。第一，注入通道角度：主流框架对工具描述与系统提示的单字段限制通常在数千 token 量级，5K 处于常见上限之内且留有余量。第二，注意力角度：多项长上下文评测显示，当有效信息密度较高时，数 K 量级的前缀仍能保持较好的指令遵循率，而继续增长后边际收益递减。第三，检索成本角度：若正文过短而 references 过多，模型需要更多轮“读取—判断—再读取”的往返，每轮都消耗 token 与延迟。三者共同把最优点推向 3K–6K 区间，5K 是其中的工程折中值。

需要强调，5K 是“建议值”而非“物理常数”。不同模型的分词器效率不同，同一段中文在不同分词器下的 token 数可能相差 20%–40%；不同框架的注入方式（是否与工具定义合并、是否压缩空白）也会改变实际占用。因此工程上应把 5K 视为“目标预算”，并配套一个可复现的计量脚本，而不是依赖人工估算。后文第七节给出的流水线即为此设计。

三、分析主线：注意力预算与检索成本的双约束模型

本文的分析主线可形式化为一个双约束优化问题。设正文长度为 T（token），正文承载的信息集合为 S，references 承载的信息集合为 R。技能执行的成功率可近似分解为：

P(success) ≈ P_route(S) × P_execute(S, R | load) × P_verify(S)

约束一（注意力预算）：T ≤ T_budget，且 P_route 随 T 增长呈倒 U 形
约束二（检索成本）：E[loads] × C_round ≤ C_max，C_round 为单次读取往返成本

目标：在双约束下最大化 P(success)，即选择 S 与 R 的划分

其中 P_route 表示模型正确判断“是否该用此技能、用哪个子流程”的概率，P_execute 表示在正确路由后按流程执行的概率，P_verify 表示输出可被校验的概率。这个分解的价值在于：它把“该放正文还是 references”从直觉判断转化为对三个概率项边际贡献的比较。

本文评述：倒 U 形的假设需要谨慎对待。它并非严格定理，而是对两类经验现象的综合——过短的正文导致路由信息不足（P_route 下降），过长的正文导致注意力稀释与关键约束被淹没（P_execute 下降）。在具体模型中，这个曲线的峰值位置需要实测，但“存在峰值”这一结构性判断在多数技能场景下是稳健的。工程上的做法不是追求精确的峰值，而是确保正文落在峰值附近的平坦区间内。

检索成本项常被低估。每一次“读取 references 文件”在智能体系统中往往意味着一次工具调用或一次上下文重载，其成本包括延迟、token 重复计入、以及引入新的干扰信息。若一个技能包需要 5 次以上往返才能完成一次典型任务，那么即使单次读取很便宜，累计成本也可能超过把关键内容直接放进正文的代价。这解释了一个反直觉的现象：并非“越拆越好”。对于高频、短路径的任务，正文应当更“厚”；对于低频、长尾、需要精确引用的任务，references 才应承担主要信息量。

四、切分判据：四维打分与决策矩阵

把双约束模型落地，需要一套可操作的判据。笔者在实践中使用四个维度对每一条候选内容打分，每维 1–5 分，再加权汇总。四维分别是：触发频率（该信息在典型任务中被用到的比例）、决策必要性（缺失该信息是否直接导致路由或执行错误）、可验证性（该信息是否可被脚本或测试自动校验）、失效半衰期（该信息随版本、时间变化的快慢）。

加权总分高于 3.5 的内容进入正文候选池，低于 2.5 的进入 references，介于两者之间的需要结合预算余量决定。需要说明，权重是笔者基于若干技能包维护经验给出的初始值，并非普适常数；团队应根据自身任务的错误成本结构重新标定。例如在金融合规类技能中，“决策必要性”的权重应显著提高，因为一次错误分支的代价远高于多读一个文件的成本。

本文评述：四维打分法的真正价值不在于分数本身，而在于它强制维护者对每条内容回答“它服务于哪个概率项”。实践中大量正文膨胀源于“把文档搬进入口”——维护者把 API 手册、参数表、历史案例整段粘贴，理由是“万一要用”。但“万一”对应的正是低触发频率与低决策必要性，这类内容应外移。反过来，一些看似琐碎的约束（例如“输出必须是 JSON 且不含注释”）虽然短，却直接决定 P_verify，必须留在正文并前置。

4.1 一个快速判定的启发式清单

在时间有限时，可以用以下清单快速判定。若一条内容满足“删掉它，模型有超过三成概率做错第一步”，则留正文；若满足“删掉它，模型仍能正确开始，只是后续某步需要查证”，则外移；若满足“它只在特定错误发生后才有用”，则外移并在正文中写明“出错时读 references/xxx.md”；若满足“它描述的是外部系统的当前状态”，则外移，因为失效半衰期短，正文内嵌会迅速过期。

这四条启发式与四维打分在方向上一致，但更强调“第一步正确性”。原因在于智能体任务的错误具有级联性：第一步路由错误后，后续再精确的执行也无法挽回。因此正文的首要职责是保证第一步正确，其次才是保证执行细节完整。

五、正文骨架：5K 预算内的七段式模板

基于上述判据，笔者推荐一个七段式正文骨架，并给出各段的 token 预算参考。该骨架的顺序经过刻意设计：把最不可牺牲的约束放在最前，把可牺牲的示例放在最后，从而在 L3 预处理截断发生时，损失被限制在尾部。

七段合计约 3.1K–5.7K token，中位数落在 4.5K 附近，与 5K 建议值吻合。若预算紧张，优先压缩第 7 段与第 4 段的措辞，而非删除第 2 段或第 5 段。第 5 段（加载指令）常被忽视，但它是正文与 references 之间的唯一耦合点：没有它，references 就是一堆模型不知道存在的文件。

本文评述：把“最小示例”放在最后是一个有意的权衡。示例对模型的行为塑造作用很强，但示例也最容易膨胀——维护者倾向于不断增加示例以覆盖更多情形。把示例放在尾部，一方面利用“近因效应”让模型在生成前最后看到具体形态，另一方面在截断发生时优先损失示例而非约束。若团队发现示例被截断后成功率明显下降，正确的做法不是把示例前移，而是把示例压缩成一个“最小可复现片段”，并把完整示例集外移到 references。

5.1 正文写作的三条硬规则

第一，每条约束必须可判定。避免“尽量”“适当”“合理”这类不可判定的措辞，改为可检查的条件，例如“输出字段不超过 8 个”“若输入含日期则统一为 ISO 8601”。可判定性是 P_verify 的前提。

第二，流程步骤必须单句单动作。一个步骤包含多个动作时，模型容易漏执行或合并执行。把“读取配置、校验字段、写入结果”拆成三步，每步一个动词，可显著降低执行偏差。

第三，加载指令必须显式命名文件路径与触发条件。写成“需要时查阅 references/api.md”是不够的，应写成“当用户要求分页时，读取 references/pagination.md 的‘游标’一节”。路径与条件越具体，模型越可能在正确时机触发读取。

六、references 目录契约与渐进式披露时序

references 不是“杂物间”，而应遵循一套目录契约。笔者建议的最小契约包含四项：命名规范、索引文件、分节粒度、版本标记。命名规范要求文件名表达内容而非来源，例如 pagination.md 优于 doc_v3_final.md；索引文件（如 references/INDEX.md）列出所有文件的一句话摘要与适用场景；分节粒度要求每个文件内部用二级标题划分可独立读取的单元；版本标记记录最后核对日期与对应外部系统版本。

索引文件是渐进式披露的关键。它本身也应控制在数百 token 内，只包含“文件名—一句话—何时读”三列。这样模型在需要时可以先读索引，再决定读哪个文件，形成两级披露：正文 → 索引 → 具体文件。两级披露相比一级披露的优势在于，索引的体量小、可常驻，而具体文件可以很大且不必常驻。

# references/INDEX.md（示例，约 200 token）

| 文件 | 一句话 | 何时读 |
|---|---|---|
| api.md | 接口签名与错误码 | 需要调用外部接口时 |
| pagination.md | 游标与偏移两种分页 | 结果超过一页时 |
| errors.md | 常见错误与修复 | 校验失败且原因不明时 |
| schema.md | 输出 JSON Schema | 生成结构化输出前 |

本文评述：索引文件的存在改变了一个常被忽略的成本结构。没有索引时，模型要么不读 references（信息浪费），要么盲目读取多个文件（往返成本高、干扰大）。有索引时，读取行为变成“先低成本定位、再高成本展开”，期望往返次数下降。这与信息检索中的两阶段排序思想同构：先用轻量模型召回候选，再用重量模型精排。笔者认为，技能包的 references 设计应明确借鉴这一结构，而不是把所有文件平铺给模型。

6.1 加载时序的三种模式

模式一，前置加载：在任务开始时一次性读取所需文件。适用于任务路径确定、文件体量小的场景。优点是往返少，缺点是可能读取用不上的内容。

模式二，惰性加载：在执行到特定步骤时才读取。适用于路径分支多、文件体量大的场景。优点是按需，缺点是若触发条件写得模糊，模型可能漏读。

模式三，失败驱动加载：仅在校验失败或异常发生时读取排错文档。适用于错误处理类内容。优点是几乎不占常驻预算，缺点是对首次执行的帮助有限。

实践中三者常混合使用：元信息与硬约束常驻，主流程惰性读取参数文档，排错文档失败驱动读取。关键是为每类内容明确指定模式，并在正文的加载指令段写清楚。若不加指定，模型的行为会不稳定——同一技能在不同会话中可能表现出完全不同的读取习惯。

七、工程流水线：计量、校验与截断回归

再好的判据也需要工具支撑。笔者建议在技能包的构建流程中加入三道关卡：token 计量、结构校验、截断回归。三道关卡都可脚本化，并接入持续集成。

7.1 token 计量

计量的要点是使用与目标模型一致的分词器，而非按字符数估算。中文场景下字符数与 token 数的比例波动很大，按字符估算容易系统性低估。计量脚本应输出总 token、各段 token、以及“若截断到 5K 会丢失哪些段”的模拟结果。

# 伪代码：分段计量与截断模拟
from tokenizer import encode

SECTIONS = split_by_heading("SKILL.md")   # 按二级标题切分
budget = 5000
total = 0
lost = []
for name, text in SECTIONS:
    n = len(encode(text))
    total += n
    if total > budget:
        lost.append(name)
print("total:", total, "lost_if_5k:", lost)

输出中的 lost_if_5k 是核心指标。若丢失的段落包含硬约束或加载指令，则构建失败；若只丢失示例，则告警但不阻断。这把“5K 建议”变成了可执行的构建规则。

7.2 结构校验

结构校验检查四件事：元信息字段是否齐全；硬约束是否使用了可判定措辞（可用关键词黑名单检测“尽量”“适当”等）；加载指令中提到的文件是否真实存在；索引文件是否覆盖了 references 下的所有文件。这四项检查成本低、收益高，能拦截大部分低级错误。

7.3 截断回归

截断回归是最容易被跳过、却最有价值的一环。做法是构造一组代表性任务，分别在“完整正文”与“截断到 5K 的正文”两种条件下运行，比较成功率与错误类型。若截断后成功率下降超过预设阈值（例如 10 个百分点），则说明正文的尾部承载了过多关键信息，需要重排。

本文评述：截断回归的意义在于把“5K”从一个静态数字变成动态约束。随着技能演进，正文会自然膨胀，今天安全的尾部明天可能变成关键段。定期运行截断回归，相当于给技能包做“压力测试”，提前暴露脆弱点。这一思路与软件工程中的故障注入（fault injection）同源：主动制造截断这一故障，观察系统是否优雅降级。

7.4 可参考的外部资源

关于长上下文利用率的评测方法，可参考 Lost in the Middle 原始论文 与 其官方代码仓库；关于提示工程中的结构化写法，可参考 Prompt Engineering Guide；关于分词器差异的实测，可参考 Hugging Face Transformers 文档 中 tokenizer 章节；关于检索增强的分阶段设计，可参考 Pinecone 的 RAG 系列教程。这些资源提供了可复现的方法，读者可据此搭建自己的计量与回归环境。

八、案例与数据：三类技能包的切分对照

为使判据可感，下面给出三类典型技能包的切分对照。需要说明，以下 token 数为笔者对若干内部技能包的统计中位数（模拟整合数据，非公开基准），仅用于说明量级关系，不应作为普适结论引用。

从对照可见，正文长度与技能频率并非正相关。高频短路径技能反而应保持较短正文，因为其流程简单、错误成本低，把细节外移可减少常驻占用；中频多分支技能正文最长，因为路由信息必须常驻；低频长尾技能正文适中，但 references 数量最多，索引质量成为成败关键。本文评述：这一格局说明“5K”是上限而非目标，真正的目标是让正文长度与路由复杂度匹配，而非一律顶格。

在合规审查类技能中，一个常见错误是把法规原文整段放入正文。法规原文体量大、更新频繁，且多数任务只需引用其中少数条款。正确做法是正文只写“引用规则：涉及数据跨境时读取 references/cross-border.md 第 3 节”，并在索引中标注该文件的最后核对日期。这样既控制了正文体量，又保留了可追溯性。

九、对比与局限：常见反模式与边界条件

9.1 四类反模式

反模式一，“文档搬家”。把外部文档整段粘贴进正文，导致正文膨胀至 10K 以上，关键约束被截断。识别信号是正文中出现大段无结构的说明文字。

反模式二，“空壳入口”。正文只有一句话“请参考 references 目录”，没有索引、没有加载指令。模型不知道有哪些文件、何时该读，实际行为退化为凭先验猜测。

反模式三，“示例通胀”。为覆盖每种情形不断增加示例，正文中示例占比超过一半。示例的边际收益递减很快，而占用的预算却是线性的。

反模式四，“隐性依赖”。正文引用了 references 中并不存在的文件，或引用了已改名的文件。这类错误在人工维护中极难发现，必须靠结构校验拦截。

本文评述：四类反模式的共同根源是把 SKILL.md 当作“文档”而非“接口”。文档追求完整，接口追求契约清晰。一旦把正文视为接口——它的消费者是模型而非人类读者——许多取舍就变得自然：接口不应包含实现细节，但必须声明依赖与前置条件。

9.2 边界条件

双约束模型在以下条件下需要修正。其一，当模型上下文窗口极大且注意力机制对长前缀友好时，5K 的约束可以放宽，但检索成本项仍然存在，因此“正文适度增厚、references 保留”仍是合理策略。其二，当任务完全确定性、可由脚本完成时，正文应极简，把逻辑交给代码，因为代码的可验证性远高于自然语言描述。其三，当技能需要向人类读者展示时（例如作为产品文档），正文与 references 的划分还需兼顾可读性，此时可维护两套视图而非一套。

还需指出，本文引用的长上下文研究多在英文基准上进行，中文场景下的注意力衰减曲线可能不同。分词粒度、语序、标点密度都会影响有效注意力。因此团队在应用本文判据时，应在本领域数据上做小规模复现，而非直接套用他人的阈值。

十、结论与展望

回到最初的问题：5K 以内该留什么、该拆什么。本文的答案是——留“路由与约束”，拆“证据与长尾”。具体而言，元信息、硬约束、路由表、主流程、加载指令、校验清单应留在正文，并按不可牺牲程度从前到后排列；API 手册、法规原文、完整示例集、排错文档应外移到 references，并通过索引文件与显式加载指令与正文耦合。四维打分法提供了逐条判定的操作路径，七段式模板提供了预算分配参考，三道关卡提供了可自动化的质量保障。

展望未来，技能包的形态可能继续演化。一方面，随着模型原生支持更结构化的工具描述与更长的有效上下文，正文与 references 的边界会移动；另一方面，随着技能市场与复用生态的成熟，references 的契约可能标准化，出现可跨技能共享的索引格式。笔者认为，无论形态如何变化，“正文是接口、references 是证据”这一分工不会过时，因为它对应的是信息架构中一对稳定的张力：常驻信息的成本与按需信息的延迟。

对工程团队而言，最务实的起点不是争论 5K 是否精确，而是立刻建立三件事：一个与目标模型一致的 token 计量脚本、一份 references 索引文件、一组截断回归任务。这三件事的成本都不高，却能立刻暴露当前技能包中最脆弱的部分。技能包的可靠性，往往就藏在这些看似琐碎的工程细节里。

主要参考文献

说明：本文参考文献与资料总数 62 篇（含上述主要文献 10 篇及正文中提及的教程、文档与论文），其中近三年（2023–2025）文献占比约 58%。文中三类技能包的 token 统计为笔者对若干内部技能包的整合统计中位数，属模拟整合数据，已在此标注；长上下文注意力相关结论以公开论文为准，未做独立复现。