agent-skills：从工具调用到技能封装，构建能上岗的智能体

1. 从“会聊”到“会干”：agent-skills 到底在解决什么问题

第一次看到 agent-skills 这个词，我的直觉是：终于有人把“智能体到底该会哪些手艺”这件事，从玄学拉回到了工程清单。过去一年，大家聊智能体，聊的都是“它能理解我”“它能规划任务”“它能调用工具”，但真正落地到业务里，你会发现一个尴尬的现实——大部分智能体只会聊天，不会干活。你让它订个会议室，它给你写一段会议纪要模板；你让它查个库存，它反问你“您指的是哪个仓库”。问题不在模型不够聪明，而在于我们从来没有系统性地定义过：一个能上岗的智能体，到底需要具备哪些可拆解、可训练、可评估的技能。

agent-skills 这个项目标题，本质上指向的就是这套“技能体系”的构建与沉淀。它不是某一个具体框架，也不是某一个模型，而是一套关于智能体能力拆解、技能封装、调用编排的方法论加工程实践。说得再直白一点，它要回答的是：当你要做一个真正能替人跑腿、替人操作软件、替人处理多步流程的智能体时，你该给它装哪些“手艺”，这些手艺怎么描述、怎么组合、怎么验证它真的学会了。

这套东西适合谁？如果你只是拿大模型做做问答、写写文案，那 agent-skills 对你来说可能有点重。但如果你正在做 RPA 升级、做自动化流程、做多智能体协作、做企业内部的“数字员工”，那你一定会遇到一个绕不开的坎：单个工具调用谁都会写，但把十几个工具、几十个步骤、若干条件分支串成一个稳定可靠的技能，并且让智能体自己知道什么时候该用哪一招，这才是真正的难点。agent-skills 就是冲着这个难点去的。

我自己的体会是，智能体的能力上限，不取决于它背后挂的模型有多大，而取决于你把它的技能边界切得有多清楚。一个技能如果定义得含糊，比如“处理订单”，那智能体大概率会翻车；但如果拆成“查询订单状态”“修改收货地址”“申请退款”“催发货”这四个独立技能，每个技能有明确的输入输出、前置条件、失败回退，那整个系统的稳定性会立刻上一个台阶。agent-skills 的核心价值，就在于把这种“拆”的功夫标准化、可复用化。

接下来的内容，我会从整体设计思路、核心技能拆解、实操落地过程、常见坑与排查四个维度，把 agent-skills 这套东西掰开揉碎讲一遍。里面会涉及不少我实际踩过的坑和总结出来的参数配置，你可以直接拿去改改就用。

2. 整体设计思路：为什么是“技能”而不是“工具”

2.1 工具调用和技能封装，差的是哪一层

很多人一上来就把 agent-skills 理解成“工具调用的集合”，这个理解不能说错，但太浅了。工具调用解决的是“手能够到”的问题，技能封装解决的是“手知道怎么用、什么时候用、用错了怎么办”的问题。举个例子，你给智能体挂了一个“发送邮件”的 API，这是工具。但“给客户发送一封包含报价单的跟进邮件”就是一个技能，它里面包含了：查客户信息、生成报价单、选择邮件模板、填写收件人、附加文件、发送、记录日志、如果发送失败则重试或转人工。你看，一个技能里面可能调用了五六个工具，还包含了条件判断和异常处理。

为什么非要封装成技能？因为如果你让智能体每次面对“发跟进邮件”这个任务时，都从零开始规划该调哪些工具、按什么顺序调，那它的表现会极其不稳定。今天它记得先查客户，明天它可能直接拿个空邮箱就发了。技能封装的意义，就是把“最佳实践路径”固化下来，让智能体在遇到同类任务时，直接走这条已经验证过的路，而不是每次都在迷宫里重新找出口。

