Agent技能封装：把散装API变成大模型真正会用的工具

1. 为什么Agent总在"差一步执行"的地方翻车

做AI Agent也有一段时间了，我发现一个特别普遍的现象：大家把精力都花在模型选型、Prompt调优、上下文管理这些"看得见"的地方，结果一到真实任务执行，Agent就露出马脚——明明知道该干什么，但动手那一下总是歪。

我在某项目里做过一个客服Agent的Demo，最初直接给模型挂了十几个平铺的API函数。写的时候信心满满，觉得这不就是把工具喂给模型嘛，它还能不会用？结果实测下来，任务完成率差得离谱。比如用户问"我上个订单为什么还没发货"，模型居然先去调了"查询用户信息"而不是"查询订单状态"；再比如用户说"帮我退款"，模型调用了退款接口，但参数传的是订单号而不是退款单号。那段时间我每天都在Debug"为什么模型不会用工具"，后来才意识到：问题根本不是模型笨，是我给它的"技能"封装得太粗糙了。

这篇想聊的就是"agent-skills"这件事——如何把Agent的外挂能力从一坨散装的函数，整理成一套Agent真正能理解、能调用、能组合的技能体系。这可能是Agent开发里性价比最高的一项投入，适合所有在搞AI应用、智能助手、自动化工作流的工程师参考。如果你现在的Agent也经常"知道该做什么但做不对"，那这篇文章大概率能帮你找到症结。

我想先从一次演示事故说起，讲清楚我为什么决定把"技能"当成一个独立工程来做。

1.1 一次让我重新审视Agent能力的演示事故

那次事故画面我至今记得。会议室里，系统负责人让我现场演示，用户跟Agent说："帮我查一下手机套餐里哪个流量包最合适，然后直接给我办一个。"我当时心里一咯噔——这个需求要连续调两次工具：先查套餐列表，再根据返回结果推荐并下单，属于典型的"多步技能编排"。而我们的Agent当时所有能力都堆在一个超长的系统提示词里，附带一堆JSON Schema。

结果不出所料，Agent先成功调用了套餐查询接口，拿到结果之后，在"办一个"这一步突然开始自由发挥，它没有调用任何技能，而是直接根据查询结果编了一段"已为您办理成功"的话术。现场气氛直接凝固。我事后复盘，发现根因非常清晰：模型根本不知道"下单"这个动作对应哪个工具、参数从哪里来、调用之后会发生什么。它只知道QA表格里的模糊说明，于是选择了"编答案"这个最低成本的路径。

这件事让我第一次认真思考：Agent的执行能力，实际上等于它对外部能力的"理解能力"，而不仅仅是模型推理能力。工具定义写得再标准，如果模型在关键时刻无法把当前对话状态和某个技能匹配起来，那一切都白搭。也就是从那天起，我开始把"skills"当作产品核心组件来设计，而不是一个附属于Prompt的配置项。

1.2 执行力的真正瓶颈在"技能封装"

后来我复盘了大量用户会话，发现Agent执行翻车可以归纳成三类问题：

第一类是选错技能，明明该查订单状态，它去查了账户信息；第二类是用错技能，知道要调用哪个，但参数填得不对或者少填必填项；第三类是瞎编结果，调没调用工具都不确定，反正给用户一个看起来合理的答复。

深入分析之后会发现，这三类问题很少是因为模型能力不足，绝大多数都出在"技能封装"上——我们把能力的元信息描述得不清楚，把使用场景写得模棱两可，把参数的约束和前置条件藏得太深。模型就像个新入职的员工，你塞给他一堆工具，但没告诉他什么场景用什么、用了要注意什么、出错怎么办，那他当然会犯错。

所以"agent-skills"这个命题的核心，不是要不要给Agent挂技能，而是怎么把技能描述、参数契约、错误处理、使用边界这些工程细节做到位。这也是我这篇文章真正想展开的东西。

2. 技能不是函数，也不是插件：先厘清这层设计边界

