给Agent装上“可插拔的手脚”：agent-skills技能编排实战拆解
年后那段时间一直在折腾Agent，工具调用（Tool Call）倒是跑通了，但很快就发现一个尴尬的问题：Agent在复杂任务里经常把工具用错、用乱，或者说根本不知道该在什么时候用哪个工具。后来我换了个思路，不再把能力看成一个个孤立的“工具”，而是把整个体系重构成一套按领域划分、可注册、可编排、可热插拔的技能（Skill）体系，这套东西我暂时叫它agent-skills。今天这篇文章就把这套技能体系的完整设计思路、注册机制、编排原理、实操代码和踩坑记录摊开聊一聊，给正在做Agent开发、尤其是卡在多工具协作和任务编排这步的朋友们一份可以直接抄作业的参考。
1. 为什么需要一套技能体系
1.1 从Tool Call到Skill的演进
早先做Agent，最朴素的做法就是给大模型塞一堆函数的JSON Schema，让它按需调用。这种方式在Demo里跑得通，一到生产环境就露馅了。大模型面对十几个乃至几十个工具描述时，会出现明显的“选择困难症”和“幻觉调用”——明明要查天气，它偏偏去调了日历接口；明明需要先算后查，它把顺序搞反。核心原因不是模型不够聪明，而是工具本身是“死”的，它们之间没有上下文关联、没有前后置条件、没有失败降级策略，模型只能在平铺的函数列表里“盲选”。
所以我把思路从Tool Call升级到了Skill。什么是Skill？你可以把Tool理解为“一个动作”，而Skill是“一套包含动作、输入输出约束、前置条件、失败处理逻辑的完整能力单元”。比如“查询电商订单”是一个Tool，但“处理售后工单”就是一个Skill，它内部可能需要先查订单、再查物流、再判断是否超时，最后生成处理建议。Skill把零散动作封装成了Agent可以直接消费的“能力积木”。
这套体系下来，Agent不再需要面对几百个碎片化函数，它只需要在几十个Skill里做选择，每一个Skill内部已经包含了完整的业务逻辑和参数校验规则，准确率和可维护性都提升了一个量级。
1.2 agent-skills想解决的问题
我设计agent-skills的核心目标有三个，后来在多个模拟项目X和某跨平台系统里落地验证，基本都达到了预期。
第一是解决**技能发现（Skill Discovery）**的问题。模型怎么知道当前任务该用哪个技能？我在每个技能的描述里做了标准化的语义索引，不靠函数名猜，而是用“场景描述+输入示例+预期输出”三个维度告诉模型这个技能是干嘛的。这样即使函数名叫exec_odr_proc这种抽象名字，模型也能通过场景描述准确匹配。
第二是解决**技能组合（Skill Composition）**的问题。真实业务里很少有一步搞定的任务，大多数都是多步骤流水线。agent-skills在编排层支持顺序执行、条件分支和并行执行三种组合模式，Agent可以像搭积木一样把多个技能串成一个工作流。
第三是解决**技能治理（Skill Governance）**的问题。技能不是写一次就完事的，要管理版本、灰度、权限、运行日志。我参考了后端微服务的治理思路，给每一个技能加了版本号、注册状态、调用频次限制和审计日志，让技能体系可以像服务一样被统一观测和维护。
2. 技能如何被定义和注册
2.1 一套标准化的技能描述协议
技能定义是整个体系的基石。我在agent-skills里规定，一个技能必须包含以下几个核心字段：
name：技能的唯一标识，建议用领域_动作的命名法，比如order_query、refund_apply，方便日志检索和权限控制。description：给LLM看的语义描述，不能只写“查询订单”，要写成“查询用户订单信息，适用于用户咨询订单状态、物流进度、商品明细等场景，输入订单号或用户ID”。这一步直接影响模型能不能正确选中技能。parameters：JSON Schema格式的参数声明，不只是类型和必填项，还要加上参数的业务含义描述和取值范围。execute：真正的执行函数，接收解析后的参数，返回结构化的结果。on_error：失败时的兜底逻辑，可以返回降级结果，也可以抛出标准错误码。preconditions：可选的前置条件，例如“需要先完成登录鉴权”这类约束。version：技能版本号，升级迭代时用于追踪。
这里最容易被忽略的是description和parameters里的描述信息。我在早期实验里测试过，描述写得模糊时，模型技能选择的准确率在70%左右甚至更低；把描述重写为“场景+输入示例+预期输出”的三段式之后，准确率能直接升到95%以上。这与模型的语义对齐机制有关，大模型的注意力机制更吃自然语言描述，而不是枯燥的参数名。
2.2 注册中心与热插拔机制
技能定义好之后需要一个注册中心来管理，agent-skills里用了一个极简的技能注册表，核心逻辑就是每个技能进来先校验Schema是否合法、执行函数是否可调用、描述是否达标，通过之后放入一个线程安全的字典里，供编排引擎查询。
注册接口我采用装饰器风格，这样对业务代码的侵入性最小：
# 注册一个技能 @skill_center.register( name="order_query", description="查询用户订单信息，适用于用户咨询订单状态、物流进度、商品明细等场景。输入订单号或用户ID。", parameters={ "type": "object", "properties": { "order_id": {"type": "string", "description": "订单编号"}, "user_id": {"type": "string", "description": "用户ID，可选"} }, "required": ["order_id"] }, version="1.2.0" ) def query_order_handler(params): order_id = params["order_id"] return order_service.query(order_id)热插拔机制其实没那么玄乎，本质上是把技能字典做成一个可以被外部配置驱动的集合。我在某跨平台系统的生产环境里，用Redis发布订阅或配置文件变更来触发技能集合的刷新，业务代码运行中动态增删技能而不需要重启进程。要注意的是热插拔的原子性，同一个技能在切换版本时，不能让一个请求读到旧版本、下一个请求读到新版本，操作上我用了一个双缓冲的Map结构先拷贝再替换，保证切换瞬时完成。
3. 技能编排的核心原理
3.1 三步执行闭环：解析→匹配→编排
技能体系真正跑起来的时候，整个执行链路可以拆成三个阶段。
第一阶段是意图解析。Agent收到用户请求后，先由大模型做语义理解，把用户的自然语言转成结构化的技能调用意图，这个阶段会输出一个候选技能列表以及用到的参数。业界常说的“function calling”其实就是这一步，只不过我们要求模型输出标准化意图，而不是自由散漫的JSON。
第二阶段是技能匹配。这里有两种路径，一种是纯靠大模型选择并把参数抽取出来；另一种是先用规则引擎按关键词过滤一遍，再利用向量检索做语义召回，最后让模型在几个候选里精排。我实验下来的结果是：对技能数量超过50个的场景，加一道向量检索前置过滤能明显降低模型的匹配错误率，同时也能减少token消耗。核心原因是大模型面对一个过大的候选集时，注意力会被无关的技能描述稀释，缩小候选范围后更容易决策。
第三阶段是编排执行。拿到技能与参数之后，编排引擎开始按照预先定义好的流程模板执行。这里说的“流程模板”，是写在每个Agent的配置里的，比如“先查订单，再查物流，最后汇总”，或者“如果退款金额大于500，执行人工审核技能，否则自动退款技能”。编排引擎本身不需要理解业务，只需要忠实地按DAG（有向无环图）结构把技能节点串联起来。
3.2 编排的三种常用模式
我在agent-skills的编排引擎里内置了三种执行模式，基本覆盖了日常业务里九成以上的场景：
顺序编排是最简单的，技能A执行完拿结果喂给技能B，比如“查询天气→根据天气推荐穿搭”就是典型链式依赖。实现上我用了一个简单的队列迭代器，每次取一个节点执行，并把输出写入上下文变量池，供下一个节点读取。
条件编排是结合意图参数来路由，比如售后工单里要判断“退款”还是“换货”。实现上支持在节点上配置condition表达式，引擎执行到时评估表达式，为true才继续执行子技能。
并行编排适合做信息收集型任务，比如“同时查询多个平台的库存”，或者“同时拉取订单信息和用户画像”。这里用Python的ThreadPoolExecutor来控制并发度，还要注意结果聚合的时机。并行编排最大的坑是共享状态的线程安全，所以我规定每个技能的输入输出都必须走上下文变量池，不允许在技能内部直接修改全局状态。
这三种模式可以嵌套组合。实际生产里我见过最复杂的流程有17个技能节点，包含了顺序、分支、并行三种模式的嵌套，只要有清晰的DAG定义和日志追踪，调试起来并没有想象中那么恐怖。
4. 技能库的持久化与版本管理
4.1 技能目录结构
技能不应该是只存在于代码里的函数，它应该像一套可以持续积累的“能力仓库”。我在agent-skills里推荐了一套落地的目录结构，基本照搬了后端项目的模块化思路：
skills/ order/ # 按业务域分目录 __init__.py query.py # 技能实现文件 schema.py # 参数Schema定义 version.py # 版本信息 refund/ __init__.py apply.py audit.py common/ # 通用技能 auth.py notify.py registry.json # 注册中心配置，声明哪些技能启用/禁用每个技能独立成文件或目录，好处有三个：一是可以独立写单元测试；二是Code Review时改动范围清晰可见；三是方便后续做成技能市场，按目录打包上传、下载、复用。
4.2 安全与权限边界
Agent的技能体系上线后，安全问题会比普通API调用更突出。因为技能有了编排能力，几个技能组合起来可能产生开发者预想不到的副作用，比如“查询用户信息”加“发送短信通知”组合起来，就可能被恶意循环调用。
我在这块做过三层防护。
第一层是技能级的鉴权，给每一个技能标记需要的权限等级，比如只读、可写、高危险。执行引擎在调用前检查当前会话的权限域，不满足直接拒绝。
第二层是编排级的安全策略，比如限制同一技能在一轮会话中的最大调用次数、限制编排链路的最大深度、对高危险操作强制加人工确认节点。这里设计了一个SafetyPolicy配置对象，里面用阈值来控制。
第三层是参数字段级的脱敏，为了避免Agent在日志里泄露敏感信息，所有技能输入输出都要经过一个脱敏层，电话号码、身份证号这类字段自动打码后再交给大模型处理与日志记录。
5. 从零实现：一个完整的技能编写示例
5.1 技能脚手架代码
说了那么多理论，来一个可以跑的示例。假设我们要为Agent开发一个“库存查询”技能，它需要接收商品编码，返回库存数量与预计补货日期。基于agent-skills的写法如下：
from agent_skills import Skill, SkillContext, register_skill @register_skill( name="inventory_query", description="查询商品实时库存情况，适用于用户询问某商品是否有货、预计发货时间、补货日期等场景。", parameters={ "type": "object", "properties": { "sku_id": {"type": "string", "description": "商品SKU编码，例如SKU-10086"}, "warehouse": {"type": "string", "enum": ["华东", "华南", "华北"], "description": "仓库区域，可选"} }, "required": ["sku_id"] }, version="1.0.0", tags=["inventory", "query"], timeout_seconds=10 ) class InventoryQuerySkill(Skill): def execute(self, ctx: SkillContext): sku_id = ctx.get_param("sku_id") warehouse = ctx.get_param("warehouse", "华东") # 这里对接真实的库存系统，失败时走on_error兜底 try: result = inventory_service.fetch(sku_id, region=warehouse) return { "sku_id": sku_id, "stock": result["available"], "restock_date": result["estimated_restock"], "source_ts": ctx.now() } except InventoryServiceUnavailable: return self.on_error("INVENTORY_SERVICE_DOWN", sku_id=sku_id) def on_error(self, error_code, **kwargs): # 降级策略：返回一个缓存库存值，并标记数据置信度 return { "error_code": error_code, "stock": None, "confidence": 0.3, "message": "库存服务暂时不可用，已返回降级结果" }这里有几个要点值得展开。
description我特意写了业务场景而不只是动作，这是为了让模型能在“商品是否有货”这类自然语言里联想到这个技能。parameters里我给warehouse加了枚举值，这样大模型抽取参数时更不容易编造出不在枚举里的值。timeout_seconds是执行引擎的超时保护，避免一个技能把整个编排卡死。on_error里我返回了一个带confidence字段的降级结果，这样Agent往下编排时就知道当前库存数据可信度低，不能直接对用户承诺发货时间。
5.2 在Agent中加载技能
写好的技能如何注入到Agent的运行时？我提供一个技能加载器，它负责扫描注册中心、构建技能目录、并把技能列表注入到LLM的对话上下文中。
from agent_skills import SkillRuntime, LLMAgent runtime = SkillRuntime() runtime.scan("skills/") # 扫描skills目录下所有技能 runtime.activate_by_tags(["order", "inventory"]) agent = LLMAgent( model="your-llm-model", skill_runtime=runtime, system_prompt="你是一个电商客服助手，请优先选择最合适的技能来回答问题..." )加载完成之后，Agent的每次请求都会先经过技能匹配层，把选中的技能和参数传给LLM做确认，然后进入执行引擎跑编排。这里我建议不要让模型直接输出最终答案，而是先输出“意图JSON”，像这样：
{ "intent": "inventory_query", "params": { "sku_id": "SKU-10086", "warehouse": "华东" } }再让执行引擎驱动技能运行、拿到结果后，由另一段提示词把结果整理成用户友好的自然语言回复。这样做的好处是执行链路和语言生成解耦，技能运行结果可以稳定复用，而不是每次都要大模型重新推理一遍参数怎么填。
6. 实战中踩过的坑与排查思路
6.1 描述不精确导致技能误匹配
第一次上线时，我把一个“订单改地址”的技能描述写成“修改订单信息”。结果用户问“订单里手机号怎么改”时，模型匹配到了这个技能，参数却提取了一堆不存在的字段，执行直接报错。排查时翻日志才发现，问题出在描述里的“订单信息”太宽泛，模型理解成所有订单相关修改都走这里。
修好之后我的经验是：每个技能的description里要主动写清楚“不要用于什么场景”。比如“本技能仅用于修改收货地址，不处理商品信息变更、金额变更、发票修改等需求”。这一句负面清单在形式上像是给模型划了边界，实际测试里显著减少了误匹配。现在我在团队内部的规范里硬性要求，描述必须包含“适用场景”“典型输入”“不要用于”三部分。
6.2 技能执行超时与幂等性
另一个高频坑是外部接口调用超时。返回值还没拿到，LLM已经结束了一轮对话，用户看到的是“该功能暂时不可用”。第一次我以为是模型问题，后来统计日志才发现是技能执行时间超过了对话Session的限制。
解法是我在编排引擎里给每个技能都设了超时阈值，并且把超时分为两类：快速失败型和慢速降级型。快速失败型是接口5秒内没返回就放弃；慢速降级型是如果是物流查询这类本身就慢的接口，则先返回“正在查询”的中间态，异步任务跑完后把结果推送给用户。同时所有技能调用要尽量设计成幂等的，因为超时后重试存在重复扣款、重复发短信这类副作用，我给涉及写入操作的技能加了一个request_id参数，每次都带唯一请求ID，服务端按ID去重。
6.3 参数幻觉问题与校验策略
大模型在参数抽取上偶尔会“一本正经地乱填”，比如商品SKU明明是SKU-10086，模型给抽成SKU-10080。这类参数幻觉很难从模型层面彻底根治，只能从框架层面兜底。
我的兜底策略是三层校验。第一层是Schema校验，用JSON Schema的pattern约束编号格式，不合格直接拒绝执行并要求模型重新抽取。第二层是规则校验，比如数量字段如果是负数直接判非法，这个放在技能内部。第三层是业务侧校验，比如库存查询技能在查询前先拉一份合法SKU列表，做一次存在性校验，不在列表内的直接返回“商品不存在”而不是让下游业务报错。这一套下来，线上参数幻觉导致的事故率基本压到了1%以下。
除了这三类高频问题，还有一个容易忽略的坑是技能编排的日志可观测性。技能链路一旦长起来，出了问题很难定位是第几个节点失败、哪个技能返回了脏数据。我在框架里给每个执行节点都生成了Trace ID，每一步执行都记录输入摘要、输出摘要、耗时、错误信息，排查问题时直接按Trace ID聚合查询。这块投入产出比极高，建议在技能数量超过10个时就尽快补上。
7. 一些优化技巧和经验
7.1 技能拆分的粒度判断标准
什么样的粒度算合理？我总结了一个简单标准：如果一个技能函数的代码超过200行、或者职责描述里出现了“并且”这个词，基本就该拆分了。比如“查询订单并且计算退款金额”——这个技能应该拆成“查询订单”和“计算退款金额”两个技能，由编排引擎决定是先查再算还是并行执行。
粒度拆分太细也有问题，导致Agent在一个普通任务里要串七八个技能，每个技能的参数抽取都会引入误差，链路一长累计误差就高。所以我的建议是：技能尽量按“业务交付物”来切分，比如“售后处理完成”是一个交付物，“生成售后总结报告”是另一个交付物，而不是按底层函数来切。以交付物为边界，Agent只关心“这件事做完没有”，而不是纠结“这件事分几步做”。
7.2 技能执行的观测与日志
技能体系上线后，线上问题排查全靠日志。我的日志规范是：每个技能执行结束，输出一行结构化日志，包含技能名、版本、耗时、入参摘要、出参摘要、错误码、Trace ID。然后把这些日志汇总到统一的可观测平台里，按技能维度看调用量、成功率、P95耗时，哪个技能劣化了第一时间能发现。
关于出参摘要我要多说一句，千万别在日志里打完整响应体，一是敏感信息容易泄露，二是日志量会爆炸。固定采样5%或者只记关键字段就够排查问题用了。
7.3 技能市场与团队共享
技能做到后面，越来越像内部的开源生态。我把验证过的技能打包成独立的Python包，上传到内部的制品仓库，其他团队通过一行配置就能拉取使用。比如我做过的“通用鉴权技能”，一开始只是给自己这个项目写的，后来被隔壁几个团队都拿去复用了。
这里有一个经验：技能作为共享包发布时，需要额外加一层API兼容性测试。你改了自己的技能内部实现不要紧，但如果改了入参Schema，所有下游Agent可能都会挂。我的策略是发布技能时执行一次契约测试，凡是外部依赖此技能的消费方都会被跑一遍回归用例，通过后才允许发布新版本。这一步虽然初期有点重，但在技能数量膨胀到几十个之后，它就是维持整个生态不崩的底线。
最后再分享一个个人体会，agent-skills这套思路，本质上是用工程化的方式弥补大模型在长链路工具调用上的不确定性。它没办法让模型变得“更聪明”，但可以让每一个技能调用都更可控、更可追踪、更可复用。如果你正在做Agent，且已经遇到了工具一多就失控的问题，不妨从定义第一个标准技能开始，慢慢把能力沉淀成体系，后面你会发现Agent的稳定性、可维护性和团队协作效率都会上一个台阶。