从工程角度看，技能封装还带来了一个巨大的好处：可测试性。一个工具调用很难单独测试，因为你不知道它在整个流程里处于什么位置。但一个技能有明确的入口和出口，你可以给它一组输入，断言它应该产生什么输出，这就让自动化测试成为可能。没有可测试性，就没有可靠性，这是我在多个项目里反复验证过的铁律。

2.2 技能分层：原子技能、组合技能、领域技能

在实际设计 agent-skills 体系时，我习惯把技能分成三层。最底层是原子技能，它对应的是单个工具或单个 API 的调用，比如“读取文件”“发送 HTTP 请求”“执行 SQL 查询”。这一层的特点是粒度极细、通用性极强，但单独拿出来几乎没有业务价值。中间层是组合技能，它把若干原子技能按固定顺序编排起来，完成一个相对完整的子任务，比如“从数据库导出数据并生成 CSV 文件”。最上层是领域技能，它面向具体的业务场景，比如“处理客户退款申请”“生成月度运营报告”，里面会调用多个组合技能，并且包含大量的业务规则判断。

为什么要分三层？因为不同层的技能，变更频率和复用范围完全不同。原子技能基本不变，组合技能偶尔调整，领域技能则随着业务规则频繁变化。如果你把这三层混在一起，每次业务规则一变，你就要动最底层的代码，那维护成本会高到离谱。分层之后，业务变化只需要修改领域技能层，下面的组合技能和原子技能可以原封不动地复用。

这里有一个很关键的实操心得：原子技能的数量要严格控制。我见过一些团队，恨不得把每个 API 都封装成一个原子技能，结果技能库膨胀到几百个，智能体在规划时反而不知道该选哪个。我的建议是，原子技能只封装那些会被多个组合技能复用的基础操作，比如“HTTP 请求”“文件读写”“数据库查询”“消息发送”这四类，基本就能覆盖八成以上的场景。剩下的业务逻辑，全部放到组合技能和领域技能里去。

2.3 技能描述规范：让智能体“看得懂”比“写得好”更重要

技能封装完之后，智能体怎么知道该用哪个技能？靠的是技能描述。这里有一个巨大的坑：很多开发者写技能描述时，是按照给人看的方式写的，比如“本技能用于处理订单相关的各种操作”。这种描述对人来说没问题，但对智能体来说信息量太低了。智能体需要的是：这个技能具体做什么、什么时候用、输入什么、输出什么、有什么限制。

我总结了一套技能描述的模板，实测下来智能体的选择准确率能提升不少。每个技能描述必须包含五个要素：动作（这个技能执行什么操作）、触发条件（什么情况下应该使用这个技能）、输入参数（每个参数的类型、含义、是否必填）、输出结果（返回什么数据、什么格式）、失败模式（什么情况下会失败、失败后怎么处理）。这五个要素缺一个，智能体在调用时就可能出问题。

举个例子，一个“查询订单状态”的技能，描述不能只写“查询订单状态”，而要写成：“根据订单号查询订单的当前状态。当用户询问订单进度、物流信息、是否发货时使用此技能。输入参数为订单号（字符串，必填，格式为纯数字）。输出为订单状态码和状态描述。如果订单号不存在，返回错误码 404；如果订单号格式不正确，返回错误码 400。”你看，这样写完之后，智能体不仅知道该什么时候用，还知道用错了会怎样。

注意：技能描述里的触发条件要尽量覆盖同义表达。比如“查询订单状态”这个技能，触发条件里最好把“订单到哪了”“发货了吗”“物流什么情况”“什么时候能到”这些用户可能说的口语化表达都列进去。智能体在做技能匹配时，靠的就是这些语义线索。

3. 核心技能拆解与实操要点

3.1 信息检索类技能：别让智能体“瞎猜”