在我接触的很多团队里，有个概念混淆非常致命："技能"到底和"函数"、"插件"有什么区别？如果这个问题想不清楚，设计出来的东西就会四不像。我用一张表格先做个区分，然后逐个解释。

2.1 函数解决的是"参数化调用"，不是"模型理解"

传统的函数封装，解决的是代码层面的复用问题。你把一段逻辑抽成函数，定义好参数类型和返回值，调用方只要符合接口契约就能用。但在Agent场景里，调用方不是程序员，而是大模型。模型不会去读你的TypeScript类型定义，不会去看你的API文档，它只能通过"自然语言描述"来猜测这个函数是干嘛的、什么时候该用它。

所以很多团队直接把函数列表塞给模型，本质上是在做一个无效沟通：你给模型看的是程序员的接口文档，但模型需要的是"业务说明书"。

2.2 插件解决的是"能力扩展"，不是"决策匹配"

插件这个概念的出发点是应用层的扩展。装一个插件，应用就多一组功能。插件的重点是"提供能力"，至于用户什么时候触发这个能力、该不该触发，通常由应用自身的业务逻辑决定。但在Agent里，这个"决策权"被交给了模型——是模型来决定现在要不要调用某个技能。

这就意味着，技能设计必须包含"决策辅助信息"：什么情况下应该调用我、什么情况下不应该调用我、我改了系统状态之后有什么后果。插件思维里通常不包含这些，所以直接把插件当技能用，Agent经常会做出错误决策。

2.3 技能的本质：给模型的一份"行动说明书"

我后面在项目中把技能重新定义为：一段可以被大模型理解并触发的、具有明确业务边界和副作用描述的执行单元。它由两部分组成：一部分是给模型读的"说明书"（技能名、描述、使用场景、前置条件、示例、注意事项），另一部分是给系统执行的"引擎"（实际处理逻辑和参数处理）。

这有点像一个带标签的电器插座：说明书告诉模型"这个插座支持220V，只能接电饭煲，接微波炉会跳闸"，系统则在模型做出选择后真正完成供电。没有说明书，模型只能猜；有了说明书，模型才能做正确判断。我说这个边界想清楚之后，后面的所有设计都顺了。

3. 技能描述规范：名字、摘要、说明、示例如何组织

既然技能的"说明书"决定了模型能不能正确使用，那这个说明书怎么写就值得下功夫。我调研了很多公开的最佳实践，也踩过一些坑，最后沉淀出一套我自己的技能描述模板。不敢说它是最优解，但在我实测的多个场景里，它的误用率比原来的写法低了将近一半。

技能描述我一般按五段式来组织：技能名、一句话摘要、详细说明、前置条件与副作用、调用示例。

3.1 技能名的严谨性：动宾结构 + 明确对象

技能名是模型看到的第一眼信息，也是匹配的核心关键。我发现很多团队喜欢起"工具A"、"功能B"这种名字，或者用"processData"这种看不太懂的缩写，模型怎么可能选对？

我的命名规则是：动宾结构，动词要具体，宾语要明确。比如"查询订单物流状态"就比"获取订单信息"更准确——前者直接告诉模型动作是"查询"、对象是"物流状态"，而"获取订单信息"太泛，模型可能拿它去处理用户的所有订单相关问题。

命名时还要注意语义覆盖：一个技能如果要支持多类相似请求，名字可以稍微抽象一点，比如"处理退货退款"，但如果不同业务的差异太大，宁可拆成两个技能，也别让一个技能去承担所有模糊请求，否则描述会变得非常臃肿。

3.2 摘要信息的"正反两面"：什么时候该用，也写清楚什么时候不该用

很多人写技能的描述，只写"这个技能能做什么"，但不写"它不能做什么"。在Agent场景里，"不能做什么"往往比"能做什么"更重要。

举个例子，一个"查询订单状态"的技能，摘要可以写成："根据订单号查询当前物流状态和预计送达时间，适用于用户询问包裹到哪了、什么时候到、是否已发货等问题。注意：本技能只负责查询，不处理改地址、催件、退款等操作，若用户提出这些需求请转其他技能。"

