这两年做大模型应用一个感受越来越强烈决定Agent上限的往往不是模型本身而是它身边那套“技能系统”设计得怎么样。我见过不少团队模型换了一版又一版效果却一直卡在及格线。后来把精力挪到技能库建设上同一个模型任务完成率直接翻了一番。这里说的“agent-skills”本质上就是给智能体装上一套可注册、可检索、可调用的能力中枢——把模型不会做、做不好的事拆成它用起来顺手、执行起来可靠的标准件。这篇文章我会围绕技能系统的核心机制、构建路径和真实场景里的坑把从零到一的设计思路完整过一遍。适合正在做Agent应用、或者准备把业务接入智能体的团队参考。1. Agent Skills到底解决什么问题从“会接话”到“能办事”先聊一个基本问题模型本身已经很能打了为什么还要单独搞一套技能系统这个想不清楚后面所有设计都会跑偏。1.1 模型的“知道”和系统的“做到”之间隔着一条鸿沟大语言模型擅长的是文本生成、语义理解、逻辑推理它“知道”很多事但不代表它能“做到”那些事。比如让它查一下你公司上季度的营收数据模型可以回答出“需要查询财务系统”但它自己连不上数据库拿不到token更不会调用内部API。这时候就需要一套机制把“模型意图”翻译成“真实动作”再把“动作结果”反馈回给模型。这套机制就是技能系统。另一个被很多人忽略的点模型的推理是概率性的同一个问题换个问法它可能给出不一样的中间判断。但业务执行是确定性的——你不可能让订单系统“也许”创建订单、“大概”扣款。技能系统本质上是在模型的概率世界和业务的确定性世界之间加了一层可控制的缓冲带。它把那些必须精确、稳定、可审计的操作从模型的语言生成里剥离出来固化成代码逻辑。这正是“agent-skills”这套设计理念存在的根本理由。1.2 Skill、Tool、Workflow三者到底有什么区别很多刚接触Agent的读者会把技能Skill、工具Tool、工作流Workflow混为一谈这里先把边界划清楚。Tool是最小可执行单元比如“发送HTTP请求”“读取文件内容”“发送邮件”。它通常是无状态的输入参数、调用执行、返回结果一次完成。Tool本身不带业务判断像一把螺丝刀你告诉它拧哪颗螺丝它就拧哪颗。Skill是围绕某个能力域的Tool集合加编排逻辑。比如“客户信息查询技能”可能包含“搜索客户”“查询订单”“获取售后记录”三个Tool并且定义了“先查客户、再关联订单、最后补售后信息”的调用顺序。Skill有状态有内部逻辑像一个工具箱加一份使用说明。Workflow则是面向完整业务场景的流程编排往往跨多个Skill包含条件分支、人工审批、异常回退等。比如“客户投诉处理工作流”会先调用“客户信息查询技能”定位客户再用“工单管理技能”建单必要时触发“退款技能”走审批流程。一句话总结Tool管动作Skill管能力域Workflow管业务流程。技能系统处在中间层向上承接流程编排向下调度工具执行是Agent架构里承上启下的核心关节。1.3 技能系统如何决定Agent的实际能力边界有一个判断我越来越确信评测Agent的能力不如去数它注册了多少个高质量技能。技能库的丰富度直接决定了Agent能处理多少种任务而技能的设计质量决定了任务完成的可靠度。实际跑业务的时候你会发现模型的上下文窗口再大也没法装下所有操作细节。技能系统相当于给Agent外挂了一个“能力外脑”——模型只需要知道“遇到什么问题去找哪个技能”具体的执行步骤、参数规则、异常处理都被封装在技能内部。这既节省了模型有限的注意力资源也降低了业务操作的出错概率。换个角度如果把模型比作一个人的大脑技能系统就是他的双手和工具箱没有后者想法永远只是想法。2. 技能的形式化定义与注册机制让模型“看得懂”还能“用得好”既然技能这么关键第一步就是把技能本身设计成一种既规范、又对模型友好的形态。这块做得不好后面检索再先进也白搭。2.1 一个技能的基本组成描述、参数Schema、执行体我通常把一个技能拆成三个组成部分缺一不可。技能描述Description用自然语言说明这个技能“是干什么的、在什么场景下用、有什么注意事项”。这段文字不是写给人看的文档而是写给模型看的“使用说明书”。模型靠它决定“当前这个任务要不要调用该技能”所以描述里必须说清楚适用条件和边界。比如一个“天气查询”技能描述里就要写“用于查询中国任意城市未来3-7天的天气预报支持按城市名称定位不适合查询历史天气”。参数SchemaParameter Schema定义调用技能需要传入哪些参数、每个参数的类型和约束。这是技能和模型之间的“接口契约”。设计得越严谨模型越不容易传错参数。比如天气查询技能参数可以定义为城市名称string、日期范围string格式YYYY-MM-DD、可选单位enum: celsius/fahrenheit。Schema不仅约束参数格式还隐含了调用方式的引导——模型读到清晰的Schema会自然按部就班地组织参数。执行体Executor实际跑逻辑的代码。它接收Schema定义的参数完成真实操作返回结构化结果。执行体可以是一个Python函数、一个API封装、一段SQL查询、甚至一个命令行脚本。唯一要求是输入输出都必须是结构化、可序列化的方便模型理解和继续处理。2.2 描述工程为什么模型总是“看不懂”你写的技能说明我见过太多团队技能逻辑写得很扎实但模型就是调不对。后来一排查问题出在描述上——要么太笼统要么太技术化模型根本没法把“用户需求”和“技能描述”对上号。举一个真实案例。有个团队做了一个“商品比价技能”描述写成“比较各大电商平台同类商品的价格差异并输出对比结果”。看起来没毛病实际测试发现模型经常在用户问“这个手机哪家买便宜”时不触发该技能反而自己去编答案。后来把描述改成“当用户希望比较同一商品在不同电商平台如京东、天猫、拼多多的价格高低时使用本技能。注意必须先通过商品名称或型号精确锁定商品再执行比价若用户未指定具体商品应主动询问商品名称后再调用。”效果立刻改善。核心差异在于好描述是从“模型决策视角”出发写的而不是从“功能视角”出发写的。它告诉模型“什么时候该用、用之前要满足什么前提、有哪些坑要注意”而不是干巴巴地描述“我能做什么”。2.3 参数Schema的设计原则把“模型的自由发挥”关进笼子关于参数Schema三条经验值得分享第一尽量减少必填参数的数量。每一个必填参数都是模型的一次“犯错机会”。能通过默认值解决的就别设计成必填。比如超时时间、返回条数这类可以给默认值真正必填的通常只有定位任务核心的那一两个参数。第二用枚举值代替自由文本用正则约束格式。比如结果排序方式与其让模型传任意字符串不如定义成枚举popularprice_ascprice_descprice_asc。这样模型的选择空间被限制在可控范围内执行体收到非法参数的概率大大降低。日期、手机号这类格式明确的字段配上正则校验提前拦截脏数据。第三参数之间的依赖关系要在Schema里说清楚。比如“查询订单必须传订单号或手机号二选一”这种约束最好在描述里用For Example写出正确和错误的调用示例。模型对“示例”的遵循能力远高于对“规则”的遵循能力多给几个正例和反例参数调用准确率能提升不少。2.4 技能注册的完整流程从定义到上线的规范化步骤技能的注册流程看起来简单实际跑起来有很多细节。我建议按下面这条链路走需求分析跟业务方确认这个技能要覆盖哪些场景、支持哪些输入形态、输出给谁看。形式化定义按照上面说的三件套写出描述、参数Schema评审通过后冻结第一版。执行体开发先实现一个最小可用版本用Mock数据自测保证单次调用逻辑正确、异常路径可控。单技能评测用一批“真实用户问题”跑一遍重点看模型能不能正确触发技能、参数传得对不对、返回值是否满足需求。这一步最容易暴露描述和Schema的问题。联调与灰度把技能接入完整的Agent链路先用小流量测试确认不影响其他技能的正常调用。上线与监控技能上线不是终点要持续看调用成功率、参数错误率、用户反馈形成迭代闭环。3. 技能的检索与路由怎么让Agent在关键时刻选对技能技能库一旦上了规模几十个、上百个一个新的问题浮出水面面对用户五花八门的需求模型怎么知道该调哪个技能这就涉及技能的检索与路由机制。3.1 路由的三种主流策略规则路由、向量检索、模型直选规则路由是最朴素的方式适合技能数量少、边界清晰的场景。通过关键词匹配或固定规则把用户请求映射到特定技能。比如用户问题里包含“天气”就路由到天气查询技能。优点是确定性强、可控性好、执行速度快缺点是规则维护成本高覆盖不了长尾需求用户换个说法规则可能就失效了。向量检索是把用户请求和所有技能的描述都做嵌入Embedding算相似度取top-k个候选技能。这种方式对模糊表达、同义改写有较好的容忍度适合技能数量多、边界模糊的场景。但它有个问题相似度高的技能不一定就是用户需要的检索结果只能做“候选”后面还得靠模型精排。模型直选是把“用户请求候选技能列表”交给模型让模型直接输出要调用哪个技能及其参数。这是目前主流方案。模型理解复杂指令的能力强能结合上下文做综合判断。但模型直选对候选列表的质量很敏感——如果候选列表里没有正确技能模型再聪明也无能为力。实际工程里三种策略不是互斥的而是分层配合规则路由做第一层粗筛拦截明显的关键词触发向量检索做第二层候选扩充模型直选做最后决策。三层配合能把技能选择准确率做到比较理想的水平。3.2 技能目录的组织方式分类、标签与索引的三层结构技能多了之后目录管理就成了刚需。我之前踩过“平铺列表”的坑150多个技能平铺在一起光是维护描述都让人崩溃模型每次要在一堆候选里大海捞针。后来规范成三层结构路由准确率和维护效率都明显改善。技能分类Category按业务域划分比如“客户管理”“订单交易”“营销活动”“数据报表”每个技能归属唯一分类。模型路由时先定分类缩小候选范围。技能标签Tag跨分类的灵活标记比如“只读”“高权限”“第三方依赖”“实验性”。标签用于辅助筛选比如高权限类技能在非授权场景下直接过滤掉。技能索引Index指向技能文档、测试用例、版本记录、负责人信息。索引不参与在线路由但支撑离线评测和排查问题。这套三层结构本质上是在为模型建立一个“先粗后细”的检索漏斗。分类缩小范围标签过滤掉不合规选项最终进入模型决策视野的候选技能数量控制在个位数决策质量自然就上来了。3.3 路由冲突消解两个技能都说“我能做”怎么办技能规模大了一个常见问题是同一个用户需求多个技能都声称自己可以处理。比如“查询订单物流”和“查询订单详情”两个技能用户问“我的快递到哪了”两者的描述可能都会命中。这时候如果选错轻则返回内容不对重则调用出错。三个实用的消解策略第一细化描述划清边界。在技能描述里明确写出“本技能不处理什么”。比如订单物流技能写明“仅提供物流轨迹查询不包含订单金额、商品列表等订单详情信息”模型读到边界后取舍就清晰了。第二定义技能优先级和互斥关系。在技能元信息里标注Priority字段当多个技能都满足触发条件时优先选高优先级技能同时可以配置Exclusive列表声明哪些技能不能同时被选中。比如“创建订单”和“查询订单”可以共存但“创建订单”和“修改订单”在同一会话里互斥因为业务上不允许先建再改的混乱逻辑。第三引入用户确认机制。当候选技能得分非常接近、模型难以决策时不要硬猜直接反问用户。比如“您是想查询物流进度还是查看完整的订单信息”让用户来做最终决策。这虽然是“笨办法”却是准确率最高的兜底方案。3.4 上下文增强路由让历史对话参与技能选择在一次多轮对话里用户的需求往往是渐进清晰的。比如用户先说“帮我查个东西”模型无法判断查什么下一句“上次买的那双鞋发货了没”结合历史才知道是要查订单物流。所以技能路由不能只分析当前这一句要把对话历史一并纳入决策上下文。工程实现上一般把最近几轮对话、当前用户的身份信息、当前页面/场景标识拼接到路由输入里。比如客服场景中用户已登录可以直接拿到用户ID用户在商品详情页发起咨询就优先路由商品咨询类技能。场景信息Intent Context本身就能过滤掉大量无关技能是路由效果最容易被忽视的杠杆。4. 从零构建一个技能库选型、开发与测试的完整路径理论聊了不少这一章直接给一套可落地的实操路径。从需求梳理到上线监控每一步该做什么、用什么工具、怎么验证一次说清楚。4.1 第一步需求盘点——哪些场景真正值得做成技能不是所有功能都值得封装成技能。开发技能是有成本的描述要设计、执行体要维护、路由要调优。所以第一步是给需求排优先级。我的筛选标准有三个高频这个功能用户经常触发。一天用不到几次的不值得做成技能。确定性输入输出边界清晰结果可预期。太开放的任务比如“帮我想个方案”不适合做成技能。复用性多个业务场景都能用不是一次性需求。比如“发送短信验证码”可以在注册、登录、找回密码等多个流程复用价值就很高。按这三个标准把需求过一遍能做成技能的需求自然浮出水面。不要贪多先做10个高质量技能好过做50个半吊子技能。4.2 第二步技术选型——技能框架和运行环境怎么选技能系统的技术选型核心是解决两件事技能怎么描述和技能怎么执行。描述层面业界主流做法是采用类似OpenAPI的规范来定义技能接口同时用自然语言描述补充模型的语义理解。也有团队直接用纯Python装饰器把函数暴露成技能运行时自动生成描述和参数Schema。这条路对开发效率友好适合内部快速验证。执行层面一个值得认真考虑的问题是技能和Agent主进程跑在一起还是分离部署。小规模场景跑在一起最简单但技能多了以后单个技能的异常内存溢出、死循环可能拖垮整个Agent。专业一点的做法是把技能做成独立服务通过RPC或HTTP调用每个技能有独立的进程隔离和资源限制。这个取舍没有标准答案关键看团队的运维能力。额外提醒一个容易忽略的选型点技能的版本管理和平滑升级。技能描述和参数Schema一旦被模型“记住”变更可能影响路由效果。所以要用类似DAG有向无环图的方式管理技能版本线上调用稳定版本新版本在灰度验证通过后再全量切换。4.3 第三步技能开发——“最小可用”到“稳定可靠”的迭代节奏单个技能的开发我推荐按“最小可用版本 → 真实场景打磨 → 异常加固”三步走。最小可用版本的目标是快速跑通链路不要一开始就追求功能全面。先覆盖最核心的调用路径把技能挂到Agent上用真实用户问题验证“模型能不能找到它、描述有没有歧义、参数传得对不对”。这个阶段发现的描述问题、Schema问题比执行体的bug影响更大一定要优先修。跑通之后进入真实场景打磨。一方面补充边界输入空参数、超长文本、特殊字符另一方面补充边界场景数据不存在、接口超时、权限不足。这时候你会发现真正的工程量不在于“正常路径”而在于“异常路径”的处理设计。最后是异常加固。给技能的执行体套上统一的异常捕获和重试机制返回稳定的错误码和错误信息。每个技能都要回答一个问题当它失败时Agent下一步该怎么做是换个技能重试还是向用户解释原因还是转人工这条“失败路径”设计得越好用户体验越稳。4.4 第四步技能测试——除了“正确性”还要测“可发现性”技能测试比普通代码测试多一个维度——不仅要测执行体的逻辑正确性还要测模型的“可发现性”。也就是说在大量真实用户问题下模型能不能稳定触发该技能、能不能准确传参。我自己常用的评测方法是构建一个“技能需求测试集”每条样本包含用户问题含多种表达方式、期望调用的技能、期望的参数。跑评测时加载Agent对测试集逐条执行统计三个指标触发准确率应该调该技能的问题里有多少比例正确调用了。参数准确率正确触发的调用中有多少比例参数传得完全正确。误触率不该调该技能的问题里有多少比例被错误调用了。这三个指标分别对应描述质量、Schema质量和边界划分质量。每次迭代描述或Schema后用同一套测试集回归就能直观看到改动是否有效。这个测试集要持续扩充把用户真实反馈里的失败样本吸收进来避免问题二次发生。5. 实战中的坑与解法我在技能系统上踩过的那些“看不见的地雷”这章写点更实在的东西——那些文档里不写、网上案例也少、只有自己趟过才知道的细节问题。每一条都是用真实时间换来的教训。5.1 描述与实现不一致模型按“描述”行事你却按“代码”交付技能描述写得很美好执行体实现跟不上这是最常见也最隐蔽的坑。比如描述里写“支持查询任意城市的天气”执行体接第三方接口实际只覆盖了国内城市用户问“纽约天气”时模型照常触发技能返回结果却是“暂不支持该城市”。用户的感受就是这Agent能力不行。解法没什么技巧建立描述与实现的一致性校验机制。技能注册时必须附带一份“能力自查清单”逐条确认描述里的每个承诺都有实际实现支撑。每次执行体变更同步检查描述是否需要修订。宁可让描述更保守也别让描述超出实现。5.2 参数语义理解偏差模型把“事件时间”理解成了“当前时间”在参数提取时模型经常犯一类语义错误把用户在自然语言里表达的相对时间错误地理解成绝对时间。比如用户说“查一下上周的销售数据”模型可能提取出一个错误的时间参数直接查了本周数据返回结果用户一眼就能看出不对劲但问题出在参数理解上而且极难在常规测试里发现。解决思路是“相对时间”问题尽量不在模型层解决而在执行体层解决。参数Schema只接收标准格式的绝对时间执行体内部可以对“相对时间”做二次解析或校验。或者更简单当模型识别出时间类参数时强制要求它输出“参考日期”字段执行体基于参考日期做相对时间计算减少歧义。这类“语义归位”的细节设计往往比调模型prompt更有效。5.3 技能间的隐式依赖单个技能都正常连起来就翻车每个技能单独测试都通过但Agent在真实链路里却频繁出错这种情况多半是技能之间存在隐式依赖。最常见的例子技能A返回的数据格式是技能B的输入Schema不兼容的。比如A返回“userId”B的参数名叫“customerId”模型把值填进去没问题但语义上这两个是否一致如果不一致B拿到的就是错误ID查出来的结果是别人的数据——这种错误最危险因为它表面看起来“成功了”。解法是设计一个统一的数据契约层技能间的数据传递都走标准化的数据格式字段名、类型、精度全局统一。每个技能在注册时声明自己的“输入数据依赖”Agent在编排时自动做格式转换或校验而不是把转换责任丢给模型临场发挥。5.4 状态管理混乱技能记不住上下文多轮对话断片多轮对话场景中一个高频痛点用户第一轮让Agent查了订单第二轮说“帮我退款”Agent却不知道“这个订单”指的是哪个订单。这是因为技能系统默认是无状态的每次调用都从零开始没有把上一轮的上下文带入下一轮。稳妥的方案是引入会话级状态管理。在对话上下文中显式存入关键状态字段比如当前选中的订单ID、当前用户身份、当前操作对象。Agent编排时优先读取状态字段而不是让模型每轮重新理解一遍。状态字段的生命周期要明确会话内有效、会话结束清理、敏感信息加密存储。记住让状态管理显式化比让模型“隐含记住”可靠得多。6. 技能的质量评估与持续迭代怎么证明你的技能库在变好到这一步技能库已经有了一定规模能跑通不少业务。但一个躲不开的问题是如何证明它确实在变好评估体系和迭代机制缺一不可。6.1 从“调用量”到“任务完成率”找到正确的北极星指标很多人一开始用“技能调用次数”来衡量技能的价值这个指标会骗人。调用次数多可能只是说明技能被频繁触发并不代表用户的任务被顺利解决。我建议把核心指标定在任务完成率上也就是用户发起一个需求Agent在整段对话里是否最终实现了用户目标。具体到技能层拆解为四个细分指标触发准确率该用某个技能的问题里正确触发比例。参数有效调用率触发的调用里参数合法且执行成功的比例。结果采纳率执行成功后返回结果被用户认可并按需使用的比例可以用用户反馈、点击行为等代理指标。技能失败恢复率技能执行失败后Agent还能通过其他方式完成同一目标的比例。这四个指标合在一起才算是完整刻画了技能在真实业务中的价值。单独看任何一个都容易产生错觉。6.2 线上监控与链路追踪技能出问题时怎么快速定位技能规模变大之后排障效率会成为新的瓶颈。我的经验是要建立一套从“用户会话”到“技能调用”的可追踪链路。每次技能调用至少要记录以下信息会话ID和用户ID触发时的用户原始问题完整原文模型选中的技能名称和置信度传入参数的完整快照执行体的返回结果或错误信息单次调用的耗时和资源消耗这些日志统一沉淀到检索系统里支持按会话ID查全链路按技能名称查调用分布。排查问题时最有效的起手式通常都是把失败会话的原始日志拉出来看模型是怎么理解用户意图的、为什么选了某个技能、参数在哪个环节出了问题。这一步不需要多高深的技术但能把排查时间从小时级降到分钟级。6.3 从反馈闭环到技能演进把每一次失败变成技能升级的燃料评估体系建立的最终目的是驱动技能持续演进。我把这个闭环总结成四步收集失败样本从线上日志里把任务完成失败的会话捞出来按失败原因打标签描述歧义、参数错误、执行异常、路由误选。聚类分析根因把相似失败样本归成一类找到共性原因。通常80%的失败集中在少数几个根因上优先处理Top类目。针对性优化根据根因调整技能描述、Schema、执行体或路由策略。每次改动要小以便评估效果。批量回归验证把修改后的技能放回评测集里全量跑一遍确保修复了旧问题、没有引入新问题。我见过最高效的团队几乎把“失败样本→根因分析→技能迭代”跑成了日常机制每周都有版本更新技能库在持续迭代中变得越来越厚实。反观那些上线后就不动的技能库三个月后基本就沦为“演示环境能跑、生产环境没法用”的花架子。自己做完这套体系后的体会是Agent类项目拼到最后拼的不是谁家模型参数大而是谁的技能库更厚、更稳、更能抗真实业务的杂音。模型是发动机技能库才是底盘和悬挂。发动机决定极速底盘决定你到底能开多快而不翻车。希望这篇文章能帮正准备建技能库、或者已经在路上被各种问题困扰的团队少走几段弯路。