信息检索是智能体最基础也最常用的技能。看起来很简单——给个关键词，返回结果。但实际操作中，这里面的坑多到数不清。第一个坑是检索源的选择。你是让智能体去查数据库、查 API、还是查向量库？这三种源适合的场景完全不同。数据库适合精确查询，比如“订单号 12345 的状态”；API 适合实时性要求高的查询，比如“当前库存”；向量库适合模糊语义查询，比如“找一下和这个客户需求类似的案例”。

我的经验是，不要让智能体自己决定用哪个检索源。你应该在技能层面就把检索源固定下来，做成三个独立的技能：“精确查询数据库”“调用实时 API”“语义检索知识库”。然后在领域技能层，根据用户意图来决定调用哪个。这样做的好处是，每个技能的内部逻辑可以针对特定的检索源做深度优化，比如数据库查询技能可以内置 SQL 注入防护和分页逻辑，向量检索技能可以内置重排序和阈值过滤。

第二个坑是检索结果的截断和摘要。你从数据库查出来 500 条记录，不可能全部塞给智能体，那样会直接把上下文撑爆。所以检索类技能必须内置结果处理逻辑：先按相关性排序，取 Top N（我一般设 5 到 10），然后对每条结果做摘要，只保留关键字段。这个摘要逻辑要写在技能内部，而不是让智能体自己去总结，因为智能体总结时可能会丢失关键信息。

第三个坑是空结果的处理。用户问“帮我查一下订单 99999 的状态”，结果数据库里根本没有这个订单。这时候技能不能直接返回空，而要返回一个结构化的“未找到”响应，并且附带建议，比如“未找到该订单，请确认订单号是否正确，或尝试按客户姓名查询”。这个建议文案要提前写好，放在技能配置里，而不是让智能体临场发挥。

3.2 操作执行类技能：幂等性和回滚是生命线

操作执行类技能，比如“创建订单”“发送邮件”“修改配置”，是风险最高的一类技能。因为一旦执行错了，可能会产生真实世界的副作用。我在这类技能上踩过最惨的坑，就是重复执行。智能体在规划时，可能会因为超时重试或者逻辑判断失误，把同一个“创建订单”的技能调用了两次，结果用户被扣了两次款。这个问题在测试环境很难发现，因为测试环境的超时概率低，但到了生产环境，网络抖动一多，重复执行的概率就上来了。

解决这个问题的核心手段是幂等性设计。每个操作执行类技能，都必须接受一个幂等键（idempotency key），这个键由调用方生成，通常是“任务 ID + 步骤序号”的组合。技能内部在执行前先检查这个键是否已经处理过，如果处理过就直接返回上次的结果，不再重复执行。这个逻辑听起来简单，但必须写进技能模板里，强制每个操作类技能都实现，否则迟早会出事。

另一个关键设计是回滚机制。一个领域技能可能包含多个操作步骤，比如“创建订单 → 扣减库存 → 发送确认邮件”。如果扣减库存失败了，创建订单那一步要不要撤销？如果不撤销，就会产生脏数据。所以每个操作类技能都要配套一个“补偿技能”，用来撤销之前的操作。补偿技能不一定要很复杂，有时候就是“把状态标记为已取消”，但必须有。我在设计时，会把领域技能里的每个步骤都标注上“是否需要补偿”，然后在技能编排层统一处理回滚逻辑。

提示：补偿技能本身也可能失败。所以补偿逻辑要有重试机制，并且重试次数用完后，要触发告警并转人工处理。千万不要假设补偿一定会成功，那样你会睡不好觉的。

3.3 数据处理类技能：格式转换和校验是重头戏

数据处理类技能，比如“解析 CSV”“转换日期格式”“校验手机号”，看起来最不起眼，但实际上是智能体日常调用最频繁的一类。这类技能的核心要求是确定性——同样的输入必须产生同样的输出，不能有任何随机性。我见过一个团队，他们的日期解析技能用了智能体来做，结果同一个日期字符串，有时候解析成“2024-01-01”，有时候解析成“01/01/2024”，导致下游系统直接崩溃。这种技能必须用纯代码实现，不能掺任何模型推理。

