最近好几个团队都在折腾同一个问题给智能体写技能时到底怎么规划才能让模型稳定调用、代码好维护、扩展还不费劲。我在自己的项目里也反复改了好几版踩了不少坑正好借这个机会把 agent-skills 这套思路完整梳理一遍。这个东西不是某个开源库的代名词而是一种把“智能体能干什么”这件事显式建模的方法——说白了就是给大模型配一套规范化的技能库让它知道自己有什么工具、什么参数、什么约束然后在任务里按需调用。这套做法特别适合正在做智能体应用的人参考不管是写个人助理、客服机器人还是搭内部自动化流程都会遇到一个问题模型动不动就“幻觉”出一个不存在的接口或者明明有工具却不用。agent-skills 要解决的就是这类让人头疼的稳定性问题。它会涉及技能的定义方式、描述怎么写、参数 Schema 怎么设计、技能怎么测试怎么上版本内容会比单纯的 Function Calling 教程更深一层但要理解起来并不难只要有基础的 API 调用经验就能跟上。1. 先把“技能”这件事说清楚agent-skills 到底在解决什么问题1.1 我对智能体技能的理解“技能”这个词在不同框架里有不同叫法。OpenAI 那边叫 function callingAnthropic 那边现在力推 tools 和 skills 的分层LangChain 里干脆叫 tool。但本质上它们描述的是同一件事让模型在生成回复的过程中能够主动决定“我需要调用一个外部能力”来完成用户的需求。agent-skills 的创新点在于它把单个工具的“点”升级成了“面”。你不再只是给模型注册一个 get_weather 函数而是给一整类能力做了聚合和描述。比如“日历管理”是一项技能它底下可以有“查看日程”“创建日程”“修改日程”“取消日程”四个具体动作。模型在决定调用时不需要记住每一个细碎的函数名而是理解“用户提到日程安排我应该调用日历管理技能”然后再由技能层去路由到具体动作。这个分层的思路其实非常像我们人类的工作习惯。你不会在每次开会前临时想“我该怎么打开会议室预订系统、填哪几个字段、点哪个按钮”你只会想“我约个会议室”。技能库就是把这种心智模型教给模型让它也能“按职业习惯办事”。我在实际项目中体会最深的一点是技能设计得好模型的表现会像换了一个人。没设计之前它是个什么都会一点但什么都不精的“万金油”设计之后它像个熟手知道什么时候该查什么、不该查什么整个交互的稳定性和可预测性都上来了。1.2 没有技能库的智能体有多难用举个真实案例。我之前做过一个内部知识库问答机器人最初版本就是简单粗暴地把几个 API 包装成 function 塞给模型以为万事大吉。结果上线第一周就出了各种幺蛾子用户问“帮我查一下上季度的报销政策”模型死活不调用搜索函数而是凭训练数据里的“印象”瞎编了一段报销规则用户问“预约会议室A”模型调用了“创建日程”函数但传进去的时间参数格式不对日历系统直接报错模型偶尔会自作主张把“查询员工信息”这种受限能力当成“搜索引擎”的替代品触发了一堆权限告警。这些问题表面看起来是模型不够聪明但根子在于技能没有被妥善定义。描述写得不清楚参数约束不严格触发条件不明确权限边界没有划清模型就是在“盲人摸象”里做选择能稳定才怪。所以后来我花了大力气把整套路数重构成“技能库”模式。每个技能都有一套完整的“使用说明书”什么时候用、什么时候不用、参数怎么取、取值从哪里来、异常怎么处理。这个改造做完之后上面那些问题大部分都消失了模型的行为就像从“野生”变成了“驯化”。2. 技能库的架构设计从 0 开始规划 agent-skills2.1 技能的本质其实是一份契约我为什么强调“契约”这个词因为在智能体系统里技能是模型、代码、业务方三者之间的共同约定。写技能的团队要约定“模型的输入是什么、输出的预期是什么”调用方要约定“这个技能的边界在哪里什么任务不该走它”业务方要约定“能力归属哪个部门、权限怎么管控”。如果你只是把技能当成“一段可以被模型调用的代码”那设计出来的东西一定很随意——函数名随机、参数描述冗余、返回值没有统一规范。而一旦你把它当成一份契约就会自然而然地开始思考这份契约的“条款”够不够清晰有没有歧义能不能被机器和人共同理解。我目前采用的技能定义格式是标准 JSON Schema 扩展出来的核心字段包括技能 ID、技能名称、触发条件的自然语言描述、参数定义、返回结构、错误码约定。技能名称一定用英文 slug比如calendar_manager触发描述则完全用自然语言写在description里让模型自己判断是否命中。2.2 命名与参数设计的关键原则命名这件事看起来是基本功但在 agent-skills 体系里它的重要性被放大了很多倍。模型是靠着名字和描述来做语义匹配的名字取得不好描述写得不专业模型就会“不认识这个能力”。我总结了几条硬性原则技能名尽量用“名词动词”结构比如invoice_fetcher、meeting_room_checker让人一看就明白它是干什么的不要在名字里加版本号calendar_v2这种写法只会让模型困惑版本信息放到元数据里参数名统一用 lowerCamelCase 或者 snake_case不要混用一旦定下来就不要变否则历史会话里缓存的数据就全对不上了每个技能都有一个description字段这里要用 2 到 3 句话写清楚触发场景宁长勿短但要避免“万能化”描述——如果你把它描述成什么都能干模型就会什么任务都往这里塞。参数设计上有一条我踩过坑后特别强调的可选参数要给默认值并且明确写到 Schema 里。模型在生成参数时往往会偷懒你不给它默认值它可能直接省掉这个字段不传后端一接受到空值就崩。而如果你给了默认值哪怕它漏传系统也能安全降级。2.3 技能与工具的边界在哪里“技能”和“工具”这两个概念经常被混着用但在我看来它们的关系更像“文件夹”和“文件”。技能是一个聚合单元它可以包含多个工具也就是具体动作也可以包含子技能。工具是最小可执行单元直接对应后端的一个 API 或一段可复用函数。举个例子我的客服机器人里有一个order_service技能它内部就挂了order_detail_query、order_status_update、refund_request_create三个工具。模型只需要学会“用户想查订单、改状态、申请退款时调用订单服务技能”至于具体是哪个工具描述引擎会在技能内部根据用户意图再做一次意图路由。这种层级设计带来一个巨大好处当你的工具数量超过 20 个时单层的 function list 会因为 Token 过长导致指令跟随能力下降模型会开始“挑着看”描述偶尔漏掉关键工具。而做了技能层之后每次只把候选技能的描述传给模型模型做完粗粒度选择后再展开细粒度工具整个命中率和准确率都显著提升。我建议的拆分标准是如果你的工具描述加起来超过 3000 Token就要开始考虑把它们聚类成技能。如果某个技能内部又分出太多子工具说明这个技能本身设计过粗需要再拆。3. 实操全过程构建一个可复用的技能库3.1 第一步先盘点能力清单再定义技能边界很多人一上来就急着写代码我建议你先拿一张白纸把现有系统的所有能力列出来。比如你的后端已经有“用户查询”“订单管理”“物流跟踪”“支付退款”“优惠券核销”“商品推荐”等能力那么先不要急着把它们直接映射成技能而是问自己几个问题这些能力里哪些是模型可以直接调用的哪些必须走人工审批哪些能力之间的边界容易混淆比如“退款”和“取消订单”用户说“我不想要了”到底算哪边哪些能力需要组合才能完成任务比如“售后流程”其实涉及订单查询、物流查询、退款申请三个动作。理清这些问题后你才能确定技能的数量和粒度。我在一个电商项目中最初列了 32 个工具最后聚类成 9 个技能模型的表现不降反升。原因很简单候选越少选择越准。3.2 第二步写触发条件与描述这是最花时间的活技能描述写得不好是整个 agent 项目失败的最大原因之一。模型不是靠读代码理解技能的它只靠读你的 description。所以你要用“产品经理写需求文档”的心态来写描述场景、对象、排除条件、示例都要写清楚。我自己沉淀了一份模板技能名order_query 技能描述 - 当用户查询订单状态、物流进度、发货时间、收货地址时使用本技能。 - 当用户查询过往购买记录、订单金额、商品明细时使用本技能。 - 本技能不处理退款、退货、修改订单等操作类需求。请勿用本技能进行修改。 - 查询单号可能来自用户输入也可能从上下文会话中提取。缺失时主动询问。 - 示例用户说“我上周买的那个手机发货了吗”返回订单状态及物流跟踪号。这段描述我用了大约 150 个 Token看起来“浪费”但正是这些细节决定了模型能否正确路由。我还要强调一点把“不使用场景”写清楚比只写“使用场景”更重要。模型的误调用多半是因为描述里只说了做什么没说清不做什么。3.3 第三步定义参数 Schema交给模型自动填充参数 Schema 是让模型“帮你填表单”的格式说明。每个参数的字段包括类型、必填与否、含义、取值范围、默认值、示例值。这里有一个容易被忽略的点来源标注。我建议给每个参数加一个value_from字段标注“该参数可以从对话中提取”“该参数需要用户额外提供”“该参数由系统绑定注入”。比如查询订单订单号参数可以由模型从历史消息中提取但“用户ID”不能依赖模型猜测必须由你在调用时从会话上下文注入避免越权访问。关于枚举值能用枚举就用枚举。比如订单状态字段你写死成[pending, paid, shipped, completed, cancelled]模型就会严格从里面选。你如果只放一个 string 类型模型可能给你传一个“已支付啊”这种自然语言后端直接无法解析。3.4 第四步本地化测试与版本管理技能写完不是终点你得测。我的测试方法是建立一套“技能触发测试集”每个技能准备 30 到 50 条真实语气的问题覆盖正常场景、边界场景、否定场景和伪装场景。比如order_query技能的正常场景是“我的快递到哪了”边界场景是“上周的订单帮我查一下”需要多轮上下文否定场景是“帮我取消订单”该路由到售后技能伪装场景是“我不记得买过什么东西帮我查查”可能需要引导用户登录而不是直接查。把这些问题逐条跑一遍统计技能命中率和参数补全率。版本管理上技能定义建议放在独立的 Git 仓库里每次变更走 MR 评审合并后自动发布到配置中心。线上技能更新要谨慎尤其在智能体会话中技能描述改了如果缓存了旧 session容易造成前后行为不一致。我做了一个简单的做法技能配置带effective_version字段会话开始时锁版本跑完一个会话再用新版本。4. 常见问题与排查技巧实录4.1 模型为什么老是不调用我定义的技能这是最常被问到的问题。遇到“模型视而不见”的情况先别急着骂模型按下面顺序排查看技能是否真的进了 Prompt是不是拼接逻辑写错了技能列表被截断或者被过滤了。看描述是否对用户的表达敏感用户习惯说“我记不清单号了”你描述里只写了“用户输入订单号”那模型识别不到。看触发条件是否“太窄”或者“太宽”太窄就是漏掉太宽就是抢活需要在 3.2 节说的排除场景里下功夫。看模型版本是否支持工具调用有些轻量模型对 function calling 的支持非常弱你说破天它也调不起来这种情况只能换模型或者换解析策略。还有一个很容易被忽略的坑同时注册太多技能导致 Prompt 过长模型注意力被稀释。这也是我在 2.3 节强调分层设计的原因。如果你的技能列表已经超过 10 个就得认真考虑粗粒度路由了。4.2 技能之间的冲突与“抢单”问题技能多了之后一定会出现“这个技能也想接那个技能也想接”的抢单现象。比如用户说“帮我查一下物流顺便看看能不能改地址”order_query和order_update都觉得自己该上模型如果不够聪明会同时调用两个技能或者随机选一个。我的处理方案是定义技能优先级。在技能元数据里加一个priority字段当模型同时命中多个技能时优先调用优先级高的。比如“改地址”这种修改型操作优先级要高于“查询型”技能因为这涉及用户意愿的变更宁可多走一步确认也不能擅自执行。另外要给模型一个“组合调用”的空间。有些任务天然需要多技能协作比如“退货”需要先查订单再创建退款申请那你不能光靠优先级还要在技能描述中写明“你先调用 order_query 获得订单号再调用 compensation_create 完成退款”。4.3 参数错误频发模型传错、传漏、传空怎么防参数问题是仅次于触发问题的高频故障。模型传入空字符串、错误格式、甚至是“这个参数我不太清楚所以没传”都常见。对策有三个层面第一层Schema 校验严格化。所有枚举、格式、必填标记都写清楚后端再做一次强校验不合格直接返回错误不要“宽容处理”。第二层在模型侧做“参数补全追问”。设计一个argument_fill_required标记对于无法从上下文中提取的必填参数让技能层返回“缺少参数请让用户补充”而不是硬着头皮调用后端。第三层对敏感参数做系统注入。比如用户 ID、商户 ID、租户 ID 这类上下文参数不要留给模型生成由调度层统一注入这样既准确又安全。5. 技能库的工程化实践从“能用”到“好用”5.1 技能的动态加载与按需下发技能定义如果每次都全部塞进 Prompt既浪费 Token 又降低准确率。我的做法是搭一个轻量级的“技能路由服务”它接收用户当前输入和上下文返回一个候选技能列表。这本质上是一个小型的分类模型或者规则引擎可以在主模型之外独立运行。路由服务有以下几种实现方式基于关键词的规则引擎适合技能边界清晰、触发词明确的场景成本最低。基于嵌入式向量的语义检索把每个技能的描述做成向量用户输入也做向量算相似度取 Top K。基于小模型的分类器微调一个文本分类模型技能数量在 50 个以内时准确率很高。我目前在项目里是“Embedding 召回 规则兜底”的组合先用向量召回 Top 3再用规则对召回结果做修正。比如用户说“查一下”如果没带明确宾语规则层会默认拉起最新会话里涉及的技能避免模型什么候选都选不出来。5.2 技能的观测与日志体系技能上线跑起来之后你必须能回答这几个问题哪个技能被频繁调用哪个技能几乎没人用哪个技能调用后错误率特别高哪个技能和描述不一致导致「答非所问」我的建议是为每次技能调用记录一份详细日志至少包含调用时间、用户输入原文、命中的技能 ID、实际执行的动作、参数快照、返回摘要、模型选择技能的置信度如果系统支持的话、用户对结果的反馈点赞/点踩。这些日志不仅是排查问题的依据更是后续优化技能名称和描述的基础素材。尤其要重视“模型选了技能但执行结果用户不满意”的案例。这说明技能描述与实际能力之间存在偏差可能你写的描述夸大了技能的能力需要把描述改得更贴近真实处理逻辑。5.3 技能的安全与权限控制技能能够访问各种后端能力也必须成为权限管控的重点对象。我在技能配置里增加了permission_level和allowed_scopes两个字段。permission_level分为三级L1 是只读能力比如查询订单、查物流L2 是操作型能力比如改地址、创建退款单要求用户二次确认L3 是高危能力比如删除账号、转账、批量导出数据除了用户确认外还需要额外鉴权。allowed_scopes用于限制技能可以操作的数据范围。比如同一个get_user_info技能普通用户只能查自己客服坐席能查特定范围管理员才能全量查。这个限制必须由后端强制执行不能只靠模型自觉模型只能决定“用什么技能”不能决定“技能能干嘛”。在权限这块我还建议做“技能调用审计”。一旦某个用户在某段会话里调用了多个 L2/L3 技能系统应该自动标记并进入人工审核队列防止有人通过多轮对话诱导模型执行危险操作。6. 常见问题与排查技巧实录6.1 模型调用技能的正确动作但参数用的是旧格式这个问题常常出现在“技能升级”之后。线上会话是长连接用户在 A 版本里发了消息等你在 B 版本里改了参数模型已经生成了 A 版本的参数格式后端解析自然就会失败。我的解决办法是在后端兼容层同时接受新旧参数格式并做转换。同时每次技能定义变更前在发布说明里写明“引退时间窗口”。在窗口期内新旧版本并存但新调用请求一律使用新版本。窗口期过后再用定时任务把旧会话缓存清理掉避免历史脏数据继续影响系统。6.2 技能命中正确但返回结果结构化程度差模型调用技能后返回结果是一段自然语言而后端接口需要的是结构化参数这是另一个高频问题。比如用户说“发我一个华为手机订单的物流信息”模型识别到技能order_query但传给后端的参数可能是{keyword: 华为手机订单}而不是干净的{order_id: 20240916001}。我的处理套路是在技能内部塞一个“参数抽取步骤”不是让主模型直接生成参数而是先让它把用户原句里的关键信息抽取成结构化候选再进行 Schema 校验。如果校验不过就发起一轮澄清。简单说把“一步到位”拆成“先提取、再校验、最后执行”三步失败率会大幅下降。6.3 一个技能里面挂了很多子操作模型经常选错子动作上面提到订单技能包含了“查”“改”“退”三个操作如果模型在技能内部定位不准会拿“查询”的动作去执行“退款”的意图。这时你不能只靠技能层描述要在工具描述里把边界写得非常细并且添加“意图示例”。我给每个子工具都配了两到三个典型说法和两个“易混淆但不该走这里”的反例。比如动作名refund_request_create适用说法我要退货、申请退款、不想要了、这笔钱什么时候退反例只是查退款进度、看看退款到没到账这种情况应该路由到 refund_status_query反例写多了之后模型的选择准确率会有肉眼可见的提升。6.4 技能响应太慢影响交互体验智能体系统增加技能调用层之后端到端延迟很容易翻倍。如果是内部系统隔个几秒还能接受如果是对 C 端用户每多一秒都是在流失用户。你在链路图上会看到延迟通常集中在四个环节技能路由层、模型生成参数、后端业务接口、返回结果再进模型整理话术。我优化下来最有效的两招一是“参数预生成”。在路由层选中技能的同时就根据用户输入预生成一份参数草稿等主模型确认后直接提交减少一次往返。二是“结果直通”。对于查询类的技能后端接口如果已经返回了格式化结果就不要再丢给模型做一遍总结直接按模板拼接自然语言能省掉一次模型调用省下来的时间非常可观。6.5 如何知道当前技能库的覆盖面是否完整最后聊一个偏“体检”方向的问题你如何判断技能库还有没有缺口用户提出的需求里有多少是技能库完全没覆盖的有多少是覆盖了但匹配错了我每周末会做一次离线日志分析把所有未命中任何技能的会话问题聚个类。如果某个分类反复出现说明你应该新增一个技能如果某个技能长期零调用说明它名存实亡可以考虑下线或者重构描述。用数据驱动来迭代技能库比一开始硬憋一个“大而全”的方案要靠谱得多。技能库不是一次建完就完的它应该像产品一样持续维护、根据真实使用反馈不断演进。这个思路放到任何行业都适用不管你做的是智能客服、编程助手还是办公自动化先上线一个最小可用的技能集然后把用户反馈和日志跑起来再迭代加厚。做到底agent-skills 的工程核心不是写代码而是“围绕模型的决策习惯持续打磨能力边界”。我自己是在几轮重构后才真正体会到这件事的分量。也希望你少走一半弯路一次就把技能设计到点子上。
最近好几个团队都在折腾同一个问题给智能体写技能时到底怎么规划才能让模型稳定调用、代码好维护、扩展还不费劲。我在自己的项目里也反复改了好几版踩了不少坑正好借这个机会把 agent-skills 这套思路完整梳理一遍。这个东西不是某个开源库的代名词而是一种把“智能体能干什么”这件事显式建模的方法——说白了就是给大模型配一套规范化的技能库让它知道自己有什么工具、什么参数、什么约束然后在任务里按需调用。这套做法特别适合正在做智能体应用的人参考不管是写个人助理、客服机器人还是搭内部自动化流程都会遇到一个问题模型动不动就“幻觉”出一个不存在的接口或者明明有工具却不用。agent-skills 要解决的就是这类让人头疼的稳定性问题。它会涉及技能的定义方式、描述怎么写、参数 Schema 怎么设计、技能怎么测试怎么上版本内容会比单纯的 Function Calling 教程更深一层但要理解起来并不难只要有基础的 API 调用经验就能跟上。1. 先把“技能”这件事说清楚agent-skills 到底在解决什么问题1.1 我对智能体技能的理解“技能”这个词在不同框架里有不同叫法。OpenAI 那边叫 function callingAnthropic 那边现在力推 tools 和 skills 的分层LangChain 里干脆叫 tool。但本质上它们描述的是同一件事让模型在生成回复的过程中能够主动决定“我需要调用一个外部能力”来完成用户的需求。agent-skills 的创新点在于它把单个工具的“点”升级成了“面”。你不再只是给模型注册一个 get_weather 函数而是给一整类能力做了聚合和描述。比如“日历管理”是一项技能它底下可以有“查看日程”“创建日程”“修改日程”“取消日程”四个具体动作。模型在决定调用时不需要记住每一个细碎的函数名而是理解“用户提到日程安排我应该调用日历管理技能”然后再由技能层去路由到具体动作。这个分层的思路其实非常像我们人类的工作习惯。你不会在每次开会前临时想“我该怎么打开会议室预订系统、填哪几个字段、点哪个按钮”你只会想“我约个会议室”。技能库就是把这种心智模型教给模型让它也能“按职业习惯办事”。我在实际项目中体会最深的一点是技能设计得好模型的表现会像换了一个人。没设计之前它是个什么都会一点但什么都不精的“万金油”设计之后它像个熟手知道什么时候该查什么、不该查什么整个交互的稳定性和可预测性都上来了。1.2 没有技能库的智能体有多难用举个真实案例。我之前做过一个内部知识库问答机器人最初版本就是简单粗暴地把几个 API 包装成 function 塞给模型以为万事大吉。结果上线第一周就出了各种幺蛾子用户问“帮我查一下上季度的报销政策”模型死活不调用搜索函数而是凭训练数据里的“印象”瞎编了一段报销规则用户问“预约会议室A”模型调用了“创建日程”函数但传进去的时间参数格式不对日历系统直接报错模型偶尔会自作主张把“查询员工信息”这种受限能力当成“搜索引擎”的替代品触发了一堆权限告警。这些问题表面看起来是模型不够聪明但根子在于技能没有被妥善定义。描述写得不清楚参数约束不严格触发条件不明确权限边界没有划清模型就是在“盲人摸象”里做选择能稳定才怪。所以后来我花了大力气把整套路数重构成“技能库”模式。每个技能都有一套完整的“使用说明书”什么时候用、什么时候不用、参数怎么取、取值从哪里来、异常怎么处理。这个改造做完之后上面那些问题大部分都消失了模型的行为就像从“野生”变成了“驯化”。2. 技能库的架构设计从 0 开始规划 agent-skills2.1 技能的本质其实是一份契约我为什么强调“契约”这个词因为在智能体系统里技能是模型、代码、业务方三者之间的共同约定。写技能的团队要约定“模型的输入是什么、输出的预期是什么”调用方要约定“这个技能的边界在哪里什么任务不该走它”业务方要约定“能力归属哪个部门、权限怎么管控”。如果你只是把技能当成“一段可以被模型调用的代码”那设计出来的东西一定很随意——函数名随机、参数描述冗余、返回值没有统一规范。而一旦你把它当成一份契约就会自然而然地开始思考这份契约的“条款”够不够清晰有没有歧义能不能被机器和人共同理解。我目前采用的技能定义格式是标准 JSON Schema 扩展出来的核心字段包括技能 ID、技能名称、触发条件的自然语言描述、参数定义、返回结构、错误码约定。技能名称一定用英文 slug比如calendar_manager触发描述则完全用自然语言写在description里让模型自己判断是否命中。2.2 命名与参数设计的关键原则命名这件事看起来是基本功但在 agent-skills 体系里它的重要性被放大了很多倍。模型是靠着名字和描述来做语义匹配的名字取得不好描述写得不专业模型就会“不认识这个能力”。我总结了几条硬性原则技能名尽量用“名词动词”结构比如invoice_fetcher、meeting_room_checker让人一看就明白它是干什么的不要在名字里加版本号calendar_v2这种写法只会让模型困惑版本信息放到元数据里参数名统一用 lowerCamelCase 或者 snake_case不要混用一旦定下来就不要变否则历史会话里缓存的数据就全对不上了每个技能都有一个description字段这里要用 2 到 3 句话写清楚触发场景宁长勿短但要避免“万能化”描述——如果你把它描述成什么都能干模型就会什么任务都往这里塞。参数设计上有一条我踩过坑后特别强调的可选参数要给默认值并且明确写到 Schema 里。模型在生成参数时往往会偷懒你不给它默认值它可能直接省掉这个字段不传后端一接受到空值就崩。而如果你给了默认值哪怕它漏传系统也能安全降级。2.3 技能与工具的边界在哪里“技能”和“工具”这两个概念经常被混着用但在我看来它们的关系更像“文件夹”和“文件”。技能是一个聚合单元它可以包含多个工具也就是具体动作也可以包含子技能。工具是最小可执行单元直接对应后端的一个 API 或一段可复用函数。举个例子我的客服机器人里有一个order_service技能它内部就挂了order_detail_query、order_status_update、refund_request_create三个工具。模型只需要学会“用户想查订单、改状态、申请退款时调用订单服务技能”至于具体是哪个工具描述引擎会在技能内部根据用户意图再做一次意图路由。这种层级设计带来一个巨大好处当你的工具数量超过 20 个时单层的 function list 会因为 Token 过长导致指令跟随能力下降模型会开始“挑着看”描述偶尔漏掉关键工具。而做了技能层之后每次只把候选技能的描述传给模型模型做完粗粒度选择后再展开细粒度工具整个命中率和准确率都显著提升。我建议的拆分标准是如果你的工具描述加起来超过 3000 Token就要开始考虑把它们聚类成技能。如果某个技能内部又分出太多子工具说明这个技能本身设计过粗需要再拆。3. 实操全过程构建一个可复用的技能库3.1 第一步先盘点能力清单再定义技能边界很多人一上来就急着写代码我建议你先拿一张白纸把现有系统的所有能力列出来。比如你的后端已经有“用户查询”“订单管理”“物流跟踪”“支付退款”“优惠券核销”“商品推荐”等能力那么先不要急着把它们直接映射成技能而是问自己几个问题这些能力里哪些是模型可以直接调用的哪些必须走人工审批哪些能力之间的边界容易混淆比如“退款”和“取消订单”用户说“我不想要了”到底算哪边哪些能力需要组合才能完成任务比如“售后流程”其实涉及订单查询、物流查询、退款申请三个动作。理清这些问题后你才能确定技能的数量和粒度。我在一个电商项目中最初列了 32 个工具最后聚类成 9 个技能模型的表现不降反升。原因很简单候选越少选择越准。3.2 第二步写触发条件与描述这是最花时间的活技能描述写得不好是整个 agent 项目失败的最大原因之一。模型不是靠读代码理解技能的它只靠读你的 description。所以你要用“产品经理写需求文档”的心态来写描述场景、对象、排除条件、示例都要写清楚。我自己沉淀了一份模板技能名order_query 技能描述 - 当用户查询订单状态、物流进度、发货时间、收货地址时使用本技能。 - 当用户查询过往购买记录、订单金额、商品明细时使用本技能。 - 本技能不处理退款、退货、修改订单等操作类需求。请勿用本技能进行修改。 - 查询单号可能来自用户输入也可能从上下文会话中提取。缺失时主动询问。 - 示例用户说“我上周买的那个手机发货了吗”返回订单状态及物流跟踪号。这段描述我用了大约 150 个 Token看起来“浪费”但正是这些细节决定了模型能否正确路由。我还要强调一点把“不使用场景”写清楚比只写“使用场景”更重要。模型的误调用多半是因为描述里只说了做什么没说清不做什么。3.3 第三步定义参数 Schema交给模型自动填充参数 Schema 是让模型“帮你填表单”的格式说明。每个参数的字段包括类型、必填与否、含义、取值范围、默认值、示例值。这里有一个容易被忽略的点来源标注。我建议给每个参数加一个value_from字段标注“该参数可以从对话中提取”“该参数需要用户额外提供”“该参数由系统绑定注入”。比如查询订单订单号参数可以由模型从历史消息中提取但“用户ID”不能依赖模型猜测必须由你在调用时从会话上下文注入避免越权访问。关于枚举值能用枚举就用枚举。比如订单状态字段你写死成[pending, paid, shipped, completed, cancelled]模型就会严格从里面选。你如果只放一个 string 类型模型可能给你传一个“已支付啊”这种自然语言后端直接无法解析。3.4 第四步本地化测试与版本管理技能写完不是终点你得测。我的测试方法是建立一套“技能触发测试集”每个技能准备 30 到 50 条真实语气的问题覆盖正常场景、边界场景、否定场景和伪装场景。比如order_query技能的正常场景是“我的快递到哪了”边界场景是“上周的订单帮我查一下”需要多轮上下文否定场景是“帮我取消订单”该路由到售后技能伪装场景是“我不记得买过什么东西帮我查查”可能需要引导用户登录而不是直接查。把这些问题逐条跑一遍统计技能命中率和参数补全率。版本管理上技能定义建议放在独立的 Git 仓库里每次变更走 MR 评审合并后自动发布到配置中心。线上技能更新要谨慎尤其在智能体会话中技能描述改了如果缓存了旧 session容易造成前后行为不一致。我做了一个简单的做法技能配置带effective_version字段会话开始时锁版本跑完一个会话再用新版本。4. 常见问题与排查技巧实录4.1 模型为什么老是不调用我定义的技能这是最常被问到的问题。遇到“模型视而不见”的情况先别急着骂模型按下面顺序排查看技能是否真的进了 Prompt是不是拼接逻辑写错了技能列表被截断或者被过滤了。看描述是否对用户的表达敏感用户习惯说“我记不清单号了”你描述里只写了“用户输入订单号”那模型识别不到。看触发条件是否“太窄”或者“太宽”太窄就是漏掉太宽就是抢活需要在 3.2 节说的排除场景里下功夫。看模型版本是否支持工具调用有些轻量模型对 function calling 的支持非常弱你说破天它也调不起来这种情况只能换模型或者换解析策略。还有一个很容易被忽略的坑同时注册太多技能导致 Prompt 过长模型注意力被稀释。这也是我在 2.3 节强调分层设计的原因。如果你的技能列表已经超过 10 个就得认真考虑粗粒度路由了。4.2 技能之间的冲突与“抢单”问题技能多了之后一定会出现“这个技能也想接那个技能也想接”的抢单现象。比如用户说“帮我查一下物流顺便看看能不能改地址”order_query和order_update都觉得自己该上模型如果不够聪明会同时调用两个技能或者随机选一个。我的处理方案是定义技能优先级。在技能元数据里加一个priority字段当模型同时命中多个技能时优先调用优先级高的。比如“改地址”这种修改型操作优先级要高于“查询型”技能因为这涉及用户意愿的变更宁可多走一步确认也不能擅自执行。另外要给模型一个“组合调用”的空间。有些任务天然需要多技能协作比如“退货”需要先查订单再创建退款申请那你不能光靠优先级还要在技能描述中写明“你先调用 order_query 获得订单号再调用 compensation_create 完成退款”。4.3 参数错误频发模型传错、传漏、传空怎么防参数问题是仅次于触发问题的高频故障。模型传入空字符串、错误格式、甚至是“这个参数我不太清楚所以没传”都常见。对策有三个层面第一层Schema 校验严格化。所有枚举、格式、必填标记都写清楚后端再做一次强校验不合格直接返回错误不要“宽容处理”。第二层在模型侧做“参数补全追问”。设计一个argument_fill_required标记对于无法从上下文中提取的必填参数让技能层返回“缺少参数请让用户补充”而不是硬着头皮调用后端。第三层对敏感参数做系统注入。比如用户 ID、商户 ID、租户 ID 这类上下文参数不要留给模型生成由调度层统一注入这样既准确又安全。5. 技能库的工程化实践从“能用”到“好用”5.1 技能的动态加载与按需下发技能定义如果每次都全部塞进 Prompt既浪费 Token 又降低准确率。我的做法是搭一个轻量级的“技能路由服务”它接收用户当前输入和上下文返回一个候选技能列表。这本质上是一个小型的分类模型或者规则引擎可以在主模型之外独立运行。路由服务有以下几种实现方式基于关键词的规则引擎适合技能边界清晰、触发词明确的场景成本最低。基于嵌入式向量的语义检索把每个技能的描述做成向量用户输入也做向量算相似度取 Top K。基于小模型的分类器微调一个文本分类模型技能数量在 50 个以内时准确率很高。我目前在项目里是“Embedding 召回 规则兜底”的组合先用向量召回 Top 3再用规则对召回结果做修正。比如用户说“查一下”如果没带明确宾语规则层会默认拉起最新会话里涉及的技能避免模型什么候选都选不出来。5.2 技能的观测与日志体系技能上线跑起来之后你必须能回答这几个问题哪个技能被频繁调用哪个技能几乎没人用哪个技能调用后错误率特别高哪个技能和描述不一致导致「答非所问」我的建议是为每次技能调用记录一份详细日志至少包含调用时间、用户输入原文、命中的技能 ID、实际执行的动作、参数快照、返回摘要、模型选择技能的置信度如果系统支持的话、用户对结果的反馈点赞/点踩。这些日志不仅是排查问题的依据更是后续优化技能名称和描述的基础素材。尤其要重视“模型选了技能但执行结果用户不满意”的案例。这说明技能描述与实际能力之间存在偏差可能你写的描述夸大了技能的能力需要把描述改得更贴近真实处理逻辑。5.3 技能的安全与权限控制技能能够访问各种后端能力也必须成为权限管控的重点对象。我在技能配置里增加了permission_level和allowed_scopes两个字段。permission_level分为三级L1 是只读能力比如查询订单、查物流L2 是操作型能力比如改地址、创建退款单要求用户二次确认L3 是高危能力比如删除账号、转账、批量导出数据除了用户确认外还需要额外鉴权。allowed_scopes用于限制技能可以操作的数据范围。比如同一个get_user_info技能普通用户只能查自己客服坐席能查特定范围管理员才能全量查。这个限制必须由后端强制执行不能只靠模型自觉模型只能决定“用什么技能”不能决定“技能能干嘛”。在权限这块我还建议做“技能调用审计”。一旦某个用户在某段会话里调用了多个 L2/L3 技能系统应该自动标记并进入人工审核队列防止有人通过多轮对话诱导模型执行危险操作。6. 常见问题与排查技巧实录6.1 模型调用技能的正确动作但参数用的是旧格式这个问题常常出现在“技能升级”之后。线上会话是长连接用户在 A 版本里发了消息等你在 B 版本里改了参数模型已经生成了 A 版本的参数格式后端解析自然就会失败。我的解决办法是在后端兼容层同时接受新旧参数格式并做转换。同时每次技能定义变更前在发布说明里写明“引退时间窗口”。在窗口期内新旧版本并存但新调用请求一律使用新版本。窗口期过后再用定时任务把旧会话缓存清理掉避免历史脏数据继续影响系统。6.2 技能命中正确但返回结果结构化程度差模型调用技能后返回结果是一段自然语言而后端接口需要的是结构化参数这是另一个高频问题。比如用户说“发我一个华为手机订单的物流信息”模型识别到技能order_query但传给后端的参数可能是{keyword: 华为手机订单}而不是干净的{order_id: 20240916001}。我的处理套路是在技能内部塞一个“参数抽取步骤”不是让主模型直接生成参数而是先让它把用户原句里的关键信息抽取成结构化候选再进行 Schema 校验。如果校验不过就发起一轮澄清。简单说把“一步到位”拆成“先提取、再校验、最后执行”三步失败率会大幅下降。6.3 一个技能里面挂了很多子操作模型经常选错子动作上面提到订单技能包含了“查”“改”“退”三个操作如果模型在技能内部定位不准会拿“查询”的动作去执行“退款”的意图。这时你不能只靠技能层描述要在工具描述里把边界写得非常细并且添加“意图示例”。我给每个子工具都配了两到三个典型说法和两个“易混淆但不该走这里”的反例。比如动作名refund_request_create适用说法我要退货、申请退款、不想要了、这笔钱什么时候退反例只是查退款进度、看看退款到没到账这种情况应该路由到 refund_status_query反例写多了之后模型的选择准确率会有肉眼可见的提升。6.4 技能响应太慢影响交互体验智能体系统增加技能调用层之后端到端延迟很容易翻倍。如果是内部系统隔个几秒还能接受如果是对 C 端用户每多一秒都是在流失用户。你在链路图上会看到延迟通常集中在四个环节技能路由层、模型生成参数、后端业务接口、返回结果再进模型整理话术。我优化下来最有效的两招一是“参数预生成”。在路由层选中技能的同时就根据用户输入预生成一份参数草稿等主模型确认后直接提交减少一次往返。二是“结果直通”。对于查询类的技能后端接口如果已经返回了格式化结果就不要再丢给模型做一遍总结直接按模板拼接自然语言能省掉一次模型调用省下来的时间非常可观。6.5 如何知道当前技能库的覆盖面是否完整最后聊一个偏“体检”方向的问题你如何判断技能库还有没有缺口用户提出的需求里有多少是技能库完全没覆盖的有多少是覆盖了但匹配错了我每周末会做一次离线日志分析把所有未命中任何技能的会话问题聚个类。如果某个分类反复出现说明你应该新增一个技能如果某个技能长期零调用说明它名存实亡可以考虑下线或者重构描述。用数据驱动来迭代技能库比一开始硬憋一个“大而全”的方案要靠谱得多。技能库不是一次建完就完的它应该像产品一样持续维护、根据真实使用反馈不断演进。这个思路放到任何行业都适用不管你做的是智能客服、编程助手还是办公自动化先上线一个最小可用的技能集然后把用户反馈和日志跑起来再迭代加厚。做到底agent-skills 的工程核心不是写代码而是“围绕模型的决策习惯持续打磨能力边界”。我自己是在几轮重构后才真正体会到这件事的分量。也希望你少走一半弯路一次就把技能设计到点子上。
