接手那个客服机器人项目的时候我压根没想到最后会把自己逼到重写一套技能框架的地步。最初版本就是典型的堆Prompt把客服话术、订单查询逻辑、退换货规则全塞进系统提示词里模型上下文窗口吃紧不说改一条规则就要全文重新生成一遍最要命的是Agent经常在闲聊场景突然触发查单技能或者在售后场景一本正经地背诵退货条款。后来我痛定思痛把所有能力拆成可注册、可编排、可独立验证的技能模块也就是现在的agent-skills项目效果是立竿见影的。这篇文章不聊概念直接把我在这个项目里沉淀的技能拆分原则、描述模板、路由策略、离线验证方法和踩过的坑都摊开讲适合正在给Agent叠功能却觉得越来越难维护的开发者也适合准备入行做Agent工程的读者。1. 先厘清概念Agent技能和工具函数、工作流到底有什么区别很多人在设计Agent时,分不清技能Skill、工具Tool和工作流Workflow的界限,结果功能模块边界模糊,复用性和可维护性都很差。我在这套agent-skills框架里,把这三者做了严格区分,并且强制团队所有成员按这个标准来定义新模块。1.1 从Prompt堆砌到技能化我踩过的第一个大坑最开始那个客服机器人,逻辑是这样的系统提示词里有大段的当用户询问订单状态时,请调用查询订单接口,并按照以下模板回复……。这种写法在小范围demo里很管用,因为任务少、场景集中,模型能够精准命中。但是当功能点增加到二十个以上,问题开始集中爆发。第一个问题是上下文稀释。二十段技能描述全部塞进系统提示词,将近4000个token被占用,真正留给对话历史和用户输入的窗口变小,模型反而开始忘记核心指令。第二个问题是触发冲突。比如查询物流和查询订单这两个描述放在一起,模型经常把物流信息当成订单信息回复,因为它们在语义上太接近了。第三个问题就是维护噩梦——运营同学说退货政策改版了,我改了一段描述,结果模型在售后场景的应答风格整体漂移,连带影响了其他功能。后来我看了几篇讲Anthropic Skill和OpenAI Function Calling的工程实践,才真正想明白一件事Agent不能活在一条巨大的Prompt里,它需要一组可以被独立加载、独立验证、独立调用的小型行为单元。这就是Skills的定位。它不是替代工具函数,而是站在工具函数之上,管理当什么场景出现时,以什么顺序调用哪些工具,以什么格式输出结果这整条行为链路。1.2 技能、工具、工作流的边界划分工具函数是单一动作。比如调用天气API获取某城市温度查数据库里某个用户的订单列表,它无状态、一次执行、单一产出。Agent技能是带有决策和编排逻辑的行为单元。它内部可能调用多个工具,也可能基于输入参数做分支判断,还可能包含上下文记忆和错误恢复机制。工作流则是偏流程化的固定管线,比如先审核资质,再扣款,再发短信通知,通常是离线的、确定性的。举个具体例子。一个处理退换货申请的技能,它内部会依次调用校验用户订单权限、核对退货政策、计算退款金额、生成退货单、通知仓库。对Agent来说,这是一件事,一个技能,一次调用但如果拆成裸工具,Agent就需要自己知道先调A再调B,如果C失败就回滚,这等于把流程逻辑写进了模型的脑子里,不可控。我在agent-skills里用了一个等价类来约束模块设计**凡是需要两步以上工具调用且有状态流转的,一律封装为技能凡是单次无状态操作,一律保持为普通工具函数凡是固定业务链路且不允许模型自由发挥的,放到工作流引擎里由代码驱动,不要交给Agent。**经过这样一刀切,整个系统的职责清晰了很多,模型只需要做两件事——判断该用哪个技能,以及按技能定义的参数规范填充信息。这也成了agent-skills核心设计的第一条铁律。2. 技能设计的地基粒度、描述与输入输出约束技能这个东西,看起来就是个JSON配一段说明,但真正决定成败的恰恰是那些最不起眼的字段。这一节我从粒度拆分、描述编写、Schema设计三个角度,把我在agent-skills里的完整做法交代清楚。2.1 粒度拆分原子技能与复合技能的取舍逻辑技能拆多细,直接决定Agent的调用成功率和维护成本。我见过两种极端一种是把发邮件拆成获取邮件列表创建邮件草稿添加收件人设置邮件主题发送邮件五个原子技能,结果Agent光决定先调哪个就晕了另一种是把处理用户投诉整个做成一个技能,里面塞了五十行内部逻辑,稍微换个需求就要动技能本体。我现在的拆分标准是以决策边界为准。一个技能应该对应一个独立、完整的决策事件是否需要使用某技能,应当是一个清晰的问题是/否,而不是分类讨论。比如对于发送邮件,Agent只需判断用户是否想发邮件,这就是一个决策事件,因此整个发邮件过程就做成一个技能,内部再去按需调用SMTP、联系人查询等底层工具。如果某个技能内部出现过多次如果用户意图A,走分支X如果意图B,走分支Y,说明这个技能拆粗了,应该把分支X和分支Y各自提升为独立技能,由上层路由来决定。还有一个隐性原因是可测试性。agent-skills的每个技能都必须配一套离线验证用例,粒度太粗的技能,输入空间太大,用例根本写不全。我现在每个技能的参数数量控制在一到三个,行为路径不超过五条,这样验证成本可控,线上出问题也容易定位。2.2 技能描述怎么写,才能让模型认准并正确触发这是整个agent-skills项目里投入产出比最高的一件事。模型不看你的代码,它只通过技能描述来决策。描述写得稀烂,底层逻辑再完美也白搭。我总结了一个五段式描述模板,每段都有明确作用触发场景明确指出什么样的用户输入应该调用本技能,并列出正反例。不要写当用户需要帮助时,要写当用户主动要求查询订单、退换货、修改收货地址时,调用本技能仅进行闲聊问候时不要调用。功能概述一句话说明这个技能完成什么任务,用动作开头,尽量包含领域关键词。执行要点模型在调用过程中需要特别注意的约束,比如不要替用户做出最终决定退款金额以系统计算结果为准,不要自行估算。输出规范明确最终输出的结构和风格。比如先给出结果摘要,再列出明细,最后提示下一步可选操作。禁忌清单列出绝对不能做的事。这一点很容易被忽略,但对于防止错误调用非常关键。五段中,触发场景和禁忌清单是影响路由准确率的决定性因素。我做过对照实验在200条测试对话上,加入禁忌清单后,错误触发率直接下降了38%。原因是大模型在决策时,负面约束提供的信号往往比正面描述更清晰。2.3 输入输出Schema给Agent装好约束的扶手如果说描述解决的是何时调用的问题,Schema解决的就是调用之后怎么填参数的问题。我在agent-skills里全部使用JSON Schema做参数约束,并且定了几条硬性规范。所有参数都要写description。哪怕参数名是user_id,也要写明用户的唯一标识,来自用户登录态,不要从对话内容中猜测。能用枚举约束的,不用自由文本。比如订单类型字段,枚举[normal_order,gift_order,exchange_order],而不是让模型随便填。必填项和可选项要标注清楚。可选项要给默认值,默认值必须是对大多数场景安全的选择。输出也要有Schema。不能只约束输入不约束输出,我用response_schema来约束技能返回的JSON结构,这样上层编排模块才能稳定解析结果。下面是我给agent-skills里查询订单技能定义的简化版Schema,你可以感受一下这个约束粒度{ name: query_order, description: 查询用户订单状态与物流信息,仅当用户明确表达查单诉求时使用。, trigger_scene: 用户询问当前订单在哪里、什么时候送达、订单状态等, avoid_conflict: 用户询问退款进度请走refund_status技能,用户询问商品信息不触发本技能, input_schema: { type: object, properties: { order_id: { type: string, description: 用户提供的订单号,若用户未提供则从对话上下文中提取,提取不到时询问用户 }, include_logistics: { type: boolean, description: 是否包含物流轨迹明细, default: true } }, required: [order_id] }, output_schema: { type: object, properties: { order_status: { type: string, enum: [pending, shipped, delivered, cancelled] }, carrier: { type: string, description: 物流公司名称,无物流信息时为空字符串 }, tracking_number: { type: string }, eta: { type: string, description: 预计送达时间 } } } }这套Schema在agent-skills里不是给人看的,而是同时给模型和校验器用的。模型拿它做函数调用参数生成,校验器在技能执行前后做参数合法性检测。两边共用一份定义,避免了模型生成一个格式,后端期待另一个格式的经典翻车。3. 路由与编排技能多了以后,如何保证用对而非用乱技能库一旦超过十个,新的问题就出现了Agent面对一堆技能,如何高效且准确地选择?我在agent-skills里尝试了三种路由方案,最后用的这套组合策略在实践中效果最好。3.1 技能不再全量注入,而是按需检索早期agent-skills把所有技能的描述全部灌进上下文,让模型自己选。技能少的时候没问题,但随着技能库扩张到二十多个,描述占了大量token,且相似技能之间互相干扰,错误率显著上升。后来我改成两阶段路由先用一个轻量的文本检索模块,根据用户当前输入召回最相关的三到五个技能,再把这些候选技能的描述注入上下文,让模型最终决策。具体实现上,recall阶段我用的是embedding向量召回加关键词加权。每个技能在注册时都会生成一个语义向量,基于它的触发场景和功能概述用户输入进来之后,计算输入向量和所有技能向量的余弦相似度,取TopN,同时如果输入文本命中了某个技能的英文名或常用别名,该技能直接进入候选集。这个方案不依赖模型,开销极低,上线后技能调用准确率从82%提升到了94%。有同行问我,为什么不直接用模型做单步路由,比如让模型输出技能ID?我的经验是当技能数量超过十五个时,让模型在对话理解和技能选择两件事上同时做判断,反而容易出错。检索召回相当于先框定一个小范围,把模型的选择压力降下来,这对开源的通用模型尤其友好。3.2 复合技能的内部编排顺序、分支与并行一个技能内部如果涉及多步骤,就需要定义编排逻辑。我在agent-skills里定义了几种简单的控制原语,避免把编排逻辑写死在代码里顺序执行sequence前一步的输出作为后一步的输入,用于流程固定的场景。条件分支branch根据参数值或中间结果,决定后续走哪个子步骤。并行执行parallel多个子步骤互不依赖,同时执行再合并结果。核心原则是编排逻辑尽量声明化,而不是命令式。也就是说,我不在技能代码里写复杂的if-else和for循环,而是用配置文件声明先做什么,再根据什么条件做什么。这么做的好处是,每一步的输入输出都可以被记录和回放,调试线上问题会轻松很多。举一个退换货技能的编排配置简化版本skill: handle_return_request steps: - id: verify_permission type: tool_call tool: check_order_owner input: order_id: {parameters.order_id} user_id: {session.user_id} - id: check_policy type: tool_call tool: get_return_policy input: sku_id: {verify_permission.sku_id} - id: calc_refund type: tool_call tool: calculate_refund_amount input: order_id: {parameters.order_id} policy: {check_policy} branches: if: {verify_permission.is_owner} true AND {check_policy.returnable} true then: continue else: return { code: REJECTED, reason: {check_policy.reject_reason} } - id: create_return_order type: tool_call tool: create_return_shipment input: order_id: {parameters.order_id} refund_amount: {calc_refund.amount} - id: notify_user type: tool_call tool: send_im_message input: text: 您的退货申请已提交,退款金额{calc_refund.amount}元,将在1-3个工作日原路返回。这套声明的编排方案,让技能内部逻辑对Agent完全透明。Agent只需要在最高层决定这个用户需要走退货流程,剩下全部由agent-skills的执行引擎驱动。模型的决策深度被降低了,错误也随之减少。4. 技能质量的验证离线跑测、上线观测与回归预防一套技能系统,最怕的就是改了一个技能,带崩了另一个技能。这个章节聊聊我在agent-skills里的质量保障手段,包含离线评估和线上监控两部分。4.1 离线验证用测试矩阵锁住每个技能的边界行为我给每个技能都强行配了一份Markdown格式的测试规范,不写测试用例不允许合代码。测试用例分四类正向触发典型的用户输入,应当明确调用该技能。反向触发相近但无关的输入,不应当调用该技能。边界参数参数缺省、参数类型错误、参数值为空串时,系统应当能兜住。组合流程涉及多技能依次触发的对话,验证技能之间切换是否顺畅。这里有个容易被忽略的点反向触发用例的价值远高于正向触发。正向触发测的是该来的来了,反向触发测的是不该来的别来。在实际业务中,错误触发对用户体验的破坏性远大于漏触发。比如用户明明在问退款什么时候到账,结果Agent却调了查询订单技能,把退款进度答成物流信息,用户直接原地崩溃。我在agent-skills里加了一条规则新技能提交时必须附带至少三条反向触发用例,并且必须描述此前其他技能的迷惑点。离线跑测我通常采用批量回归脚本,把所有测试对话喂给Agent,跑完之后对比输出与预期结果。这里强烈建议把判定方式从严格匹配改成规则匹配语义相似度打分的组合,否则自然语言的多样性会让测试天天飘红。4.2 线上观测抓住调用率、失败率与回退率线上部分,我重点盯三个指标技能调用率某技能被触发的次数占总Message的比例,突然飙升说明触发了错误路由,突然归零说明路由策略改了导致未被召回。技能执行成功率技能内部步骤全部跑通的比例。成功率下降,再结合日志判断是参数问题、下游API问题还是策略配置问题。模型回退率模型在技能执行后拒绝输出结果或要求澄清的比例。回退率上升,往往说明技能的输出和用户预期不匹配,或是输出规范有歧义。下面给出一份我常用的监控维度表指标正常范围参考异常信号排查方向技能调用率与业务流比例匹配某技能占比骤升路由召回阈值、描述改写执行成功率≥95%低于90%参数抽取、下游API稳定性模型回退率≤8%超过15%输出格式不匹配、Schema约束过严平均耗时视技能复杂度突增内部步骤串行过多、工具超时在agent-skills里,我还在每个技能执行路径上埋了trace_id,将每一步工具调用的输入输出全部串起来。这样线上出问题时,可以按trace_id直接重放整条链路,不用猜是模型选错了技能还是工具返回了脏数据。这套trace机制在最开始被人说是过度设计,但真正用了两个月后,所有人都默认新技能必须带trace才能上线。5. 避坑实录agent-skills落地过程中的典型翻车现场最后写点真正的干货,我要把开发过程中反复踩过的坑和对应的规避方式梳理一下。这些细节在官方文档里通常不会写,但实战当中几乎一定会遇到。5.1 技能描述和系统提示词互相打架我早期在系统提示词里写了一句你是电商客服助手,回复要热情友好,同时一个技能描述里又要求退货政策说明要严谨专业,避免情感化表达。结果模型在触发退货技能时,输出风格时而不伦不类。后来我制定了规则全局人格描述只能定义沟通语气,不能涉及具体业务决策,所有业务指令必须收敛到技能描述里,不能散落在系统提示词中。这条规则直接消除了大量风格漂移问题。5.2 参数抽取的漂移问题有些模型在生成参数时,会根据自己的理解脑补上下文中不存在的值。比如用户说帮我看看那个快递,并没有订单号,模型却在order_id字段填了一个臆想的字符串,导致下游接口查不到单。agent-skills的解法有两个方向一是在Schema里对关键参数开启强制校验,校验不通过则触发澄清追问流程,而不是拿脏参数去调工具二是在技能执行前加一道参数清洗,对模型生成的数值型参数做类型强转,字符串参数做非法字符过滤。这两个手段合起来,参数错误率下降了接近一半。5.3 技能膨胀后的性能劣化技能数量超过二十个,embedding召回和输入token消耗都会上升。我一度把每个技能描述写得越来越详细,结果上下文占用剧增,模型响应变慢。后来我做了一次压缩技能描述只保留触发场景、功能概述、输入参数和输出格式,把执行要点和禁忌清单移到技能内部的policy文件里,这部分内容不进入主上下文,而是由执行引擎按需加载。这相当于把描述和逻辑分离,让模型只看到决策所需信息,执行细节在引擎层面消化。压缩后,单轮对话的输入token减少了约30%,且调用准确率没有下降。这几个问题的共性在于技能系统的大部分问题不是模型不够聪明,而是上下文和约束的边界没有划清楚。把给模型看什么和由代码保证什么分清楚,很多顽疾自然就消失了。回到最开始那个客服机器人,现在agent-skills项目已经在内部跑了大半年,技能库扩充到三十七个,新增功能和调整策略都只需要在配置层完成,不需要每次重新调教模型行为。如果你正在做类似的Agent项目,我建议你把技能设计当成一个正规的开发流程来做,配独立的测试集,配路由评估,配线上监控,而不是在Prompt里反复试探。这套投入的回报,在使用者感知上也许不那么明显,但维护者看到的系统稳定性和可控性,是完全不同量级的。
路由深度实践)