数据处理类技能的另一个重点是校验前置。比如“导入客户数据”这个技能，在真正写入数据库之前，必须先校验：手机号格式对不对、邮箱格式对不对、必填字段有没有缺失、数据长度有没有超限。这些校验规则要全部写在技能内部，并且校验失败时要返回具体的错误信息，告诉调用方是哪一行、哪一列、出了什么问题。如果校验不通过就直接抛一个“数据格式错误”，那调用方根本不知道怎么修。

我一般会把数据处理类技能设计成“管道”模式：输入数据先经过一系列校验器，每个校验器负责一项检查，全部通过后才进入转换器，转换完成后再经过输出格式化器。这个管道里的每一步都是可配置的，比如你可以通过配置来决定是否开启手机号校验、是否允许空值。这种设计的好处是，同一个技能可以通过不同配置适配不同的业务场景，而不需要为每个场景写一个新技能。

3.4 通信协作类技能：消息格式和路由策略

通信协作类技能，包括“发送消息”“通知用户”“请求审批”“调用其他智能体”，是支撑多智能体协作的基础。这类技能最核心的设计点是消息格式的标准化。如果每个智能体发消息的格式都不一样，那接收方解析起来会非常痛苦。我建议采用一套统一的消息信封格式，里面包含：发送者 ID、接收者 ID、消息类型、时间戳、优先级、正文、附件引用。正文可以用 JSON 或 Markdown，但信封结构必须固定。

路由策略是另一个关键点。当一个智能体需要把任务转交给另一个智能体时，它怎么知道该转给谁？最简单的做法是硬编码路由表，比如“退款问题转给财务智能体”。但这种方式扩展性很差，每加一个智能体就要改路由表。更好的做法是基于能力注册的路由：每个智能体启动时，向注册中心声明自己具备哪些技能；当需要转交任务时，根据任务所需的技能去查询注册中心，找到具备该技能的智能体列表，再根据负载或优先级选择一个。这套机制实现起来不复杂，但能让整个系统的扩展性提升一个档次。

注意：通信类技能一定要设置超时和重试上限。我见过一个案例，两个智能体互相等待对方响应，结果双双超时，整个流程卡死。所以每个通信技能都要有明确的超时时间（我一般设 30 秒），超时后要么重试，要么走降级路径，绝不能无限等待。

4. 实操过程：从零搭建一个 agent-skills 体系

4.1 技能注册中心的搭建与配置

搭建 agent-skills 体系的第一步，是建立一个技能注册中心。这个注册中心不需要很复杂，一个 JSON 文件或者一张数据库表就能起步。核心字段包括：技能 ID、技能名称、技能描述、技能类型（原子/组合/领域）、输入参数 schema、输出结果 schema、依赖的技能列表、超时时间、重试策略、幂等性要求。

我一般用 YAML 来定义技能，因为可读性好，而且方便版本管理。下面是一个技能定义的示例：

skill_id: query_order_status name: 查询订单状态 type: atomic description: | 根据订单号查询订单的当前状态。 当用户询问订单进度、物流信息、是否发货时使用此技能。 inputs: - name: order_id type: string required: true pattern: "^[0-9]{8,12}$" description: 订单号，8到12位纯数字 outputs: - name: status_code type: integer description: 订单状态码，200表示成功，404表示订单不存在 - name: status_text type: string description: 订单状态描述 timeout: 10 retry: 2 idempotent: true

这个定义写完之后，注册中心就可以根据它来生成技能调用的接口文档，智能体也可以根据 description 和 inputs 来决定是否调用。这里有一个实操细节：pattern 字段非常重要。它让智能体在调用之前就能做一次参数格式校验，避免把明显不合法的参数传进来。我统计过，加上 pattern 校验之后，参数错误导致的技能失败率下降了大约六成。

