接手 agent-skills 这个选题时我脑子里马上浮现出前段时间做某客服智能体项目时被技能设计折磨的经历。agent-skills说白了就是给大模型 Agent 配备的能力工具箱让它能按需调用搜索、计算、查库存、发消息这些具体动作。它不是一套高高在上的理论框架而是每个做 Agent 应用的人都绕不过去的工程实活。这篇文章我想从技能库的设计思路、实现细节、踩坑记录三个层面把我实际跑过的方案和教训完整摊开来讲。无论是刚接触 Agent 开发、想弄清楚技能和工具界限的入门者还是正在为技能调用不准、编排混乱头疼的实践者应该都能在这里找到能直接抄作业的部分。1. 先搞清楚技能在智能体里到底是个什么角色1.1 技能与工具的分界线很多人一开始会把 agent-skills 理解成简单的函数调用觉得定义几个接口、让模型选一下参数再执行就完事了。但真正做过几个项目之后你会发现技能和普通工具之间有一条非常重要的分界线工具是能做什么技能是知道什么时候该做什么、怎么做更稳妥。我习惯这样区分工具是原子化的操作能力比如发送HTTP请求执行SQL查询技能则是围绕一个完整任务目标封装的能力单元它可能内部会调用多个工具、编排多步逻辑、甚至包含兜底策略。举个例子单看查询订单物流这个动作如果只是暴露一个 API 接口模型经常会在用户说我的快递到哪了时犹豫要不要调用因为它拿不准这个接口接收什么参数、返回什么格式。但如果你把它封装成一个技能描述写成当用户询问订单包裹的当前物流位置、配送进度或预计到达时间时使用输入订单号或手机号后四位模型几乎不需要推理成本就能正确触发。这个区别在实际项目中带来的体验差异是肉眼可见的。我见过不少团队直接把底层函数一股脑塞给模型结果模型要么频繁误调用要么在参数上反复试探。把能力整理成技能本质上是在模型和操作之间加了一层语义翻译和策略缓冲让模型从猜测怎么用变成按需选用。1.2 设计技能库的顶层思路做技能库设计时我一般先问自己三个问题用户会在这个场景里提出哪些类型的目标诉求完成这些目标需要哪些外部信息和操作哪些操作之间存在明显的先后顺序或互斥关系我的顶层思路是按目标聚类、按边界隔离。按目标聚类就是把相近的诉求归到一个技能下比如查询天气查询空气质量查询穿衣建议可以合成一个环境信息查询技能组内部再做分支按边界隔离就是确保每个技能只对自己的输入输出负责不越界去改别的技能的状态。这种设计在后期维护和调试时会非常省力因为问题可以被快速定位到具体某个技能上而不是在纠缠不清的调用链里反复翻找。另一个重要原则是控制技能数量。模型可选的技能越多选择正确性的压力就越大。我通常会把某个业务 Agent 的单次可用技能数量控制在 15 到 25 个之间超过这个量就考虑做技能分组或分层路由。你可以在上层设置一个路由技能让它先判断用户诉求属于哪一类再去对应的子技能列表里做选择。这有点像把一个 200 人的公司拆成几个部门而不是让 CEO 直接面对所有人。2. 技能的骨架描述、参数与实现2.1 技能描述直接影响模型判断力的头号因素如果说技能设计里有一个最值得花时间的环节那一定是描述撰写。大多数模型调用不准的问题根源不是模型能力不行而是技能描述写得太模糊或太误导。我总结了一套描述撰写的公式触发条件 目标对象 输入来源 典型示例。触发条件说明什么场景下该用目标对象说明这个技能是服务哪类诉求的输入来源说明参数从哪里来典型示例则给模型一个参照样本。举个例子如果一个查询会员积分技能描述可以写成当用户询问自己的积分余额、积分明细或积分兑换进度时使用通常需要从用户会话中提取会员ID若用户未提供会员ID则提示其先登录。这一句话就把何时用怎么取参失败怎么办全部交代清楚了。我在这个环节踩过的坑是过度追求精简。早期为了省 token我把描述压缩成查询积分结果模型把它用在任何和会员相关的场景里比如查会员等级、查开卡时间导致大量误调用。后来我放宽描述到完整的一句话加了边界说明仅用于积分相关查询不包含等级、优惠券、订单等信息误调用率立刻降了下来。描述不是越短越好关键信息齐全才是第一位的。2.2 参数定义用 JSON Schema 把规矩立好技能参数是模型最容易出错的地方参数定义不清晰模型就会开始脑补不存在的字段。我推荐所有技能参数统一用 JSON Schema 规范定义这会让参数校验、文档生成和调用链追踪都变得顺畅。定义参数时要注意三点。第一字段名用全小写下划线风格避免大小写混用。模型在生成参数名时往往会参考字段名风格你保持统一它就不容易创造变体。第二所有参数必须给出清晰的 description并且注明来源路径。比如用户在下单流程中填写的收货地址ID就比地址ID好一百倍前者明确告诉模型去哪里找这个值。第三必填参数不要太多。我见过一个技能定义了 8 个必填参数模型每次调用都在和参数纠结失败率高得离谱。尽可能把能推断出来的参数都设为可选由函数内部通过上下文补齐。还有一个常见问题是参数类型拿不准。模型经常把数字参数生成成字符串或者把枚举值写成自由文本。我的解决办法是在 JSON Schema 里用 enum 明确列出可接受的值再配合实现函数里的强校验。宁可让调用因为非法参数失败也不要让模型带着脏数据去执行操作。2.3 实现函数保持单一职责别把逻辑写死技能的实现函数是真正干活的地方。我在写实现时严格遵循单一职责原则一个技能只完成一件完整的事情不要在技能内部塞入过多分支更不要把业务决策硬编码在函数里。举个例子如果做一个商品推荐技能正确做法是内部只负责接收用户偏好和商品池数据返回排序后的推荐列表。至于用户是不是会员今天是不是大促日这类业务判断应该放到编排层或让模型通过其他技能获取后再决定调用哪个推荐策略。把业务逻辑写死在技能函数里短期看执行效率高长期看每次业务调整都要改代码技能库就变成了一个谁也动不了的泥潭。函数内部的容错处理也必须做足。外部 API 超时、返回空数据、字段缺失这些都要有默认分支。我一般在函数开头做参数清洗中间做核心逻辑结尾做统一返回结构包装。返回结构建议固定为包含 code、data、message 的字典这样模型拿到结果后能迅速判断是继续追问、直接答复还是换一种方案。3. 从零组装一套可用的技能库3.1 盘点能力清单画出边界动手写代码之前先做能力盘点。我会把目标场景拆成一个个用户可感知的服务动作然后逐个判断这些动作是纯模型知识就能完成的还是需要外部数据、外部操作参与。纯知识的部分不需要做成技能让模型直接回答就好涉及外部依赖的才需要封装成技能。完成盘点后画一张技能边界表列出技能名、输入、输出、依赖的数据源、依赖的其他技能。这个步骤很多人嫌麻烦会跳过但等到技能越来越多边界模糊引发冲突时你会非常怀念这张表。我当时在一个项目里没有及时更新边界表结果后来新增了一个查询订单技能和已有的售后进度查询功能重叠模型在两个技能之间反复横跳而且用户问题稍微绕一点两个都触发不了排查了半天才发现问题出在边界设计上。画边界表时还要特别注意互斥关系。比如取消订单和修改订单地址在业务上就不可能同时出现在同一轮对话里如果两个技能同时可被调用模型有时候会给出荒诞的组合操作。解决办法是在描述里写清楚当订单已发货时不可取消或者干脆在编排层加一道规则。3.2 技能注册与动态加载技能库搭好了接下来要解决的是模型到底能看到哪些技能。这一步不能偷懒把所有技能一次性灌给模型我采用的是注册中心加动态加载的方案。注册中心维护一份技能元数据表记录每个技能的名称、描述、参数 Schema、依赖关系、所属分组。模型每次发起会话时先由路由层根据用户当前话题和会话上下文从注册中心拉取候选技能列表再把这些候选技能的描述和参数 Schema 注入到模型提示词中。这么做的好处是既保证了模型在大部分情况下只面对小范围的技能选择又不会因为静态加载导致技能更新需要重启服务。动态加载还有一个隐藏优势就是可以做技能灰度。新技能上线时可以只在部分会话中启用观察调用率和成功率稳定后再全量放开。我在项目中靠这个机制避免过一次事故新加的一个查询技能描述有歧义灰度时发现它的误调用率特别高于是赶紧撤下修正描述没有影响到正式用户。3.3 编排层从单人技能到团队协作单技能能干活但复杂任务往往需要多个技能前后配合。编排层就是负责把多个技能串成一条流水线的地方。我在实践里把编排分为两种模式。一种是模型自主编排也就是把技能列表交给模型让模型自己决定调用顺序和嵌套方式。这种模式适合开放性强的场景比如帮我规划一条周末出游路线模型可能先查询天气再查景点开放时间然后调用地图服务生成路线。另一种是预定义流程编排针对那些步骤固定的业务场景比如退货流程先创建退货申请、再来安排上门取件、最后跟踪退款状态这三个步骤顺序不能乱我会在编排层用状态机来控制不让模型自由发挥。两种模式不是互斥的。我的项目里通常核心链路用预定义流程外围服务用自主编排。这种混合结构既保证了主流程的稳定性又不会让模型在需要灵活应变的地方束手束脚。如果你发现模型在编排时老是在两个技能之间来回折腾建议把它直接固化成一条预定义流程既能降低 token 消耗又能减少出错概率。4. 实测下来的坑与排查手册4.1 描述被模型忽略的排查套路我遇到过很多次技能描述明明写清楚了模型却还是不调用的情况。排查下来原因五花八门但有一个共性规律描述里的关键词和用户问法之间存在较大的表达距离。比如用户习惯说我这个月的账单多少技能描述写的是查询用户月度消费汇总模型可能就联想不到。排查方法是模拟用户高频问法挨个测试技能是否能被正确触发。我会整理一份问法清单每一条都是一个真实用户说过的句子然后批量跑一遍 Agent把那些没有触发对应技能的案例收集起来反推是描述缺了同义关键词还是技能边界描述误导了模型。还有一种隐蔽情况是描述之间相互污染。如果两个技能的描述里都出现了订单查询进度这些词模型会非常迷惑。解决方案是我提到的边界表在描述里明确写本技能不处理XXX来切断关联。实测发现加入一句反方向排除说明技能之间的误触发率能降低 40% 以上。4.2 参数幻觉与校验兜底模型在调用技能时产生不存在的参数值这个坑几乎每个项目都会踩。表现是用户没提的手机号、订单号模型凭空生成一个看似合理的数字填进去让技能去查询一个根本没有的数据。根治这个问题的第一步是让参数有可追溯的来源。我要求所有技能参数在描述里注明获取方式比如从用户历史订单记录中提取询问用户获取。第二步是实现层做兜底校验参数缺失或校验不通过时不要直接报错而是返回一个提示信息让模型知道该向用户索要哪些信息。也就是说技能函数要有能力把缺参数反馈转化成模型追问用户的输入。校验逻辑我建议做成独立的工具函数不要在技能内部重复实现一遍。统一校验的好处是可以统计各技能的参数缺失率哪个技能老是让模型猜参数说明它的参数定义或者交互方式有问题需要针对性优化。4.3 技能冲突与责任边界当技能库扩大到一定规模技能之间的责任重叠一定会出现。我用过一个查天气技能和一个推荐穿衣技能结果用户在问今天适合穿什么时模型一会儿调天气一会儿调穿衣推荐产出内容还彼此矛盾。解决这类冲突有两种思路合并或者分层。把天气查询合并进穿衣推荐技能作为一个内部数据源这样模型只需要面对一个技能决策路径短了准确性自然会上去。如果因为架构原因不能合并就做一个上层路由技能先判断用户的问题更偏向信息获取还是决策建议再分流到底层技能。我用分层方案居多因为合并会让技能膨胀失去复用的灵活性。冲突问题的排查技巧是开启调用日志追踪记录每次模型调用了哪个技能、参数是什么、结果如何、最终回答的文本是什么。把日志按技能维度聚合你会立刻看出哪些技能经常被一起调用、哪些技能调用后最终回答里根本没用上它的输出。后者就是典型的冗余技能可以考虑下线或者合并。4.4 技能评估与持续优化技能做出来不是一劳永逸的要建立一套持续评估机制。我在每个技能上线时都会记录两条核心指标调用准确率和任务完成率。前者看的是该不该调的时候有没有调、该调的时候有没有调对后者看的是调用之后最终能不能把用户的问题解决。评估测不出来的时候最常见的做法是准备一组标准测试集覆盖高频问题、边界问题和模糊表述问题。每次技能调整完用这组测试集跑一遍全量回归防止修复一个技能却引发了另一个技能的问题。这个过程有点枯燥但确实是技能库质量的生命线。我见过太多的 Agent 项目死在能跑就行的心态上上线时看着不错用户规模一大问题全暴露最后又回炉重做。另外一个容易被忽视的点是描述和实现之间的版本同步。技能描述改了一个词但函数实现没跟上或者反过来都会让模型表现异常。建议把技能描述和实现代码放在同一个版本管理目录下提交时统一更新从源头避免漂移。5. 技能库未来的扩展方向聊完踩坑经验最后分享一些我最近在探索的扩展方向这部分算不上成熟方案但值得留意。第一个方向是技能的自学习更新。传统技能依赖开发者预先定义但实际场景中用户总会有超出预期的诉求。我想尝试的做法是当模型发现现有技能都无法满足用户时把当时的会话上下文和期望结果记录到候选池中人工审核通过后自动生成新技能的初版描述和参数 Schema再经过测试集验证后加入技能库。这样一来技能库就能跟着用户需求一起生长。第二个方向是跨 Agent 的技能共享。多个 Agent 各自维护一套技能库很容易出现重复建设。我在设计一种基于共享技能仓库的方案把通用能力如时间查询、地址解析、格式转换做成公共技能包业务 Agent 通过依赖引用方式接入而不是各自复制一份代码。这样技能升级只需要在公共仓库改一次所有引用方都能生效。第三个方向是技能的可解释输出。目前技能返回结果基本是纯数据模型在吸收数据后输出回答过程像一个黑盒。如果技能能额外输出置信度、数据时效和依赖来源模型在组织回答时就可以做出更明智的判断比如时效性弱的数据它会提示用户仅供参考。这个方向做起来工作量不小但一旦跑通Agent 的可信度会明显提升。如果你也在做 agent-skills 相关的建设我的建议是从小处着手先盘清楚自己的能力清单写好每一个技能描述守住参数校验这一关再谈编排、评估这些上层能力。这一套流程看起来没那么炫酷但胜在稳妥能让你在项目跑起来之后少熬夜排查问题。技能库这个东西做得越扎实后面的路就越顺。