这个"注意"部分的作用，就是给模型的决策提供反例边界。我在实测中发现，加上反例之后，技能误选率下降了大概三成，原因很简单——模型在语义匹配时，正例和反例同时出现，它的判断会更稳定。

3.3 详细说明里的"小字条款"：参数格式、上下文依赖、组合方法

详细说明是最容易被忽视的地方，很多团队的技能说明只有一句话。但我建议至少包含三块内容：参数的具体格式要求；该技能是否依赖对话上下文中的某个前置信息；以及如果多个技能配合使用，它通常在前还是后。

比如一个"创建工单"技能，详细说明里可以写："需要用户描述问题，可结合之前的对话内容自动提取；如果用户没有说清楚问题类型，请先调用'问题分类'技能再创建工单；创建成功后返回工单号，可直接作为后续'查询工单进度'技能的输入。"

这段说明里的"注入顺序提示"和"输出复用提示"实际是在帮模型建立技能间的调用链，模型读到这些文字后，编排多个技能时会越来越熟练，不再是把每个技能当孤岛来用。

3.4 调用示例与语义锚点

最后是调用示例。示例千万别随便给，要给那些"最容易混淆"的边界情况。我通常会为每个技能配三个示例：一个经典用法、一个带隐含参数的用法、一个和别的技能容易混淆的用法。

比如"按标签筛选邮件"这个技能，经典示例是"找出所有标记为'重要'的邮件"；带隐含参数的示例是"把上周老板发的邮件找出来"——这里的隐含条件是"发件人=老板"、"时间=上周"，模型需要从上下文推导；容易混淆的示例是"找出所有未读邮件"，这个应该走"查询邮件列表"而不是"按标签筛选"。

每个示例都是一颗"语义锚点"，模型在看到这些真实说法之后，遇到用户千奇百怪的表达，也能稳稳地映射到对应的技能上。

4. 从零沉淀一个技能：订单查询的完整生命周期

前面讲的都是理论，这一章我拿一个真实沉淀过的技能来走一遍完整流程，大家可以直接照着这个流程套用到自己的业务里。我选的例子是客服场景里的"查询订单物流状态"，因为这个技能足够常见，又兼具了参数解析、外部API对接、结果归一化、错误自救这些典型要素。

一个技能从无到有，我分成了六个阶段：需求分析、元数据编写、逻辑实现、描述测试、灰度发布、持续维护。下面逐个说。

4.1 需求分析：搞清楚这个技能是不是真的独立

开始之前，我先问自己几个问题：这个动作是否高频？它是否有独立的输入输出？它是否需要和其他能力组合才能完成？如果三个答案都是"是"，那它大概率值得做成一个独立的技能。

"查询订单物流状态"这个需求，用户问的频率很高，输入是一个订单号，输出是物流轨迹和时间节点，而且它本身是"下单"之后的后续动作，不需要前置技能，完全可以独立。于是我把它定为基础领域技能。

这一步有个容易踩的坑：把"查询所有订单"和"查询单个订单物流"合并成一个技能。乍一看都是查订单，但两者的输入范式完全不同，而且"查询所有订单"通常还要涉及分页、状态过滤这类复杂参数，合并后描述会非常乱。所以我的原则是：输入范式不同，就拆开。

4.2 技能元数据编写：把业务逻辑翻译成模型语言

确定要做之后，我写了一份技能定义文档，核心内容如下：

技能名: 查询订单物流状态 摘要: 根据订单号查询物流运输轨迹与当前状态，包括已揽收、运输中、已签收、异常等节点。 适用场景: 用户询问"我的包裹到哪了""发货了吗""快递什么时候到""物流怎么不动了"等。 不适用场景: 仅查订单金额、改地址、催发货、申请退款等，请使用其他技能。 前置条件: 需要用户提供或从上下文推导出具体订单号；如果订单号缺失，必须先通过"获取用户近期订单"技能获取。 参数格式: order_id 字符串类型，最长20位；allow_exception_detail 可选布尔值，默认 false。 副作用: 本技能为只读操作，不修改任何业务数据。 输出格式: 结构化物流节点列表+当前状态摘要；若物流异常，额外输出异常原因。 示例: - "我的P20240601订单到哪了" -> 提取 order_id=P20240601 - "帮我看看最近那个快递" -> 若上下文有近期订单，自动映射 - "查一下JD88888888到没到" -> 如果该单号属于其他业务域，提示用户确认识别失败