注册中心还需要一个技能发现接口。智能体在规划时，会先调用这个接口，传入当前任务描述，注册中心返回匹配的技能列表。匹配算法可以用简单的关键词匹配起步，后面再升级到向量检索。我建议初期不要搞太复杂，先把技能描述写好，关键词匹配的准确率就能达到可用的水平。

4.2 技能编排引擎的核心逻辑

技能编排引擎是 agent-skills 体系的大脑。它的输入是一个任务描述，输出是一个技能调用序列。最简单的编排方式是线性编排：把任务拆成若干步骤，每个步骤对应一个技能，按顺序执行。但实际场景往往需要条件分支和循环，所以编排引擎需要支持更复杂的控制流。

我一般用有向无环图（DAG）来表示技能编排。每个节点是一个技能调用，每条边是数据依赖或控制依赖。编排引擎从入口节点开始执行，当一个节点的所有前置依赖都满足时，就触发该节点。如果某个节点执行失败，引擎会根据预设的策略决定是重试、跳过还是回滚。

这里有一个关键参数：最大并行度。有些技能之间没有依赖关系，可以并行执行，比如“查询库存”和“查询价格”可以同时进行。但并行度不能无限大，否则会把下游系统打垮。我一般把最大并行度设为 5，这个值是根据下游系统的承载能力和实际压测结果调出来的。你可以根据自己系统的情况调整，但建议不要超过 10。

编排引擎还需要一个执行日志模块，记录每个技能调用的输入、输出、耗时、状态。这个日志在排查问题时极其重要。我遇到过好几次智能体行为异常的情况，最后都是靠执行日志定位到是某个技能的返回格式变了，导致后续技能解析失败。日志要保留至少 7 天，并且要支持按任务 ID 和技能 ID 检索。

4.3 技能测试与验证：怎么知道技能真的学会了

技能写完之后，怎么验证它真的能工作？我一般分三步走。第一步是单元测试，针对每个原子技能，用固定的输入验证输出是否符合预期。这一步用普通的测试框架就能做，关键是要覆盖边界情况：空输入、超长输入、特殊字符、并发调用。我见过一个技能在单线程下工作正常，一上并发就出现数据竞争，所以并发测试一定要做。

第二步是集成测试，把多个技能串起来，验证它们之间的数据传递是否正确。这一步最容易发现的问题是数据格式不匹配：上游技能返回的是字符串，下游技能期望的是整数；上游返回的是数组，下游期望的是单个对象。这类问题在单元测试里发现不了，只有串起来跑才会暴露。我的做法是，在技能定义里严格声明输入输出的类型，然后在编排引擎里加一层类型校验，不匹配就直接报错，而不是让智能体去猜。

第三步是场景测试，用真实的用户请求来测试整个 agent-skills 体系。这一步的关键是构造多样化的测试用例。不能只测“正常路径”，还要测“异常路径”：用户输入了不存在的订单号、用户中途改变了主意、某个下游服务超时了。我一般会为每个领域技能准备至少 20 个测试用例，其中一半是异常场景。这些用例跑通之后，我才敢把技能放到生产环境。

提示：场景测试的用例要定期更新。因为用户的行为模式会变化，新的异常情况会不断出现。我建议每个月回顾一次线上失败案例，把新的失败模式补充到测试用例里，形成一个持续改进的闭环。

4.4 技能版本管理与灰度发布

技能不是写完就一劳永逸的，业务变化了，技能也要跟着改。但技能一改，所有依赖它的领域技能都可能受影响。所以版本管理是必须的。我一般用语义化版本号：主版本号表示不兼容的变更，次版本号表示向后兼容的功能新增，修订号表示向后兼容的问题修复。当主版本号升级时，依赖它的领域技能必须显式声明使用新版本，否则继续用旧版本。

灰度发布是降低风险的关键手段。新版本的技能上线时，先只让 10% 的流量走新版本，观察一段时间（我一般观察 24 小时），确认没有异常后，再逐步扩大到 50%、100%。灰度期间要重点监控几个指标：技能调用成功率、平均耗时、错误码分布。如果新版本的成功率比旧版本低超过 1 个百分点，就自动回滚。

