做Agent一段时间后我最大的感触是模型能力只是起点真正让Agent从“能聊天”变成“能干活”的是藏在背后那一层agent-skills。这个名字看起来简单但它决定了你的Agent是玩具还是工具。这篇文章我想把这一层的设计思路、落地方式和踩过的坑原原本本整理出来。先说清楚对象如果你正在做Agent类应用不管你是团队里的技术负责人、独立开发者还是刚接触大模型应用的新人这篇文章都会有用。它不讲模型怎么训练也不讲Prompt的花式技巧只讲一件很具体的事如何把外部能力安全、稳定、可控地交给Agent让它在真实业务里跑起来。1. 重新理解agent-skills为什么技能层成了Agent系统的分水岭1.1 技能是什么它和工具、函数有什么区别刚接触这个概念的人最容易把agent-skills看成“工具集合”的另一个说法。实际上两者有本质区别。工具是给开发者用的API函数技能是给模型用的能力描述单元——这句话值得反复看几遍。一个工具函数比如get_weather(city)它的消费者是代码调用方参数类型、返回值都写在接口文档里。但一个技能它的消费者是大语言模型。模型没有读过你的源码它只能通过一段描述文字来理解这个函数是干什么的、什么时候该调用、参数填什么。所以技能的本质是“面向模型的能力接口”而不是“面向程序的能力接口”。我见过很多失败的Agent项目最典型的原因就是把技能层做成了工具层。开发者写了二十个API函数往函数列表里一塞就指望着模型自己去理解。结果模型要么乱调用要么干脆不调用。“为什么刚才还要人教、现在要机器自己判断”这就是没想清楚技能和函数的区别。技能还需要回答三个问题什么时候用、怎么用、用了以后会发生什么。函数签名回答不了这三个问题但技能定义可以。1.2 技能层到底解决了什么问题站在产品视角Agent要做的事情无非三类获取信息、操作业务、生成内容。这三类事情都依赖外部能力但不同能力对模型的要求完全不一样。获取信息只需要只读接口模型要做的是决定“需不需要查、查什么”。操作业务涉及到写操作风险一下子高了起来模型必须非常明确地知道操作对象、操作内容和操作限制。生成内容看起来最简单实际上对参数约束要求最高模型很容易把提示词直接当成业务参数传进去制造出一堆垃圾输出。技能层最重要的工作是在模型和外部系统之间建立一个“翻译层”。它把庞大的API体系翻译成模型能看懂的、边界清晰的能力卡片。没有这层翻译Agent的能力就悬在空中每一步决策都像盲猜。我自己的经验是一个设计良好的技能层能让模型在80%的普通场景下直接做出正确选择只有在剩下的20%模糊场景里才需要额外推理。而一个设计混乱的技能层模型永远在犯错根本到不了工作流那一步。1.3 一个合格的技能定义至少包含哪些要素很多团队的技能定义只有一个字段描述文字。这远远不够。我在实际项目里会把技能拆成五个维度去定义缺一个都会在后续踩坑。第一是技能名称。不要用编号用动宾短语比如“查询库存余量”“提交退款申请”。第二是功能描述。这是给模型看的要点是场景、边界和触发条件。第三是参数Schema。包括字段名、类型、是否必填、取值范围。第四是副作用说明。这个技能会不会改数据、会不会发通知、能不能重复执行。第五是审计信息。版本号、负责人、调用权限、限流等级。看起来繁琐但每一块都有实际用途。名称决定召回率描述决定准确率Schema决定合法性副作用决定安全性审计信息决定可运维性。这五个维度合在一起才是完整的技能。2. 技能库的三种设计路线选型不是越复杂越好2.1 轻量路线JSON Schema打天下的取舍最朴素的技能定义方式就是直接把函数声明转成JSON Schema塞进模型请求里。这种方式上手快很多团队半天就能跑通。好处很明显开发速度快模型兼容性好大多数主流模型对JSON Schema的原生支持度都不错。而且排查问题时很直接模型返回什么参数一目了然。但这个路线的天花板也很低。当技能数量超过三十个以后模型的选择准确率会明显下滑。我测试过一组对比技能从20个增加到50个调用准确率大概下降10到15个百分点。因为模型需要从越来越长的函数列表里去匹配意图上下文里的干扰项变多了。用这条路线还需要非常重视描述文案的打磨。同样的函数描述写成“查询数据”和写成“当用户提到订单存量问题时调用本接口获取当前可售数量注意区分在库与在途”模型的表现会天差地别。我的习惯是每条描述都经过三轮修改第一轮自己写第二轮让同事只看描述复述功能第三轮跑测试看模型调用准确率。2.2 标准化路线协议化技能描述当技能库开始承载业务能力就值得考虑标准化协议了。现在社区里比较成熟的方案是借鉴命名空间加能力清单的做法把技能按域划分每个域下挂一组原子操作。比如订单域下面有查询订单、修改订单备注、取消订单三个技能。库存域下面有查询库存、锁定库存、释放库存三个技能。模型在做意图识别时先感知到“用户在问订单的事”再在订单域内部选具体技能。这样做的好处非常明显模型的选择范围从全量技能缩小到一个域准确率提升非常显著。我做过一个实验用标准化协议重组技能库后相同场景的调用准确率从82%提升到了94%。代价是定义工作变重了。你需要在技能之上再维护一层分组关系还要定期审查技能是否该归属当前域。对于团队协作场景协议化路线还有一个隐藏收益不同业务线的技能可以独立演进。A组维护订单技能B组维护库存技能互不干扰。只要组与组之间的边界清晰合并时只需要注册命名空间即可。2.3 内部DSL路线为复杂逻辑而生的硬核方案如果技能不再只是简单函数而是一组带流程的操作序列光靠参数Schema就不够了。比如“生成一份库存报告并发送给管理者”这个技能内部其实包含查询库存、生成摘要、寻找收件人、发送通知四步。内部DSL的玩法是用一段领域脚本把技能的内部流程固化下来模型只需要定位到技能入口剩下的流程由执行引擎控制。这样做的好处是复杂逻辑不用每次都依赖模型现场推理流程稳定且可测试。坏处也很明确你要维护一套脚本解释器还要设计DSL语法开发成本是前两种路线的几倍。如果只是一个几十个技能的轻量Agent完全没必要上DSL。我的建议是当技能内部涉及多步外部调用、存在条件分支和重试策略时再考虑走这条路线。2.4 三条路线怎么选我的个人建议是一个递进策略项目起步用轻量JSON Schema方案加速产品验证当技能数量超过30个且出现明显的选择准确率问题时做协议化改造只有当具体业务技能内部确实需要复杂流程编排时才为那一小撮技能做DSL定制。不要一开始就上一个庞大的技能编排平台那是大公司基础设施团队才会考虑的工程问题。中小团队把验证做好比什么都有意义。3. 技能从注册到调用一条链路上最容易出问题的四个环节3.1 技能注册把能力暴露给Agent不是把API列表丢给它技能注册是第一步也是最容易被低估的一步。很多系统就是把所有技能一股脑导进去让模型自己去看。正确的做法是先做一次“技能裁剪”。每次模型请求上线时根据当前会话所处的业务上下文只加载可能用到的技能子集。比如用户刚进到订单售后页面那就只把订单域和客服域的技能挂进去完全不加载库存域、营销域的技能。这一步能直接拉高模型的调用准确率因为干扰项少了。我在项目里还会做一个冷启动注册阶段新技能先以小流量方式上线只开放给内部白名单用户跑一周数据再看调用准确率。准确率不达标就继续调整描述文案不上全量。3.2 上下文与参数绑定约束模型的自由度模型在调用技能时最大的风险是参数乱填。比如一个查询接口只接收订单号但模型可能在没有任何订单号的情况下编造一个“客户提到过的编号”。解决这个问题需要双管齐下。第一是在技能描述里强调前置条件明确写“只有用户明确提供订单号时才可调用否则先反问用户”。第二是在执行层做参数校验模型返回的参数如果不符合Schema约束直接返回错误信息让模型重新生成。我在实践里发现参数校验这步绝对不能省。省了你就要处理各种诡异的脏数据进入业务系统。一个校验函数可能每小时帮你挡掉几十次非法调用。3.3 执行引擎与调度策略技能调用的生命周期管理技能调用不是发一个HTTP请求就完事它是一个完整的生命周期解析模型输出、校验参数、执行内置逻辑、处理返回结果、把结果格式化成模型能理解的文本。生命周期里最关键的环节是返回结果的处理。模型不是直接读接口返回的JSON它读的是经过格式化的文本。如果格式化做得不好信息密度太低模型就会在多个调用之间来回折腾浪费上下文窗口。调度策略方面我想特别提一个点技能调用是有代价的不是免费的。一次技能调用要消耗模型上下文、等待外部系统响应、占用执行时间。所以我的经验是设置一个调用次数的软上限。如果一个任务类型平均需要三次技能调用才能完成但某次会话已经调用了十次还在继续大概率是模型走进了循环这时候应该主动终止并询问用户。3.4 技能编排从单技能调用到多技能协作真实的业务场景很少是单个技能能搞定的。大多数情况下Agent需要在一次任务里组合调用多个技能这就要用到技能编排。编排这件事我的核心建议是能用流程固定的编排就不要依赖模型自由发挥。比如“生成库存报告并发送给管理者”这个流程里先查询库存再取收件人再发通知。这三步是完全确定的就应该做成固定流程模型只能选择要不要执行而不能决定中间步骤。反过来如果问题是开放式的比如“帮我分析一下为什么最近订单量下降了”这时候应该让模型自由选择查询订单量、查看客单价、检索近期活动三个技能的组合方式。固定编排处理确定流程自由组合处理开放问题。两者配合才是健康的技能编排体系。4. 把agent-skills落到真实项目一个模拟项目的完整拆解4.1 项目背景与目标为了把前面的思路落到实践我设计了一个模拟项目就叫它“某客服工作台智能助手”。目标很简单让一个对话式Agent处理客服日常工作中最常见的三类任务——查订单、处理售后、汇总交接班记录。这个项目设计了5个技能不贪多但每一个都完整走了一遍注册、描述、校验、执行、格式化整个过程。这样做的意义是用一个小而完整的案例把前面几章讲的设计理念串起来。4.2 技能清单与定义策略5个技能的定义如下查询订单状态。描述里强调需要用户提供订单号如果没有就反问。支持模糊搜索但必须经过用户二次确认。修改订单备注。这个技能涉及写操作描述里强调只能在用户明确要求修改时才调用且修改前必须回显修改内容给用户确认。提交售后申请。限制更强每次会话只能调用一次参数校验要求必须有申请原因。查询库存余量。只读技能描述里区分了精确查询和区间查询两种触发场景。生成交接班报告。多步编排技能内部固定流程为拉取当前会话未处理事项、汇总本班次已完成操作、生成文本报告。每个技能在注册时都带了版本号、适用会话场景标签和白名单权限标记。4.3 核心代码片段与运行效果我先给出一段技能注册表的伪代码用来演示结构设计这个设计里eligibility_checker的角色很关键。它会在技能执行前检查当前会话是否满足触发条件。比如create_refund技能同一个会话如果已经调用过一次这里就会直接拦截返回错误提示让模型向用户解释原因。为了跑通实操流程我选了一个中等体量的模型来做测试。测试任务是“帮我查一下订单12345的物流信息顺便给这个订单加个备注说一周后再发货。”模型在技能层的引导下先检索到query_order_status技能但在执行时发现该技能返回的信息里没有物流轨迹字段。这里体现出的设计细节是技能返回结果里主动暴露了“缺少信息”的标记模型意识到需要调用另一个快递查询技能于是补充了一次调用。整个会话最终走了一次技能选择、两次技能调用、一次参数修正。在我看来这个效果已经达到了可用的标准。如果把技能数量扩展到20到30个配合分组加载同样可以保持稳定。这个案例最值得参考的不是代码本身而是它在技能定义里埋的约束逻辑。每一处“如果用户没有提供某参数则先反问”的规则都在帮模型降低犯错概率而这恰好是技能层设计的核心价值。5. 常见问题与排查技巧实录5.1 模型开始乱填参数了怎么办最典型的场景是模型明明没有获取到订单号却编造了一个“看起来合理”的编号传入查询接口。遇到这种问题先别急着换模型优先级最高的是检查技能描述里是否写清楚了前置条件。我的常用改法是在技能描述开头加上“必须满足以下条件才可调用...”然后用列举句式把条件写全。改完之后跑一遍回归测试如果还出现乱填的情况再考虑在参数校验层增加强制反问逻辑检测到关键参数缺失时让执行引擎直接不发起外部调用返回“缺少订单号请先向用户索要”。实际排查的过程里七成问题都是描述不清造成的模型本身没有那么大罪过。5.2 技能调用超时答案迟迟不返回技能调用超时的原因往往不在模型而在外部依赖。比如技能内部要调用一个第三方查询接口这个接口偶尔要三秒钟才响应模型等待期间上下文状态还在继续消耗最终结果要么超时要么截断。我的做法是给每个技能配置独立的超时时间时长取决于外部接口的P95响应时间。与此同时在技能描述的显眼位置标注预期耗时“本技能通常需要1到2秒完成查询”。这样模型会提前知道该技能偏慢不会在慢技能上反复重试。如果外部接口实在不稳定我会直接把技能从模型可调用列表里摘掉放到固定流程里由程序自动兜底调用避免模型一次次地去撞同一堵墙。5.3 多技能组合时上下文爆炸当模型需要连续调用多个技能时每个技能的返回结果都会留在对话历史里。技能数量一多上下文里堆积了半屏的工具返回JSON真正有用的业务信息反而被冲淡了。我解决这个问题的方式是给技能返回信息加上严格的摘要层。每个技能执行完以后不是把完整结果返回给模型而是只返回一个摘要最多两句话加三个关键值。比如仓库查询返回的是“余量充足建议配件库存提交补货申请”而不是一张25行的库存流水表。这样调整后同一个任务的模型输入长度能压缩40%以上而且模型做后续判断时更聚焦。摘要层的实现也很简单给每个技能配置一个提炼函数即可不需要复杂模型参与。5.4 安全边界不能让模型什么都做最后说一个容易被忽视的问题技能层不能只考虑效果还要考虑安全边界。这里不只是指权限控制还包括业务风险的边界设定。再举一个例子某次测试里用户对模型说“把最近一周所有订单都打八折”。这个请求触碰了价格操作技能但这个技能并没用对应的权限标记。由于权限校验在技能执行前就拦截了这次调用模型被迫向用户解释“当前账号没有价格修改权限”。这就是技能层安全边界的价值让模型犯错但不能让系统承担风险。我在每个技能定义里都会加一个权限位配置。凡是涉及资金、价格、批量操作的技能权限校验绝不可跳过而且要有审计日志。做技能层时间越久我越觉得这个系统的核心不是技术挑战而是工程取舍。每一次技能边界的确定、每一句描述的打磨、每一个约束条件的添加都在真实地影响Agent的能力上限。希望这篇文章能帮你少走一些弯路把agent-skills真正做扎实。
