做 Agent 开发的人大概都经历过这样一个阶段为了让模型懂行我们把能想到的领域知识全部塞进系统提示。我第一次做 Claude Code Agent 的时候也是这样把公司的计费规则、售后流程、常见问题、内部规范整理成一份八千多字的指引全部塞进系统提示里觉得这样 Agent 就无所不知了。结果呢第一次跑通 demo 的时候确实惊艳但越往后越不对劲——上下文越用越满、响应越来越慢、成本越来越高更糟糕的是它开始在一些基础问题上犯低级错误。后来我才想明白一个很朴素的道理系统提示不是知识库它是决策框架。领域知识应该按需加载而不是全塞进去。这篇是Learn Claude Code Agent 开发系列的第五篇专门聊按需技能加载这个话题——它到底解决了什么问题、底层逻辑是什么、怎么落地、有哪些坑。适合正在用 Claude Code 搭 Agent、或者被上下文爆炸和提示词维护折磨过的开发者参考。1. 为什么全塞系统提示会把 Agent 拖垮先说结论把领域知识全塞进系统提示不是笨的问题而是违反了大模型应用的一条基本经济原则——系统提示里的每一条内容都会在每一次请求中重复参与计算。这条原则决定了全塞这个方案的不可持续性。1.1 上下文账单你为可能用到的知识付了每次调用的钱假设你的系统提示塞了 8000 个 token 的领域知识。在 Claude Code 跑一个任务的过程中Agent 往往会经历多轮思考 → 调用工具 → 观察结果 → 继续思考的循环。一个稍微复杂的任务二十轮交互不算夸张。每一轮交互系统提示的 8000 个 token 都是固定开销跟着每一轮请求一起发送、一起参与计算。这意味着什么你为 8000 个 token 付的不是一次钱而是二十次钱。跑一个任务光系统提示的运输成本就是 8000 × 20 160000 token 的计算量。而这 8000 个 token 里真正对这个任务有用的可能只有 2000。剩下 6000 个 token 属于带了但没用到的行李却每轮都在拖慢响应速度、推高成本。用大白话打个比方你请了一个顾问他从第一天起就拖着一个装满所有领域资料的大行李箱不管你今天聊的是芝麻还是西瓜他都得先拖着这个箱子走到你面前。这个拖着箱子走的动作每次对话都在重复而箱子里大部分资料今天根本用不上。所以全塞系统提示的第一个问题不是效果不好而是成本结构极其不健康。任务越复杂、交互轮数越多这个固定开销被放大的倍数就越高。我在一个内部项目里实测过同样的任务系统提示从 8000 token 降到 1500 token 之后单任务的 token 消耗直接降了 30% 以上响应速度也明显快了。1.2 指令稀释规则一旦超过三条第四条就开始失效把系统提示当成一个装知识的容器还容易踩中另一个问题指令稀释。大模型遵循指令的能力是有限的尤其在提示词很长的时候。研究员早就发现过一个被称为lost in the middle的现象——处在提示词中段的内容被模型遵循的概率明显低于开头和结尾。当你把 8000 字的领域知识塞进去真正重要的行为准则遇到歧义必须追问不要臆造参数输出必须附引用来源会被淹没在大量参考资料里。模型不是不聪明而是它真的分不清哪些是必须遵守的铁律哪些是遇到问题时再查的资料这个问题的后果很隐蔽。它不会让你的 Agent 直接崩溃而是会微妙地降低一致性。比如你明确写了所有退款金额必须四舍五入到分但紧接着后面就是三四段计费规则细节模型在处理时可能把这条准则当成背景知识而不是核心约束偶尔忽略掉。这种偶尔犯错在 Agent 场景里是最难排查的——它不规律、不可复现、看起来像随机抖动实际上是你把约束和参考信息混在了一起。打个比方你把交规和驾校教材装订在同一本书里让司机每次开车前从第一页读到最后一页。司机不是不想遵守交规而是在 8000 页的阅读量里红灯停这条规则和某路段施工绕行的公告混在一起优先级被拉平了。1.3 维护噩梦知识一变整个提示词就要返工领域知识是高频变化的东西。计费规则改了、售后流程调整了、新版产品上线了、某条政策到期了任何一个变化都意味着你要去动那篇巨型提示词。改一次大型提示词是什么体验首先你要在八千字里定位到准确的位置这本身就不容易。其次改完你要重新验证全量功能因为你没法确定这次改动会不会和提示词里其他内容产生冲突。改多了还容易改出隐蔽矛盾——旧规则没删干净、新规则又覆盖上去模型到时候听谁的规则之间互相打架Agent 的行为就完全不可预期。我在实际项目里见过最惨烈的一次某次维护时把两条计费规则写成了互斥状态Agent 开始在不同任务里给出完全相反的答案。排查了一个下午最后定位到是提示词内部的逻辑冲突——两条规则在文档里相隔不到两百字但没有任何一方提到本规则不适用于另一条规则覆盖的场景。这段经历让我彻底明白巨型系统提示是有维护债的而且这个债是复利计算的。2. 按需技能加载的核心思路把知识从提示词里搬出去既然全塞的问题这么明显那正确的做法是什么核心思路其实一句话就能说完把行为准则和领域知识分开行为准则留在系统提示里领域知识变成按需加载的技能文件。2.1 系统提示只留决策框架不负责背书系统提示的最佳状态是你在 1 分钟内能读完的东西。它应该只包含Agent 的角色定位你是谁、替谁干活核心行为准则遇到歧义怎么办、输出格式要求、安全边界决策框架什么时候该调用什么工具、什么情况下要停下来追问少量必须每次都知道的全局约定比如项目路径、常用命令换句话说系统提示回答的是你该怎么做事而不是领域里有哪些知识。知识是会变的做事的方法相对稳定。把稳定的决策框架放在系统提示里把易变的领域知识放在技能文件里两边各自独立更新互不干扰。我自己的经验是系统提示压缩到 1500 token 以内是一个比较健康的目标。如果压缩到这个量级还有内容塞不下那说明塞不下的那些内容大概率本来就该属于技能文件。2.2 领域知识进技能文件变成可触发的资产Claude Code 里有一个很实用的技能机制你可以在项目里建一个技能目录把每一块领域知识整理成独立的技能文件。每个技能包含一份描述文件说明这个技能是干什么的、什么时候该用和具体的知识正文操作步骤、规则细节、注意事项。关键在于这些技能文件不是系统提示的一部分。它们平时躺在目录里不占上下文。只有当 Agent 判断当前任务和某个技能的描述匹配时才会把那个技能的文件读进上下文里。这就好比一个专家不会把整本法规汇编背下来但他清楚地知道遇到退款争议该翻哪一章遇到发票问题该翻哪一章。这种设计的好处是显而易见的上下文里永远只有当前任务真正需要的知识。任务 A 只需要退款规则那就只加载退款技能任务 B 涉及物流时效那就只加载物流技能。互不干扰各自清爽。2.3 不是让它背是让它查加载的本质是一次工具调用理解按需加载最关键的一点是转变心态你不需要让 Agent记住领域知识你只需要让它知道去哪里查。在 Claude Code 的交互模型里技能加载本质上就是一次文件读取操作。Agent 面对任务时先浏览技能目录看看有哪些技能可用、各自的描述说了什么然后根据任务内容决定读取哪个技能文件。这个决定本身就是模型推理的一部分——它不需要事先知道技能文件里写了什么只需要理解这个任务的场景和那个技能描述的场景是匹配的。这也意味着技能加载是天然可观测、可调试的。Agent 读了哪个文件、读了几次、读完有没有用到都可以通过日志看到。相比之下全塞系统提示是一条黑盒路径——你永远不知道那 8000 个 token 里到底哪些真正影响了行为。3. 技能资产库怎么组织目录、描述与加载链路说完了思路来看具体怎么落地。技能资产库的组织方式直接决定了按需加载的命中率。组织得不好技能机制反而会成为新的负担。3.1 SKILL.md 的规范结构description 才是触发信号每个技能对应一个目录目录里必须有一个入口文件常见的命名是 SKILL.md。这个文件由两部分组成YAML 格式的元信息和 Markdown 格式的正文。元信息里最关键的两个字段是名称和描述。名称不用多说描述才是真正的触发信号。描述的质量直接决定了这个技能被正确加载的概率。写描述的时候最重要的不是这个技能包含什么而是什么情况下该用这个技能。举个对比例子。一个退款规则技能如果描述写成包含退款计算规则、退款状态说明、特殊场景处理这是一份目录式的描述。Agent 看到之后能理解哦退款相关的东西在里面但遇到具体问题时它未必能把用户问订单金额不对和退款规则技能关联起来。更好的写法是场景式的当用户询问退款金额计算、订单部分退款、退款状态异常、退款时间预估或需要判断某笔订单是否满足退款条件时使用此技能。不适用于换货、补差价场景。这种描述给了 Agent 明确的匹配条件还给出了反向排除条件命中率会高很多。3.2 知识文件的分层入口文件、参考资料与示例单个技能目录内部的资源不建议全部堆在 SKILL.md 里。SKILL.md 只是入口它的作用是给 Agent 一个处理该类任务的决策路径。具体细节应该分层存放SKILL.md入口文件包含任务处理的流程框架、关键判断条件、异常情况处理逻辑references/参考资料目录放详细的规则文档、政策原文、内部规范examples/示例目录放典型输入输出对、历史处理案例templates/模板目录放输出格式模板、回复话术模板这样的分层有个好处Agent 加载技能时先只读 SKILL.md形成一个这个任务的通盘处理思路在执行过程中如果遇到具体细节问题再按需去读 references 或 examples 里的对应文件。这就是加载的加载——连技能内部的知识都做到按需而不是一次全读出来。我在实践中的体感是一个技能目录的入口文件控制在 300-600 行以内知识细节尽量下沉到子文件是最舒服的状态。入口太长的技能加载起来还是会拖慢上下文入口太短的技能又容易让 Agent 在处理任务时不知道下一步该干嘛然后频繁去翻子文件反而增加了调用次数。3.3 一条完整的加载链路长什么样把整个机制串起来一个按需技能加载的典型链路是这样的用户向 Agent 提出一个任务比如客户 A 的订单申请了部分退款帮忙算一下应退金额Agent 在自己的决策框架指引下判断这个任务需要领域知识支持Agent 浏览技能目录看到退款规则、发票规则、物流规则等多个技能的描述Agent 把任务关键词和技能描述做匹配选中退款规则技能Agent 读取退款规则技能的 SKILL.md获得处理退款类任务的流程框架执行过程中遇到具体计算细节再读取 references 里的计算规则文档任务完成这部分知识不再占上下文下一个任务重新匹配这个链路的精髓在第 4 步匹配是靠任务场景和技能描述之间的语义匹配完成的而不是靠硬编码规则。这意味着你不需要在系统提示里写如果遇到退款就打开展退款技能这种脆弱的条件判断模型自己就能完成这个映射。这也意味着技能描述写得越好这个链路就越可靠。4. 一次真实改造售后服务 Agent 从 8000 token 提示词到按需加载理论讲了一堆还是用一个真实的改造案例来收收尾。这个案例是某公司的售后服务 Agent模拟项目内部代号售后帮我从接手到完成改造大概花了三周效果非常直观。4.1 改造前的症状慢、贵、答非所问这个 Agent 最初就是全塞方案的典型系统提示里塞了 8000 多 token 的售后知识涵盖退款、换货、发票、物流、优惠券、投诉升级六大块。它上线后陆续出现了三类症状。第一是慢。一次普通的售后咨询响应时间经常要十几秒遇到复杂任务甚至更久。第二是贵。月底一看 token 消耗账单发现很大一部分都花在运输系统提示上。第三是更隐蔽的答非所问用户问退款它突然蹦出物流规则用户问发票它又扯到优惠券叠加。虽然每一条单独看起来都沾边但组合在一起就是不对路。我还做了一个很小的统计随机抽取 50 条真实咨询记录逐条看 Agent 的回答里有多少内容是和本次任务无关但存在于系统提示里的。结果触目惊心——接近一半的回答都混入了无关领域的知识。这就是指令稀释在真实业务里的样子不是模型蠢是它手里的规则太多了多到它自己也分不清优先级。4.2 拆解步骤先分类再抽取后验证改造的第一步不是写代码而是做知识分类。我把系统提示里的 8000 多个 token 逐条过了一遍分成三类第一类是行为准则比如回答必须附订单号遇到金额争议先安抚再核实不确定时不得臆造规则。这类内容留下总共压缩到大约 1200 token。第二类是领域参考知识比如退款计算规则、发票开具标准、物流时效承诺。这类内容全部搬出去。第三类是重复和冗余信息比如同一规则在多个地方出现、新旧版本的规则混在一起这类内容直接删除。第二部把搬出去的领域知识按业务域拆成五个技能退款规则、换货规则、发票规则、物流规则、优惠券叠加规则。每个技能按前面说的结构组织SKILL.md 里写处理流程references 里放具体规则examples 里放典型问答对。第三步是最容易忽略的验证环节。我没有直接全量替换而是先让新旧两个版本的 Agent 并行跑同一组测试任务对比输出。这组测试任务覆盖了六类售后场景、每个场景 5 到 10 条典型问题总共四五十条。对比下来发现新版在绝大多数任务上的表现不低于旧版但在跨领域的任务上比如退款之后用户又问发票怎么办表现明显更清晰——因为它不会被无关知识带偏。4.3 改造后的数据对比省下的不只是 token改造完成之后我记录了半个月的数据和改造前对比指标改造前改造后系统提示大小约 8000 token约 1200 token单任务平均上下文占用约 12000 token约 8000 token单任务平均 token 消耗约 35000 token约 24000 token答案与任务相关性人工抽检约 70%约 90%规则更新后回归验证耗时2 小时起30 分钟内数据背后的逻辑很清楚系统提示瘦身之后每一轮交互的固定开销都降下来了叠加起来就是单任务 token 消耗 30% 以上的降幅。更关键的是相关性和一致性上来了跨领域串场的问题基本消失。而维护体验的提升更是立竿见影——计费规则改动时只需要改退款规则技能目录下的对应文档跑一遍回归测试集就行再也不用在八千字海洋里捞针。5. 实测中的边界与三个最容易踩的坑按需技能加载不是什么银弹它有自己的边界。下面这三个坑是我自己和身边做 Agent 开发的同行都踩过的分享出来帮大家提前绕开。5.1 触发过载技能太容易被激活等于没有技能第一个坑是技能描述写得太宽泛导致它几乎每次都被加载。比如某技能描述写的是处理各种订单问题那碰到任何和订单沾边的任务Agent 都会把它读进来。结果就是这个技能从按需加载变成了事实上的全塞上下文爆炸的问题原样回来了。触发过载的本质是偷懒你没有认真想清楚这个技能真正适用的边界于是用一句大而全的话概括。解决方法是强制自己在描述里写清楚边界条件尤其是不适用于什么场景。我当时是怎么做的我给每个技能写描述时要求自己至少写两个反向排除条件写不出来就说明我对这个技能的边界还没想清楚。5.2 触发失灵描述写成目录而不是何时该用第二个坑和第一个正好相反描述写得太像目录了。包含退款计算规则、退款状态说明、特殊场景处理这种写法信息量其实很低。Agent 看到这个描述能知道哦退款相关的知识在这个技能里但它未必能判断当前这个具体问题该不该加载这个技能。描述的正确写法是从提问者的视角出发写清楚什么话术、什么场景、什么意图会触发这个技能。用口语说就是这个技能是用来回应什么问题的。比如当用户询问退款金额怎么算、为什么退款金额不对、部分退款和全额退款有什么区别时使用。写完之后我还会自己模拟十几个真实问题逐个问自己看到这个描述我会不会想加载这个技能用这种方式来检验描述的有效性。5.3 技能之间的依赖循环与知识版本管理第三个坑更隐蔽技能 A 的处理流程里需要用到技能 B 的知识但 B 的描述里完全没有提到这种联动场景。结果是 Agent 只加载了 A处理到一半发现缺知识再去翻 B有时候翻了 B 又发现需要 C来回折腾之下加载链路乱成一团。解决方法是显式声明依赖。在技能 A 的 SKILL.md 里明确写一句处理此任务时如涉及优惠券叠加需同时加载优惠券叠加规则技能把跨技能的知识依赖显式化。依赖声明写清楚之后Agent 的加载路径就稳定多了。知识版本管理是另一个容易被忽略的问题。领域知识是持续变化的技能文件也需要自己的版本管理。我的做法是每个技能目录的 references 下放一个变更记录文件每次更新知识时记录变更内容、生效时间和影响范围。这样如果 Agent 突然行为异常我能很快定位到是哪个技能文件在什么时间点被改过。6. 让加载命中率持续提升的调试方法按需加载不是一次性的改造它和写代码一样需要持续调试和优化。最后分享三个我一直在用的方法。6.1 给每次加载打日志让命中率可见我在技能目录里设计了一个简单的调试模式让 Agent 在处理任务时把浏览了哪些技能、加载了哪些技能、加载后被用于什么环节记录下来。这些日志不需要很复杂一两行文字就行但积累起来价值很大。每周末我会把这些日志汇总过一遍关注两个数字技能加载率和技能有效使用率。加载率是多少任务加载了技能有效使用率是加载的技能里有多少真的被用上了。如果某个技能加载率很高但有效使用率很低那说明它的描述有误导性Agent 被骗进来读了半天没用如果某项技能加载率很低那说明它的描述太隐蔽或者它对应的场景确实很少出现。6.2 维护一组回归测试任务改完不慌领域知识一变技能文件就得改。但改完之后怎么确认这轮改动没把别的场景搞坏我的做法是维护一组回归测试任务大概二三十条覆盖每个技能的典型场景、边界场景和跨技能联动场景。每次改完技能文件我不做人工抽检而是直接把这组测试任务跑一遍重点看两点技能命中率有没有变化比如某个本来该加载的技能这次没加载回答内容有没有回归。跑完有异常结合加载日志定位问题没问题就直接上线。这套流程跑顺之后规则变更的风险就基本可控了。6.3 把技能当代码维护定期评审与删减技能文件也是代码它需要评审、重构、删减。我曾经整理过一个从系统提示里拆出来的技能当时觉得很有用结果三个月过去了它在真实任务里的加载次数一只手数得过来。这种技能就应该考虑合并进其他技能或者干脆删除——它存在的意义不是有这个知识而是这个知识在合适的场景能被正确调用如果调用不了文件写得再详细也是无效资产。我给自己定了一个规则每季度做一次技能资产评审逐个技能看过去三个月的加载率和有效使用率低于阈值的标记出来要么重写描述、要么下沉合并、要么直接删掉。这个习惯坚持下来之后我的技能资产库一直保持精简每个技能都有它明确的、不可替代的用途。从我自己的体会来说按需技能加载带来的最大收益其实不是省了多少钱、快了多长时间而是让 Agent 重新变得可预期、可维护了。全塞提示词的 Agent 像一个装满杂物的房间你总觉得它什么都有但真正需要某个东西时反而找不到按需加载的 Agent 像一套分类清晰的档案柜东西还是那些东西但每样都待在它该待的位置需要时一抽就出来。最后再分享一个小技巧技能描述里的触发词尽量用你真实业务里的高频词汇别用书面化的抽象表达。我见过有人把退款技能描述成资金返还流程处理模块结果 Agent 死活不加载它——因为它和用户口中的退钱之间隔了一整个语义鸿沟。