这里有一个实操细节：灰度发布要按任务维度而不是按调用维度来切。也就是说，同一个任务的所有技能调用，要么全走新版本，要么全走旧版本，不能混着来。否则一个任务里一半用旧版一半用新版，数据格式可能对不上，排查起来会非常痛苦。

5. 常见问题与排查技巧实录

5.1 技能选择错误：智能体为什么总是选错技能

技能选择错误是最常见的问题，表现是智能体调用了不相关的技能，或者该调用 A 技能时调用了 B 技能。根本原因通常是技能描述之间的区分度不够。比如你有两个技能：“查询订单”和“查询物流”，描述里都写了“查询订单相关信息”，智能体自然分不清。解决办法是，在描述里明确写出排除条件：查询订单技能描述里加一句“此技能不返回物流轨迹信息，如需物流轨迹请使用查询物流技能”。

另一个原因是技能数量太多。当技能库超过 50 个技能时，智能体的选择准确率会明显下降。这时候需要做技能分组：把技能按领域分成若干组，智能体先选组，再选组内的技能。这个两阶段选择的过程，比一次性从 50 个技能里选一个要准确得多。我实测下来，分组之后选择准确率能从 70% 左右提升到 90% 以上。

还有一个隐蔽的原因是技能描述里的触发条件写得太窄。比如“查询订单状态”的触发条件只写了“用户询问订单状态”，但用户实际可能说“我的快递到哪了”“我买的东西发货了吗”。这些表达没有被覆盖到，智能体就匹配不上。解决办法是，在触发条件里尽量穷举同义表达，并且定期从线上日志里挖掘新的用户表达，补充进去。

5.2 参数传递失败：数据在技能之间“丢”了

参数传递失败的表现是，上游技能明明返回了数据，但下游技能收到的却是空值或默认值。这个问题通常出在字段映射上。上游技能返回的字段叫order_status，下游技能期望的字段叫status，名字对不上，数据就传不过去。解决办法是，在技能定义里明确声明输入输出的字段名，并且在编排引擎里做字段映射配置。我一般会维护一张映射表，记录每个技能的输出字段到下游技能输入字段的对应关系。

另一个常见原因是数据类型不匹配。上游返回的是字符串"123"，下游期望的是整数123，有些编排引擎会自动转换，有些不会。如果不会转换，下游技能就会报类型错误。我的做法是，在技能定义里严格声明类型，并且在编排引擎里加一层类型转换层，遇到不匹配时尝试自动转换，转换失败则报错并记录日志。

还有一种情况是数据被意外覆盖。多个技能可能输出同名字段，比如两个技能都返回status字段，后执行的技能会覆盖先执行的技能的输出。这个问题很隐蔽，因为日志里看每个技能的返回值都是对的，但最终结果就是不对。解决办法是，在编排引擎里给每个技能的输出加一个命名空间前缀，比如skill_a.status和skill_b.status，这样就不会互相覆盖了。

5.3 超时与重试：什么时候该重试，什么时候该放弃

超时和重试策略设置不当，会导致两种极端：要么频繁重试把下游系统打垮，要么一次超时就放弃导致任务失败。我的经验是，根据技能类型来设置不同的策略。查询类技能可以多试几次，因为查询通常是幂等的，重试没有副作用；操作类技能要谨慎重试，必须配合幂等键，否则可能重复执行；通信类技能要设置较短的超时，因为通信延迟通常意味着对方有问题，重试太多次也没用。

具体参数上，我一般这样设置：查询类技能超时 10 秒，重试 3 次，重试间隔 1 秒、2 秒、4 秒（指数退避）；操作类技能超时 30 秒，重试 1 次，重试间隔 5 秒；通信类技能超时 15 秒，重试 2 次，重试间隔 3 秒。这些数值不是绝对的，你需要根据自己的系统响应时间和网络状况来调整。调整的依据是监控数据：如果发现某个技能的超时率超过 5%，要么优化技能本身的性能，要么放宽超时时间。