写完之后我会专门检查一遍描述里有没有"歧义词"和"过度承诺词"。比如"处理"这种动词就太宽泛，我习惯改成"查询""创建""更新"这类明确的动作；再比如"本技能可以解决用户所有问题"这种话绝对不能出现，因为模型一旦读到"包治百病"，它就什么都敢接。

4.3 逻辑实现与参数归一：让真实世界适配统一契约

元数据写完之后才是编码实现。很多团队倒过来，先写代码再补描述，结果描述只能照着代码的接口来，把"底层逻辑"当成了"业务能力"，模型自然看不懂。

我在实现阶段最注意参数归一化。用户说话千奇百怪，按理说参数解析是大模型的任务，但业务接口可没那么灵活。我的做法是：技能内部自带一层"参数适配器"，把模型传来的语义化参数转换成后端接口真正要的格式。

比如用户说"帮我看看那个蓝色杯子的快递"，模型提取出的是"蓝色杯子"这个模糊指代，后端接口却只接受订单号。适配器就会先去本地会话上下文里查最近浏览记录或最近订单，把"蓝色杯子"映射到具体订单号，再传给后端。这样技能对外的描述可以保持轻量，重活都在内部消化。

4.4 描述测试：用"魔鬼用例"验证模型的选择与调用

技能写完之后，最忌讳的就是没测试直接上线。我会专门构造一批"魔鬼用例"来验证两件事：一是该技能该被选中时，模型是否能选到它；二是该技能不该被选中时，模型是否会被其他技能抢走或者错误触发。

测试方法很简单，我准备了一个测试集，每条都是一段真实的用户话术，去掉标准答案之后，让Agent完整跑一遍。我关注两个指标：技能命中率（该调的技能有没有被调）和参数正确率（调用时参数提取正不正确）。

这里要特别强调：很多人只测"命中率"，觉得技能被调了就万事大吉，结果忽略了参数正确率。实际上参数错了，技能调了等于白调。我在订单查询技能上加了"缺订单号提醒"的处理逻辑，就是为了应对那些无法从上下文推导出订单号的场景——模型如果硬着头皮编一个订单号调接口，后端直接查无此单，体验非常糟。所以技能描述里的"前置条件"不只是给模型看的约束，更要落到代码里做兜底。

4.5 灰度发布与持续维护

一个新技能上线后，我不会一次性全量放开，而是选择10%的流量观察一段时间。观察什么？主要看两个东西：其一，有没有出现"误调用"——本来不该用这个技能的请求，模型调了它；其二，有没有出现"拒调用"——本来应该用这个技能的场景，模型却选择自己编答案。

这两类问题在线上日志里都有明显特征，误调用能看到"同一个会话里连续触发多个不相关技能"的记录，拒调用则表现为Agent回答里出现了"很抱歉我无法完成"之类的兜底话术。我的处理办法是，把出问题的会话样本收集回来，反哺到技能的描述说明里。

记得有一次，用户问"能不能帮我拦截一下快递"，按逻辑这应该走"快递拦截"技能。但当时我们的Agent调用了"查询订单物流状态"，然后在话术里说"您的快递已到xx站，暂时无法拦截"。这就是典型的误调用。原因是我在"订单物流"技能的例子里写了"包裹到哪了"的变体，模型按照语义相似度把"拦截"也归进来了。修正方案是给物流技能加一条反例："如果用户有拦截、改址、催派等操作需求，请不要调用本技能，应转至对应的操作类技能。"加上这条之后，再没出现过同类错误。

5. 技能协作场景：编排、上下文传递与错误自愈

单技能用得好，只是第一步。真实业务里，用户的需求往往要串联多个技能才能完成。比如开头说的"查流量包并办理"就是一个组合动作。技能一旦多起来，编排就成了核心难题。

