agent-skills：为智能体建立可复用技能库，告别提示词堆砌

最近有位做智能客服系统的朋友跟我抱怨说他们团队用大模型做任务调度已经三个月了效果始终差一口气——模型能力不差上下文也给了不少但就是“时灵时不灵”。我问他是不是把所有逻辑都揉在了一段系统提示词里他说对啊不然还能怎样。这个场景我太熟了很多团队把Agent做成了“提示词堆砌”最后悔不当初。今天想认真聊一个解决这类问题的思路agent-skills也就是给智能体建立一套可复用、可组合、可独立验证的“技能库”。agent-skills这个概念本质上是在说一件事别让模型每次都在高风险的未知环境里自由发挥而是把那些你已经验证过、确定能跑通的业务流程封装成标准技能让Agent按需调用。这么做的好处非常直观推理成本更低输出稳定性显著提升而且每项技能都能单独测试、单独改进不用动一发而牵全身。这篇文章适合正在做Agent应用落地的开发者、技术负责人以及那些已经受够了“提示词越长效果越差”的团队参考。1. 重新理解agent-skills它解决的到底是哪一类问题1.1 从“什么都让模型想”到“让模型会调用”先说我观察到的普遍现象。很多团队做Agent的第一步是写一个超级长的系统提示词把自己的业务流程、判断规则、处理逻辑全部塞进去然后指望模型能像一位全能员工一样既懂业务判断又懂工具操作还能在意外情况下随机应变。短期demo确实惊艳但一旦面对真实流量问题就暴露了——推理耗时长、响应不稳定、偶尔还会自作主张。这里面的根源在于大模型本质上是个概率生成器你越是放任它在高自由度空间里发挥它的行为方差就越大。而agent-skills的思路恰恰相反预先定义好一批“经过验证的行为单元”每个单元包含明确的目标描述、触发条件、执行步骤、所需资源和退出标准Agent在接到任务后先做的是“匹配技能”而不是“从零推理”。我打个比方。你请了个新厨师如果你给他一本菜谱让他自己研究怎么做川菜他确实能做出菜来但口味飘忽不定如果你事先把回锅肉、麻婆豆腐这些菜的标准流程都拍成短视频让他需要时翻出来照着做出品就稳定多了。agent-skills就是那批短视频Agent是那个厨师而LLM的推理能力则从“决定怎么做”降级为“决定该看哪个视频”。1.2 agent-skills与function calling、提示词工程的边界很多人会把agent-skills和function calling搞混这里我多说一句。Function calling解决的是“模型如何把意图转成结构化参数”的问题它偏向于模型与外部工具的接口层而agent-skills的核心是“业务流程的封装与编排”它可以调用function但封装粒度远大于单个函数。举个例子一个“生成月度数据报告”的技能内部可能包含提取数据、清洗异常值、计算指标、生成图表、排版输出五六个function调用技能层把它们串成一个完整闭环模型不需要关心每一步的底层逻辑。提示词工程则是更早期的做法它的哲学是“给足规则和上下文让模型自己推理出正确路径”。在简单场景下依然有效但当业务复杂到一定程度提示词会变得冗长、脆弱、难以维护。agent-skills并不完全取代提示词而是把那些确定性强的部分从提示词里剥离出来固化到技能里这样提示词本身只用负责最上层的意图判断负担大大减轻。我自己的经验是当单条提示词超过1500字还感觉不够用时就说明你已经在用提示词的短板硬扛业务复杂度了这时候应该考虑转型为技能体系而不是继续堆字。2. 动手前必须想清楚的全局设计2.1 技能的边界怎么划不是越细越好技能设计最忌讳的是走极端。有些团队把技能拆得极细比如“发送邮件”、“查询天气”这种原子操作也被当成技能结果Agent每做一件事要匹配七八个技能调度成本上去了还容易匹配错。另一些团队则把整条业务线打包成一个巨型技能里面分支逻辑比原先的提示词还复杂——这等于换汤不换药。我建议的划分原则有三个。第一一个技能应该能独立产生业务价值。什么叫独立产生价值用户问“今天上海能不能洗车”一个叫评估洗车适宜度的技能能直接给出结论这就产生了价值而单独的“查询未来三天天气”只能算工具调用不够格称为技能。第二技能内部的控制流复杂度应该可控分支场景建议不超过五个如果一个技能里出现了“如果A且B但C不成立且D超过阈值则走E流程否则走F流程”这种描述就该继续往下拆。第三技能的输入输出应该有清晰、可量化的规约输入是意图、参数和上下文摘要输出是结论、证据链和置信度。2.2 技能目录结构长什么样这里我给一个验证过的参考结构。每个技能是一个独立目录目录名就是技能ID目录内包含一个SKILL.md文件作为技能描述还有可选的脚本、模板和资源文件。SKILL.md的结构很关键我一般会包含以下字段name技能名称用动词短语比如“分析竞品定价策略”description两到三句话说明这个技能做什么、在什么场景下触发这部分会直接拿去喂给调度器做语义匹配所以务必写清楚边界when_to_use明确适用条件告诉模型“当看到哪些信号时用我”input_requirement执行该技能所需的参数清单每个参数写清楚类型、含义、示例execution_steps核心用步骤化的方式描述整个执行过程给出决策节点和分支条件output_format定义输出内容的结构edge_cases列出已知的边界情况遇到这些情况如何兜底这个结构看起来不复杂但字段顺序我建议不要乱动。模型在读取技能时通常先看name和description做快速筛选匹配到之后再细读execution_steps所以前面的字段越清爽调度效率越高。把大量FAQ塞在description里的做法很常见其实是个坑——它会干扰模型对技能边界判断的精准度。2.3 一套技能库的完整生命周期定义、实现、验证、迭代技能不是写完就完了它有自己的生命周期我把它拆成四个阶段。定义阶段主要工作是写SKILL.md文档这时候不要写代码先想清楚行为的输入输出和分支逻辑最好用自然语言在白板上过一遍整个流程让不熟悉这个领域的同事也能看懂。实现阶段才是代码介入的时候按照SKILL.md去开发内部逻辑每条路径都要覆盖。验证阶段是最容易被跳过的很多人写完就用结果边界情况完全没测我的建议是至少构造三组测试用例标准场景、边界场景、异常场景然后记录技能在不同场景下的输出质量。迭代阶段根据线上真实表现反馈去优化描述文本或者内部逻辑逐步逼近更稳的状态。四个阶段看起来平平无奇但能严格执行的团队真不多。大多数人的做法是定义完直接进入实现验证草草了事迭代阶段更是完全没有——技能上线之后除非报错否则再也没人碰。我说句实话agent-skills这套体系真正拉开团队差距的不是模型能力而是迭代纪律。3. 工具选型先看看三个主流路线的优劣3.1 闭源生态体系以Claude Skills为参考说到agent-skills目前最成熟的参考是Claude生态里的Skills机制。它把技能意图自动识别、上下文召回、技能执行从步骤0到步骤6做了一个完整的标准化流程并且这套流程是可观测的——你能够看到系统识别到了什么技能、参数填充到什么程度、执行到哪一步、退出原因是什么。对于没有太多底层研发资源的团队来说这是上手最快的一条路。但闭源体系的限制也很明显技能调度逻辑是黑盒你无法控制底层模型在匹配技能时的算法也没办法在模型理解出现偏差时去干预匹配过程。另外它的运行环境依赖特定平台迁移到其他模型上基本等于重构。我的判断是闭源方案适合快速验证产品概念但如果你想构建长期竞争力的核心技能资产还是要考虑可迁移的方案。3.2 开源框架路线从LangChain到自研编排开源生态里的做法就多元了。LangChain等框架提供了工具抽象和基础编排能力你可以把技能封装成工具集合再通过AgentExecutor来调度。好处是灵活、透明、可自控坏处是自由度本身就是负担——你很快会发现工具的抽象粒度、调度策略、上下文组装这些事情都得自己拿主意没有一个现成的“最佳实践”摆在那等你抄。另一个被验证比较靠谱的做法是“基于状态机的轻量自研编排”。把Agent的一次任务执行拆成状态节点每个技能对应一段行为逻辑状态机控制跳转LLM只在状态节点内做决策。这个方案技术上不复杂但效果非常稳因为它把LLM的行为自由度锁在了一个个明确的状态内模型绝对不会跑飞。3.3 工具选型速查别一上来就追求大而全很多团队一听说agent-skills就想着上一整套企业级Agent编排平台我觉得完全没必要。选型应该依赖你的实际业务规模而不是技术热度。场景推荐路线不推荐的理由快速产品验证闭源Skills机制开源方案初始化成本高中等复杂度业务开源框架自研状态机纯自研调度器投入过大技能数量超过50个自研技能注册中心匹配服务开源框架的匹配精度不够团队以业务为主闭源低代码方案预测性维护成本高长期看效率反而低核心原则是技能不是越多越好系统架构也不是越复杂越好一切以稳定交付业务价值为准绳。4. 实操把一个真实案例从零做成技能4.1 场景描述与需求分析为了把前面的理论落到地上我拿一个真实做过的场景来演示智能售后客服中的“退款资格预审”技能。业务背景是这样的客服系统每天收到大量关于退款的问题以前是一个人工客服去查订单状态、核对退货时间、判断品类是否支持无理由退款一套流程走下来大概需要五六分钟。客户希望用Agent先做预审能直接出结论的就不打扰人工。对这类需求第一步不是写代码而是做需求拆解。我梳理出这个技能必须在拿到订单号之后回答三个核心问题订单是否已过退货有效期商品是否属于不可退品类订单状态是否处于可退款区间。这三个问题之间还存在优先级关系只要过期了就直接拒绝不用再判断品类和状态没过期再看品类品类没问题再看状态。这就是一个典型的顺序分支结构非常适合固化成技能。4.2 SKILL.md逐段编写过程写SKILL.md时我是按字段顺序逐个推敲的。name字段定为“退款资格预审”description写的是“判断一个订单是否满足退款条件给出预审结论与原因说明。适用于用户咨询退款、退货、维权等售后场景能够基于订单状态、商品类型和购买时间快速给出明确结论。”这里写“适用于”而不是“当用户要求退款时触发”是因为用户可能不会直接说“我要退款”可能只是问“我这单是不是买错了”系统也应该能识别出潜在意图。when_to_use我写得更细当对话中出现订单号且用户表达出对订单不满、希望退货、询问售后政策等信号时优先匹配该技能。这里有个细节值得分享一下——把“触发信号”写出来比只写“什么时候用”有效得多。因为在调度过程中模型匹配的是用户当前意图而不是看他是否说了一句咒语。execution_steps是核心我分成了六步从用户对话中提取订单号若缺失则向下游追问澄清追询思路使用单独模板处理根据订单号查询订单主信息包括下单时间、订单状态、商品类目判断是否超出退货有效期当前时间减去下单时间对比商品类目对应的退货周期若超出有效期直接输出拒绝结论及原因结束流程若在有效期内判断商品是否属于不可退品类如定制类、生鲜类、已拆封的影音商品若品类可退再核对订单实时状态是否处于待收货、已完成等可操作区间输出最终结论每个步骤内部我会补充一句“如何做”的说明但不会把所有API细节都写进去。SKILL.md是给调度模型看的行为规约不是给工程师看的接口文档写得太细反而会喧宾夺主。输出部分我定义为一个包含三级结论的数据结构conclusion取approved、rejected、manual_review三个值之一reason给出简洁的中文说明confidence是模型对该结论的置信度数值用于下游判断是否需要转人工。4.3 配套执行脚本与资源文件的编写要点SKILL.md是给模型看的真正干活还得靠代码。我会把订单查询逻辑写成一个通用函数模块供技能内部调用用幂等设计保证多次执行不产生重复副作用。这个模块单独抽出来是因为它不只被这一个技能使用后续可能还有其他技能也需要查订单状态。脚本内部还会维护一份《商品退货规则映射表》里面记录了每个类目的退货周期和是否可退标记。这份表会定期从业务后台同步更新——为什么要单独放一张表而不是让模型自己判断因为这种业务规则是需要严格确定性的不允许模型自由发挥。这是我反复强调的一个原则凡是能确定的信息不要让模型去猜。执行完毕后脚本会生成一份结构化的执行记录包含输入参数、中间结果、最终输出和每步执行耗时。这份数据往后有大用——一方面可以做技能的回归测试另一方面可以用来做线上质量的持续监控我后面会详细说。4.4 接入后的观察与调优记录技能上线后的第一个星期我每天都会看系统的调度日志。第一天的数据就不错预审技能被正确触发的比例在八成左右误触发的主要原因有两个一是用户明明在问换货却因为提到订单号被误判成退款预审二是用户已经退款成功回来只是催进度也被误判成预审。针对这两个case我对when_to_use做了措辞调整增加了“仅当用户表达退款的潜在意图或明确诉求时使用换货咨询优先匹配换货资质预审技能退款进度查询优先匹配进度查询技能”。第二天误触发比例明显下降。另一个有意思的发现是有些用户会一次性问多个订单比如“这两个订单都能退吗”而技能一开始只支持单订单处理。我在需求分析阶段确实没考虑到这个场景日志里被自动捕获了然后我在输入处理逻辑里加了一层循环判断逐订单进行预审最后统一返回结果列表。这种从线上反馈倒推技能优化的路径是我认为agent-skills比纯提示词工程先进得多的地方——技能有明确的行为边界异常情况更容易暴露和修正。5. 常见问题与排查技巧实录5.1 技能匹配不准先看描述再看调度先说排名第一的高频问题——技能匹配错误率居高不下。遇到这种情况我的排查顺序是固定的先检查SKILL.md里的description有没有写清楚触发场景和边界多数情况下是描述太笼统或者覆盖了过多相似场景导致的如果描述没问题再去查调度器的匹配算法看它用的是关键词匹配、向量召回还是模型推理决策。有个经验要分享description里的负面排除比正面描述往往更有效。例如“本技能不适用于已经完成退款流程的订单咨询”“本技能不处理换货请求”这类句子能明显降低误触发率。我见过一个团队的技能匹配准确率从72%直接拉到91%靠的就是加了四句负面排除。另外如果你的技能库里技能超过30个纯靠把全量技能描述塞进上下文让模型匹配的方式就开始撑不住了。这时候就需要做一个轻量检索的预处理先用向量召回Top5候选技能再让模型在这五个候选里做精准匹配。这个改动并不复杂但对效果提升极为显著。5.2 技能内部执行报错调用链的可观测性是关键技能内部报了错很多人第一反应是打开日志看报错信息。但技能是跨系统调用的日志散落在各个服务的控制台里追一次调用链往往要翻三四个系统累死个人。我的建议是在技能入口处统一埋一个traceId每次执行生成一个全局唯一的追踪ID然后所有内部调用都把traceId带下去最后集中输出一份执行摘要。做了这个改造之后排查问题的效率至少翻倍。有一次线上反馈“退款资格预审技能响应超时”我看执行摘要发现时间全部消耗在第三步“判断是否超出退货有效期”的订单状态查询上而商品类目查询只用了20毫秒。顺着这个线索往下查是订单状态查询的RPC接口原来有一次超时重试机制在极端情况下会阻塞三秒。改成异步降级方案后P95耗时从4.2秒降到了900毫秒。5.3 技能学过拟合当“按步骤做”变成“死板照做”第三个问题更有意思也更容易被忽视——技能用久了模型会表现得很死板。它严格按SKILL.md的步骤走但用户问法稍微变通一点就不知道该不该触发这个技能。这个问题的本质是技能的“泛化能力不够”而过拟合的原因往往出在description和when_to_use的措辞过于贴近训练时的样本表达。解决思路是给描述加点“松弛感”。举个例子从“当用户咨询订单退款问题时使用”改成“当用户流露出对订单不满意、后悔购买、希望退货或咨询售后政策等任何与退款相关意图时使用”虽然语义看起来模糊了一些但模型在匹配时的召回率反而提升了。当然这个改动要与先前的负面排除配合使用——把容易混淆的场景排除掉之后放宽正面描述并不会带来误触发。5.4 技能数量爆炸定期做“技能健康度体检”最后一个常见问题是技能库变大之后管理成本急剧上升甚至出现技能互相覆盖、语义重叠的情况。一个健康的技能库技能的粒度应该是相对均匀的如果你发现某几个技能之间的语义距离非常近大概率是可以合并的。我用一个非常简单的办法做诊断把每个技能的name和description全部embedding化做一次聚类分析那些聚在同一个簇里的技能就是潜在的重叠对象。另一个维度是看技能的使用频次和转化率连续一个月调用量是个位数且输出质量评分不高就说明这个技能要么定位不准要么没有价值应该果断下架或重做而不是让它躺在库里制造噪音。技能资产和其他代码资产一样需要持续治理没有一劳永逸的捷径。6. 从技能到技能体系一条可逐步演进的路最后再说一个视角。agent-skills真正的价值是在时间维度上沉淀出来的。技能一旦建设起来就是一个团队内部可持续复用、持续优化的资产它不属于某一次对话也不依赖于某一次提示词的灵感而是真正可积累、可评估、可演进的组织能力。未来如果要做多Agent协作技能体系还能进一步升级——不同Agent共享技能库技能之间可以编排成更复杂的流水线甚至可以用一个“技能编排器”来自动组合已有的原子技能去解决那些你没有预先定义但可以即时拼装的需求。这条路走得通的前提是当前这一层基础足够扎实。但愿我上面这些经验能帮你少踩几个坑。