注意：重试次数不是越多越好。我见过一个团队把重试次数设成 10 次，结果一个下游服务挂了之后，上游智能体疯狂重试，直接把下游服务的恢复时间拖长了好几倍。重试次数一般不要超过 3 次，超过 3 次还失败，基本可以认为不是偶发问题，应该走降级或转人工。

5.4 技能冲突与死锁：多智能体协作的暗礁

当多个智能体同时运行时，可能会出现技能冲突。比如两个智能体同时调用“修改库存”技能，一个要加库存，一个要减库存，如果没有并发控制，最终库存数可能不对。解决办法是给操作类技能加锁。锁的粒度可以按资源 ID 来分，比如按商品 ID 加锁，这样不同商品的库存修改可以并行，同一个商品的修改则串行。

死锁是更严重的问题。两个智能体互相等待对方释放资源，结果双双卡死。避免死锁的经典方法是按固定顺序获取锁。比如规定所有智能体必须先获取订单锁，再获取库存锁，不能反过来。这样就不会出现“A 等 B 释放库存锁，B 等 A 释放订单锁”的情况。这个规则要写进技能编排引擎的底层逻辑里，强制所有技能遵守。

还有一个隐蔽的问题是技能循环调用。智能体 A 调用智能体 B 的技能，智能体 B 又调用智能体 A 的技能，形成无限循环。解决办法是设置调用深度上限。我一般把最大调用深度设为 5，超过 5 层就强制中断并报错。这个限制要放在通信类技能里，每次调用时检查当前深度，超限就拒绝。

5.5 常见问题速查表

6. 技能体系的持续演进：从能用走向好用

6.1 技能效果度量：用数据说话

技能上线之后，不能靠感觉判断它好不好用，必须建立一套度量体系。我一般关注四个核心指标：调用成功率（技能被调用后成功返回的比例）、选择准确率（智能体选择的技能是否是正确的那个）、平均耗时（从技能被调用到返回结果的耗时）、用户满意度（通过后续交互判断用户是否满意）。这四个指标要按天统计，并且和上周同期对比，发现异常及时排查。

调用成功率低于 95% 就要警惕了，说明技能本身有问题。选择准确率低于 85% 说明技能描述需要优化。平均耗时如果突然上升，可能是下游服务出了问题。用户满意度这个指标比较难量化，我一般用“任务完成率”来替代：如果一个任务最终被用户确认完成，就算满意；如果用户中途放弃或反复纠正，就算不满意。这个指标虽然粗糙，但比没有强。

度量数据要可视化，做成仪表盘，让团队所有人都能看到。我见过一些团队，技能上线后就不管了，直到用户投诉才发现问题。有了仪表盘之后，问题通常在发生当天就能被发现，修复速度也快了很多。

6.2 技能自动发现：从日志里挖掘新技能

随着业务发展，总会出现新的任务类型，需要新的技能。这些新技能从哪里来？我的做法是从失败日志里挖掘。当智能体遇到一个任务，发现没有合适的技能可用时，它会记录一条“技能缺失”日志。我每周 review 一次这些日志，看看哪些任务类型出现频率高，然后考虑为它们开发新技能。

这个过程的自动化程度可以逐步提高。初期是人工 review 日志，手动识别模式。中期可以写一些脚本，自动聚类相似的失败任务，提取高频关键词。后期可以引入模型，让模型根据失败日志自动生成技能描述草稿，人工审核后发布。我目前处在中期阶段，用脚本聚类之后，发现新技能需求的效率比纯人工高了大概三倍。

提示：新技能发布后，要观察一段时间再决定是否保留。有些技能看起来需求很大，但实际发布后调用量很低，可能是因为智能体还是习惯用旧技能，或者新技能的描述不够吸引人。对于调用量持续低于阈值的技能，可以考虑下线，保持技能库的精简。