我一开始做编排时，很喜欢给模型写一大堆"流程模板"，告诉它遇到这个场景就按这个顺序调技能。后来发现这种做法极其脆弱，因为用户的话术千变万化，流程模板没法覆盖所有分支。更合理的思路是：靠技能描述里的"衔接信息"让模型自然形成调用链，同时在上层做轻量的编排约束。

5.1 上下文传递：上一个技能的输出，就是下一个技能的输入

技能之间的衔接，最基础的是参数传递。模型规划出"A技能输出 → B技能输入"的链路之后，需要能够准确提取A技能输出中的关键字段，填充到B技能的参数里。这个能力一部分靠模型本身，一部分靠技能描述里的输出提示。

我在技能描述里加了一行"输出复用"说明，专门告诉模型这个技能产出什么字段，可以被哪些技能消费。比如客服场景里"获取用户身份"技能的输出是user_id，"查询订单"技能的前置条件就是user_id。描述里明确写"本技能输出user_id可用于后续查询订单、查询工单等技能"，模型在编排时就更倾向于建立这个链路。

5.2 错误自愈：让模型能从失败中自己爬出来

技能执行一定会出错，但Agent和普通程序不同——程序出错可以抛异常给开发者，Agent出错抛给谁？只能抛给模型自己。

所以我们设计的每个技能，返回值都做了"结构化描述"，不只是一串错误码，而是解释性的错误信息。比如"退款失败"的返回，不是给一个"500"，而是"退款失败：由于订单已超过7天无理由退换期限，无法执行退款操作。请向用户说明原因，并推荐转人工客服。"

这行文字的作用非常大。模型读到这个错误之后，不但不会傻傻地再重试一次，反而可能直接生成一段安抚用户的回答，并把会话转接给人工客服。这就是"错误自愈"——让技能把失败原因翻译成人话，交给模型去决策下一步。很多团队忽略了这一点，把错误处理逻辑全写在后端代码里，模型根本不知道发生了什么，只能机械地返回"系统繁忙"。

5.3 编排约束的取舍：该锁死的地方别让模型自由发挥

当然，也不是所有流程都适合让模型自由编排。有些业务有强约束，比如"必须先查库存再下单"、"退款金额必须小于等于订单金额"，这种规则如果光靠描述来约束，模型偶尔会犯错。

我的做法是：把强约束的流程做成"复合技能"。复合技能是一个特殊的技能类型，它的内部逻辑是由代码预定义的多个子技能调用序列，对外只暴露一个粗粒度的入口。模型只需要决定"要不要走这个复合技能"，而不用管内部怎么编排。

比如"下单"复合技能，内部逻辑是：查库存→锁库存→创建订单→返回订单号。模型看到用户的"买一个"需求，只需要调用这个复合技能，完全不用自己编排内部顺序。这样做的好处是：把关键流程的确定性握在工程手里，把灵活性留给模型。

这个设计思路也是我后续把"skills"拆成基础技能和复合技能两层的原因，后面在版本管理上也受益很多。

6. 技能测试与回归：升级时如何防止Agent"变异"

技能系统上线一段时间后，还有一个隐蔽的问题会冒出来：技能本身没有变，但模型版本升级了，或者技能描述被某个同事微调了一下，Agent行为就"变异"了——以前能正确调用的场景，现在不调了。这种问题比Bug还难排查，因为它不是报错，而是静悄悄的行为改变。

所以我在项目里建立了技能回归测试体系，核心思路是：把每次的"技能调用决策样本"沉淀成回归测试集，每次技能描述变更或模型升级，都跑一遍完整的测评。

6.1 回归测试集的建设：从用户会话里挖金子

回归测试集的来源主要有三个：线上真实会话、我们人工构造的边界场景、以及历史踩坑样本。每个样本都记录完整的三元组：用户输入、期望命中的技能、期望提取的参数。

我特别重视"历史踩坑样本"——凡是线上出现过误调用或者拒调用的会话，都会被我手动标注后放进测试集。比如前面提到的"拦截快递"场景，用户输入"能拦截快递吗"，期望命中的技能是"快递拦截"，期望参数是"包裹号"。这样做的好处是，以后再改技能描述，我立刻能知道这个行为是否被破坏了。

