从今年年初开始我一直在做 Agent 方向的应用前前后后调过不少框架也踩过很多坑。最近把项目沉淀下来想着把关于agent-skills这块的心得整理出来,正好可以给正在做类似事情的同行一些参考。很多人提到 Agent 就想到大模型但真正做过项目就会明白真正决定 Agent 能不能落地的恰恰是“技能”Skills这一层。模型的聪明程度决定上限而技能系统的设计水平决定下限。模型再强没有扎实的技能编排Agent 做出来的事也是飘的。这篇文章我会从技能体系的整体设计、技能定义与注册、执行链路、评测迭代、以及实际踩过的坑这几个方面展开。全程用实际项目经验说话不整虚的。1. Agent 技能体系的核心设计思路1.1 为什么要单独做一层“技能”而不是直接调工具我刚开始做 Agent 的时候思路很直接给模型一堆函数让它按需调用。但试过之后就发现这条路在真实业务里走不通。函数调用Function Calling本质上还停留在“让模型决定用哪个工具”的层面工具之间没有逻辑关系模型每次要做完整的推理决策既不稳定也不可控。技能Skill和工具Tool之间的区别我习惯这样解释工具是原子操作技能是带业务逻辑的动作序列。比如“查天气”是一个工具但“根据用户最近的出行安排决定是否需要带伞提醒”就是一个技能。技能内部可以组合多个工具调用也可以包含规则判断、条件分支、状态维护。另外技能是面向复用和共享的。一个工具只能做一件事但一个技能可以沉淀团队的业务经验比如“订单催付”“库存预警”“客户情绪安抚”这类高频场景一旦固化成技能后面的项目直接复用就行。这也是为什么我们在项目里单独做了一层agent-skills而不是让每个 Agent 都从零开始配工具。1.2 技能系统需要解决的三个核心问题设计技能层的时候我给自己定了三个必须解决的问题后续所有架构决策都是围绕这三点展开的第一个是标准化。技能的定义格式、入参出参约定、错误码规范、日志格式必须全项目统一。没有标准化的技能定义后面做编排和评测都会一团糟。我们早期就是吃了这个亏每个技能风格不一导致评估脚本只能针对性地写复用性极差。第二个是可编排性。技能不能是孤立的必须有清晰的组合能力。我这边参考了类似工作流引擎的思路把技能的执行抽成 DAG 节点让技能之间可以顺序执行、条件跳转、并行调度。这个设计在后面处理复杂场景的时候发挥了很大作用。第三个是可观测性。Agent 的技能调用链路过长出问题的时候如果日志不清楚排查基本靠猜。所以每个技能从入参校验开始到内部每一步工具的调用耗时、输入输出摘要、异常分支全部都要留痕。1.3 技术选型微服务 vs 函数库技能层到底做成独立的微服务还是做成一个函数库嵌入到 Agent 主进程里这问题我纠结了很久最后是根据项目体量做了取舍。如果 Agent 的类型单一、调用量也不大做成函数库是最省事的。直接把技能函数注册到 Agent 的运行上下文里调用路径短、延迟低、调试也方便。我早期很多原型都是这么干的。但当项目演进出多个 Agent、不同场景复用同一批技能时函数库的耦合问题就会暴露出来。每次更新技能都要重新发布 Agent 服务而且技能状态没法单独管理出了问题也不容易隔离。我最终的选择是核心技能独立成一个轻量服务通过内部 RPC 调用同时保留一个本地函数注册表做热插拔。这样既保证了核心技能的统一管理又允许特定 Agent 在本地挂载自己独有的技能函数两边不矛盾。2. 技能定义与注册机制2.1 技能定义文件的结构设计技能定义是整个体系的基石这层如果设计得不好后面全都要返工。我在项目里用 YAML 做技能定义文件每个技能一个目录包含SKILL.md和可选的reference资源。核心字段如下name: order_reminder description: 基于用户的订单状态生成催付提醒 version: 1.2.0 author: agent-platform depends_on: - order_query - message_push input: - name: order_id type: string required: true description: 订单编号 - name: customer_id type: string required: false description: 客户编号不传时自动从订单信息中提取 output: - name: reminder_text type: string description: 生成的催付提醒文案 - name: push_required type: boolean description: 是否需要推送 execution: timeout_ms: 3000 retry_times: 2 fallback: order_reminder_fallback关于这个定义文件多说几句我实践后的体会。描述字段至关重要。description不只是给人看的更是给模型看的。在 Agent 决策场景下模型需要靠技能的描述来决定该调用哪个技能。如果描述写得模糊比如“处理订单”模型可能根本不知道该在什么时候用。我后面把描述统一成“动词 使用场景 不下手条件”的格式明显准确率提升了不少。入参配置要有严格的 schema。我在项目里对接过很多技术方案凡是入参定义松散的系统最后大概率会在执行期出各种类型错误。最好是直接把 JSON Schema 嵌入定义让校验器在调用入口统一把关不要把脏数据带到技能内部。2.2 技能注册中心与动态加载技能定义文件写好之后需要注册到运行环境里。我这边实现了一个轻量的注册中心支持两种方式一种是启动时扫描服务启动后遍历技能目录解析所有 YAML 定义校验通过后加载进内存。这个方式简单直接适合技能数量不大、变更不频繁的场景。另一种是运行时注册通过管理接口动态新增或下线技能适合灰度发布和热更新的需求。比如某个技能出了线上问题我可以通过接口直接把它下线而不需要重新部署整个服务。动态加载的实际实现中最麻烦的是依赖管理。技能之间是有依赖关系的比如order_reminder依赖order_query。如果直接下线order_query所有依赖它的技能都会挂掉。我的解决办法是做一个依赖关系图每次注册或下线之前先做一次依赖检测有被引用的情况下给出明确警告。2.3 技能注册的核心链路在项目里的实际注册流程我梳理成了五步每一步都有校验缺一不可第一步解析定义文件。把所有字段读出来转换成内部的技能对象模型。这一步如果定义文件里数据结构和预期不符会直接抛错。第二步校验引用依赖。检查depends_on声明的依赖技能是否已经注册没有注册的直接拒绝。这里要强调一下依赖只允许向上引用不能形成循环依赖否则执行的时候会死循环。第三步加载执行代码。技能的底层执行逻辑是写好的函数通过名字映射到注册表里。这一步需要按技能的语言类型加载对应的运行时比如 Python 技能就拉起一个 Python 子解释器。第四步注册回调与事件钩子。有些技能需要在特定事件触发时执行比如订单状态变更后自动触发一个技能这些需要注册订阅关系。第五步沙箱鉴权。技能执行时涉及的权限范围应该在注册时就确定下来比如它能不能读数据库、能不能调用外部 HTTP 接口。提前声明好权限边界后面执行的时候就不用每次问了。这五步走完一个技能才算真正进入可用状态。我这里还专门做了一个注册仪表盘可以查看所有技能的注册状态、依赖关系和版本号方便巡检。3. 技能编排与执行链路3.1 从“模型决策”到“技能编排”技能层像积木一样搭好之后下一个问题就是怎么让 Agent 灵活使用这些积木而不是每次从头开始搭。我的经验是明确两条路径一条是显式编排路径。针对那些流程相对稳定的业务场景比如常规的“咨询-下单-支付-售后”流程直接在编排层把技能执行顺序和工作流画好Agent 只需要按流程执行例外情况再交给模型处理。这种方式的优点是可控性强、效率高、延迟稳定。另一条是隐式推理路径。针对开放式的用户请求模型需要自己判断用哪些技能、什么顺序、什么参数。这时候技能描述质量、入参示例质量、以及模型能力会直接影响效果。实际项目中我们大多数时候是两者结合显式流程兜底隐式推理处理边界。技能编排层对外暴露一个统一执行接口内部既支持预定义流程也支持模型动态生成的技能调用序列。3.2 技能执行的 DAG 调度设计复杂业务场景下技能之间存在依赖关系可能是线性的也可能是并行的。我直接用的是 DAG 调度模型每个技能是一个节点节点之间用有向边表示依赖关系。这里的核心工作是调度器。调度器拿到一串待执行的技能列表后会先做一次拓扑排序找出哪些技能可以并行执行哪些必须等前置任务完成。比如在“订单全链路追踪”这个技能里“查订单信息”和“查物流信息”是可以并行跑的两个子技能而“生成状态摘要”必须等两者都完成后再执行。DAG 调度的好处是能极大压缩整体执行时间。串行可能需要 5 秒的流程并行优化后可能只要 2 秒。对于用户感知明显的场景这个优化对体验提升非常有帮助。我在实现调度器的时候还加了一个“超时熔断”机制。某个技能执行如果明显超时调度器会判断是否可以降级或跳过不会因为一个技能的阻塞拖垮整个流程。3.3 技能上下文的传递与管理技能和技能之间不是孤立的前一个技能的输出往往是后一个技能的输入。这就涉及上下文传递问题。最简单的做法是共享一个全局上下文对象所有技能读写同一个对象。但这里有个坑Agent 会话中往往有多个执行分支如果所有技能共享同一个上下文很容易出现参数覆盖和污染。我在项目里的做法是每个执行批次都独立维护一个上下文容器技能只能读取自己声明依赖的字段也只能写入自己声明的输出字段形成一种“变量作用域”的隔离方案。虽然执行框架代码量多了不少但对调试和数据安全的帮助非常明显。另外上下文中还应该记录一些元信息比如技能执行开始时间、耗时、从哪个技能转过来。这些对后面的排查和链路追踪来说价值很高。3.4 技能执行日志与链路追踪我在做技能编排时最重视的部分就是日志与链路追踪。Agent 场景下的日志和传统后端日志有一个很大的区别它需要按“一次任务”来组织。用户发一条消息Agent 内部可能调用 5 个技能、20 次工具调用这些日志如果分散在不同文件里排查的时候根本没法看。我的做法是引入了 traceId。一次 Agent 任务生成一个全局唯一的 traceId所有技能执行日志都带上这个 traceId最终可以通过 traceId 检索出完整链路的执行明细。具体留痕信息包括每个技能的开始与结束时间戳、入参出参摘要、内部工具耗时、异常堆栈、重试次数。可视化之后就像一张时间轴哪个环节慢、哪个环节出错一眼就能看出来。这套机制帮我在线上排查时节省了大量时间。4. 技能评测与迭代优化4.1 技能质量怎么量化技能写得好不好不能只靠感觉得有可量化的指标。我在项目里重点看这几个维度成功率技能底层调用的工具接口的成功率。这个指标低的话说明要么接口本身不稳定要么技能传参经常出问题。端到端质量这一步通常需要人工标注。我会积累一批典型测试用例用 Agent 跑一遍然后人工判断结果是否符合预期。比如生成回复是否自然、决策是否合理、是否准确调用了预期技能。执行耗时技能整体的耗时。这里要注意耗时不只看单次执行还要看 P50、P95、P99 这些分位数。有些正常工作流程里的技能偶尔被大任务拖慢只看平均值容易掩盖问题。兜底率技能内部发生异常时触发兜底逻辑的比例。兜底率高说明这个技能的不确定性偏高需要重点优化。4.2 评测集的建设与维护评测集和单元测试类似是迭代优化的锚点。没有评测集优化就没有方向感很容易出现按下葫芦浮起瓢的情况。我建议评测集按场景分类。比如电商场景的 Agent可以分成“售前咨询”“订单处理”“售后维权”三大类每类下面再细分具体用例。每个用例要有明确的期望结果标准比如“用户催发货时Agent 必须调用订单查询技能后再回复”这类断言越具体越好。评测集要常来常新。每次线上出现问题复盘之后确认是 Agent 行为不当导致的就把这个 case 加入评测集避免后续回归。4.3 技能迭代的流程实践技能迭代方面我踩过最大的坑就是“直接改线上技能定义”。改完线上就生效出了问题连回滚都做不到。现在的流程规范了很多先修改技能定义文件的版本号从 1.2.0 升级到 1.3.0并且补上变更说明。然后在测试环境跑一遍评测集看成功率与质量指标有没有下降。如果通过再灰度到线上先放 5% 的流量观察一段时间确认稳定后逐步放量。保留上一版本定义方便随时回滚。这套流程的执行成本不高但带来的安全感提升很大。特别是线上流量大的时候一套稳妥的发布流程比什么都重要。5. 常见问题与排查技巧实录5.1 入参缺失或不匹配这是技能调用中最常见的问题模型生成的参数和技能定义中的 schema 不匹配。我这边总结了两层防线第一层严格校验。所有技能入口统一走参数校验必填参数缺失直接拒绝执行并返回清晰的错误码不带着缺参往下走。第二层模型侧的兜底。在模型调用技能前提示词里把常用技能的入参示例写清楚。实测这样能让模型生成的参数准确性提升不少。如果校验失败频率仍然较高我会检查技能描述中的入参描述是否清晰过于笼统的描述是主要原因。5.2 技能执行超时技能超时通常会直接影响用户的交互体验。常见的原因是内部调用的下游接口响应太慢或者技能内部处理了大 payload 的数据。我的处理思路有三个方向给每个技能设置合理的超时阈值超过阈值即熔断返回兜底结果。引入降级策略核心链路依赖的关键技能异常时用预设话术兜底。异步化处理那些不依赖实时结果的技能放到后台队列里不会阻塞主流程。这里提醒一句超时阈值不要设得太死要结合技能内部的真实耗时分布来设置设太短容易误伤正常请求设太长又形同虚设。5.3 技能冲突与重复调用模型在动态决策的场景下有时候会重复调用同一个技能或者调用两个职责重叠的技能造成资源浪费和结果冲突。我的做法是控制策略在决策层增加“已调用技能”的记录模型再做决策时把已执行技能作为上下文信息传入避免反复做无用功。对职责重叠的技能做约束比如“老客找回”和“流失预警”在设计上就明确适用条件让模型不容易混淆。5.4 技能编排死循环理论上 DAG 拓扑排序能避免纯循环图但一旦编排过程中出错比如某个节点把下游节点重新加入队列甚至造成互相等待排查起来很头疼。我的做法是给编排引擎设置全局执行步数上限默认 20 步。一旦超过直接终止编排并返回错误。同时在关键流程里对每个技能的调用次数设置配额任何单一技能在一个任务内不会被调用超过 3 次。5.5 上下文污染我前文反复强调上下文隔离原因是在实际项目里吃过亏。某个技能把中间变量写到了公共上下文的一个通用字段里导致后续另一个技能读到了错误的数据最后生成了完全偏离用户期望的回答。排查这类问题的关键就是链路追踪。每次技能读取和写入上下文字段都要记日志回放一条 trace 就能看到哪个环节写脏了数据。修复方法是严格执行变量作用域规则不允许跨权限读写。初始版本为了省事用了公共上下文后期专门花了时间改造成了分作用域的结构。如果你的技能编排刚开始设计建议一步到位。5.6 技能版本混乱当技能数量上升到一定规模以后版本管理就容易混乱。线上跑的是哪个版本、某个技能有没有新版本上线、改动内容是什么没有台账根本说不清。我的建议是技能版本号遵循语义化规范同时把版本信息写入注册中心并支持按版本号精准查询。每次发布技能无论在测试还是线上环境都要在变更记录里写明改动内容与验证结果。临时改技能没记录这种坑我踩过不止一次现在坚决要求所有变更留痕。6. 技能系统的扩展方向这套agent-skills体系目前已经能支撑大部分业务场景但只要摸过这层的人都会意识到它还能往更多方向走。跨项目共享沉淀把技能按领域分类沉淀成通用的技能库以后新项目直接服用成熟技能省去从零摸索的成本。我这边已经整理出了订单类、营销类、客服类三个方向的技能包复用率相当可观。技能自学习优化目前的技能大多还是固定策略下一步可以考虑让技能在每次执行后根据结果反馈自动调整一些参数。比如催付文案的风格对沉默用户和活跃用户应该有所不同这个可以通过数据分析自动优化。多语言运行时支持现在技能底层主要以某一种语言实现但实际场景里很多团队的技能代码是异构的。后续计划完善统一执行协议让不同语言的技能能在同一套编排框架下共同工作。无论往哪个方向扩展底层原则都不会变标准化定义、严格校验、可观测留痕、可回滚发布。把这四点守住技能层就能成为整个 Agent 系统稳定前进的地基。从我个人体会来说Agent 项目里最容易出成绩的往往不是调模型而是把技能层做扎实。模型的能力是通用的但对业务的理解、对场景的拆解、对执行细节的掌控才是项目真正拉开差距的地方。希望这篇文章能给正在搭建 Agent 技能体系的你一些参考。