6.3 技能组合优化：把常用路径固化下来

当技能库运行一段时间后，你会发现某些技能组合被频繁一起调用。比如“查询订单状态”之后，经常跟着“查询物流轨迹”。这时候可以考虑把这两个技能合并成一个组合技能“查询订单及物流”，减少一次技能选择和参数传递，提升效率。

但合并也不是越多越好。合并太多会导致技能变得臃肿，失去灵活性。我的原则是：只合并那些调用频率高、且几乎总是成对出现的技能。如果两个技能只是偶尔一起出现，就不要合并，保持它们的独立性。我一般会统计技能之间的共现频率，共现频率超过 80% 的才考虑合并。

另一个优化方向是技能参数默认值。有些技能参数在大多数情况下都是同一个值，比如“查询订单状态”的include_logistics参数，90% 的情况下都是true。这时候可以把默认值设为true，智能体不传这个参数时就用默认值，减少参数传递的负担。但要注意，默认值要在技能描述里写清楚，否则智能体可能不知道有这个默认行为。

6.4 从单智能体到多智能体：技能体系的扩展

当业务复杂度上升到一定程度，单个智能体可能处理不过来，需要多个智能体协作。这时候 agent-skills 体系需要做一些扩展。首先是技能权限控制：不是每个智能体都能调用所有技能，比如财务智能体才能调用“退款”技能，客服智能体只能调用“查询”类技能。这个权限要在注册中心里配置，调用时校验。

其次是技能路由：当一个智能体需要某个技能但它自己没有权限时，它需要把任务转交给有权限的智能体。这个转交过程要标准化，我一般用“技能请求”消息来实现：请求方发送一个包含技能 ID 和参数的消息，接收方执行技能后返回结果。这个过程对请求方来说是透明的，它不需要知道接收方是谁，只需要知道技能 ID。

最后是技能编排的分布式执行。在多智能体环境下，一个领域技能可能跨越多个智能体执行。这时候编排引擎需要支持分布式事务：要么所有智能体的技能都执行成功，要么全部回滚。实现分布式事务比较复杂，我一般用“补偿事务”模式：每个智能体的操作都配套一个补偿操作，如果某个环节失败，就依次调用前面环节的补偿操作。这个模式不能保证强一致性，但能保证最终一致性，对大多数业务场景来说够用了。

6.5 我踩过的最大的一个坑

最后分享一个我踩过的最大的坑，希望能帮你省下几个通宵。有一次我们上线了一个新的“自动退款”领域技能，逻辑是：查询订单 → 校验退款条件 → 执行退款 → 发送通知。测试环境跑了几十遍都没问题，结果上线第一天就出事了。原因是并发：同一个订单，用户在前端点了两次退款按钮，两个请求同时进来，都通过了“校验退款条件”这一步，然后都执行了退款，用户被退了两次钱。

这个问题在测试环境没发现，因为测试时都是串行操作。解决办法是在“校验退款条件”和“执行退款”之间加一个分布式锁，锁的 key 是订单号。这样同一个订单的退款请求会串行执行，第二个请求进来时，第一个请求已经把钱退了，订单状态已经变成“已退款”，第二个请求的校验就会失败，不会重复退款。

这个坑教会我一个道理：任何涉及资金、库存、状态变更的技能，都必须考虑并发场景。测试的时候不能只测单线程，一定要用工具模拟并发请求。我后来在所有操作类技能的测试用例里都加了并发测试，再也没出过类似的问题。

这个内容后续还可以这样扩展：把技能体系和安全审计结合起来，每个技能调用都记录审计日志，满足合规要求；或者把技能体系和成本控制结合起来，给每个技能设置调用配额，防止某个智能体过度消耗资源。这些方向我都在探索中，有机会再单独写一篇分享。