回归测试集不需要特别大，但要覆盖几个关键分支：正常用法、边界表达、歧义表达、故障场景。我目前维护的一个核心测试集大概两百条左右，跑一次大概需要几分钟，已经完全够用。

6.2 变更评审制度：给技能描述加一道审查门槛

有了测试集之后，还需要一个制度来保证"每次变更都走测评"。我们团队定了一个简单的规则：任何人改动技能描述或者技能代码，必须同时更新回归测试集并附上测评报告。测评报告里要写清楚三个东西：变更动机、预期行为变化、回归测试通过率。

有一次我改动了"查流量包"技能的摘要，只是把"最合适"改成了"最优惠且符合用户当前使用习惯"，结果回归测试发现有三个样本出现了跳技能的现象。虽然改动看似更友好，但模型的决策边界被扩大了，导致部分场景下它开始过度解读"符合使用习惯"。这个例子说明：技能的描述是极其敏感的，动不动就"变异"，必须有回归测试兜底。

6.3 模型版本升级时的技能兼容评估

还有一个容易忽略的点：底层模型升级时，技能系统也要跟着回归测试。大模型的语义理解能力在不同版本之间有差异，同一个描述在旧版本模型上的表现不能直接默认为在新版本上也成立。

我记得有一回我们把底层模型从旧版切换到了新版，其他功能都很顺利，唯独"订单退款"技能的调用率掉了不少。排查了半天，发现新模型对"退单""撤销订单""不要了"这类口语表达的语义聚类更保守，导致很多该走退款技能的请求被分流到了"查询订单"。解决方式是在退款技能的摘要里，主动增加了一组口语化同义词："退单、取消订单、不要了、想撤"。

这个经验让我养成了一个习惯：每次模型升级，都专门安排一次技能回归，别等到线上出了事故再查。

7. 技能化改造的收益与代价：我的实测数据与经验

最后聊点实际的。很多人会问：把工具改造成这套"技能体系"到底值不值得？投入产出比高不高？我不敢说所有业务场景都适合，但至少我自己实测下来，收益是非常明显的。

7.1 实测数据：三个关键指标的变化

我在几个项目里都做了改造前后的对比，挑选其中一组客服场景的数据：

需要说明的是，这组数据来自我自己的实验环境，不同业务肯定会有波动。但它反映的趋势是稳定的：技能体系可以大幅减少模型的瞎猜成本，让任务流量更集中地流向正确路径。

7.2 代价：哪些成本容易低估

技能化改造不是免费的。第一个成本是描述设计的时间，每个技能从需求分析到描述定稿，我的平均投入大概在半天到一天，复杂技能还要更久。第二个成本是回归测试集的维护，这活儿需要持续投入，不是一次性做完就结束的。第三个成本是复合技能的沉淀，当基础技能的粒度切得越来越细，复合技能的设计复杂度会上升，需要有人花精力去做编排规划。

所以我的建议是：如果你只是临时跑个小Demo，平铺函数完全够用，别一上来就搭技能体系。但如果你要长期维护一个面向用户的Agent，那这套投入是值得的。

7.3 留一个可扩展的落点

从我个人的体会来看，技能体系一旦建立起来，后面的扩展路径会非常清晰。比如新人加入项目，看技能描述文档就能快速了解Agent具备什么能力，不用翻代码；再比如要做多Agent协作，技能就是Agent之间的"标准岗位说明书"，可按需调遣别的Agent来执行它擅长的技能。我现在已经在尝试把已有技能开放成独立服务，让它们在别的场景里也能被复用，这个方向后面有机会再单独写一篇。

回到最初的"agent-skills"这个主题，我想说的其实就一句话：Agent的能力边界，不是由模型决定的，而是由你给了它哪些"能理解、能正确调用"的技能决定的。把技能的每个描述当产品来做，把技能的每次变更当一次版本迭代来管，你的Agent会稳定得多。