从零搭建智能体技能库：稳定复用与落地实践

这两年做智能体应用我有一个越来越强烈的感受模型的能力边界已经不是最大瓶颈真正决定一个智能体能不能在业务里站稳脚跟的是它有没有一套成熟、可复用、能落地的技能体系。最早我以为把几个外部 API 接进来、再写一段提示词让模型自己发挥就完事了结果在真实场景里被反复教做人——同样的任务今天能跑通明天就绕远路参数一换就报错运营同事直接来一句这东西到底能不能稳定用。后来我做了 agent-skills 这个项目核心就一句话把智能体完成特定任务的方法沉淀成技能让模型从每次现场发挥变成按需调用成熟方案。这篇文章就把我在设计、实现和落地这套技能系统过程中的完整思路、踩过的坑、以及一些实测有效的经验写出来希望给正在做智能体应用的朋友一些参考。1. 项目背景从零散工具调用到技能体系1.1 智能体应用的核心痛点不稳定与不可复用先说说我为什么要从零搭技能这套东西。之前团队做某跨平台智能助手项目接了不少工具有订单查询的、有内容检索的、有格式化报表的。最初走的是 function calling 大段提示词的路线给模型一张工具清单告诉它你可以调用这些能力自己决定怎么用。demo 阶段效果还行一放到线上就暴露问题。第一个痛点是链路不稳定。模型在长对话里编排工具调用经常出现绕路、重复调用、参数拼错的情况。同一个查询订单异常的需求有时候模型只调一次接口就给出结论有时候会反复查同样内容甚至先查订单再查用户再查商品最后绕回订单一条链路活生生多出好几倍 Token 消耗。高层看的是成本业务看的是响应速度两边都不满意。第二个痛点是经验无法沉淀。今天发现有 20% 的请求会卡在某个工具的参数格式上我修了提示词系统能好一阵明天换个任务类型又得重新发现、重新修。团队里不同人做的工具调用逻辑互相不共享同一个数据清洗动作A 项目写一遍B 项目又写一遍。说句实话这种状态跟智能根本不沾边就是堆砌。第三个痛点是验证缺失。模型调完一个工具返回结果到底对不对原来完全靠模型自己感觉。它觉得没问题就往下走可很多时候数据根本没查到、校验没通过模型还一本正经地生成答案。这种自信的错误比报错更麻烦因为你很难第一时间发现。1.2 agent-skills 的解题思路把能力变成经验资产agent-skills 的出发点就是不再把工具调用当成模型的即兴行为而是把这些行为沉淀成一套标准化的技能库。每个技能封装了一类任务的完整解法什么时候触发、按什么步骤执行、调用哪些工具、每一步怎么校验、失败之后怎么兜底。模型在运行时只需要负责路由决策——判断当前请求最匹配哪个技能剩下的事情交给技能执行引擎按流程跑。这个思路的一个直观类比是一个成熟的公司不会让每个新员工都从零发明工作流程而是有一套标准作业程序老员工按流程执行、遇到异常走预案。智能体也一样技能库就是它的标准作业程序库比每次靠大模型现场发挥可靠得多。实际改造成果也在数据上得到了验证。某模拟项目里接入技能库之后高频场景的 Token 消耗大概降了 30%端到端响应时间缩短了接近一半工具调用的平均次数从 4 次以上降到了 2 次左右。更重要的是业务的完成率从听天由命变成了可监控、可优化的指标。这套系统也让新场景开发周期明显缩短——新需求来了先查技能库有没有能复用的没有才新写写完了注册进去后续都能用。2. 系统设计技能模型与分层架构2.1 核心抽象一个技能到底是什么很多朋友听到技能两个字第一反应以为是提示词模板或者是给模型用的函数列表。其实在 agent-skills 里一个技能是一份完整、自包含的可执行经验链它至少包含四个部分。技能元信息负责让上层系统理解什么时候该用我。包括技能名、版本号、功能描述、适用场景、标签、权限要求、输入输出 schema。这块内容看起来像配置其实非常关键尤其是描述字段我后面会单独展开讲。技能逻辑负责定义具体怎么做。它是一套编排好的执行步骤可以是面向模型的指令流也可以是确定性的流程脚本包含顺序步骤、条件分支、循环、超时控制。这一层决定了技能执行的可预期性。工具绑定负责把系统能力接进来。技能运行过程中需要调用的外部能力都挂在绑定层检索接口、存储读写、第三方服务 API、内部函数通通可以作为工具被技能引用。工具层和技能逻辑层分离使得同一个工具可以被多个技能复用同一个技能也可以在不同环境里绑定不同的工具实现。校验与兜底负责回答怎么算成了、失败了怎么办。每个步骤之后都可以定义结果校验逻辑满足条件才继续往下走失败时有重试、降级、人工接管等预案。这一层是技能和普通脚本最大的区别也是稳定性的来源。这里补充一个经常被混淆的点技能不等于 function calling。function calling 是给模型一张工具清单让模型自己决定调用哪个、怎么拼参数、怎么处理返回本质是单次决策。技能是一套已经编排好的流程工具只是流程中的一环模型在流程里更多是做判断题而不是做应用题。实际工程里两者可以配合先用技能兜住高频复杂场景再给模型留出 function calling 空间处理低频开放场景。2.2 技能库分层核心层、业务层与扩展层技能数量少的时候怎么放都行但一旦过了几十个一股脑塞进一个目录就会失控。我在项目里把技能库分成三层每一层的定位和治理方式完全不同。核心层放着与具体业务无关的通用能力比如网页正文提取、JSON 数据清洗、时间格式解析、编码转换、通用去重。这层技能讲究高度稳定任何改动都要走完整回归因为不确定哪个上层业务正在依赖它们。核心层的血泪教训是宁可少而精不要多而杂什么都能做的通用技能最后往往什么场景都接不住。业务层跟具体业务域绑定比如订单状态查询、库存核算、对账单生成、工单分类。这层按业务模块继续划分子目录目录之间不允许直接互相调用避免出现订单技能改了导致库存技能挂了这种幽灵依赖。业务层的技能允许根据业务变化调整但每次变更要记录版本线上默认走稳定版本。扩展层用来放实验性、临时性或外部贡献的技能。这一层允许快速试错跑通了再升级到业务层跑不通直接删掉。扩展层的存在很重要因为它给团队一个低门槛的提交技能的入口——没有这一层大家会把半成品塞进业务层然后整个技能库的质量就被拉下来了。2.3 技能注册与发现机制让模型看得懂技能技能入库时有几个动作必不可少写清元信息、定义输入输出 schema、写高质量描述。元信息里的 name 和 version 好理解我要特别强调 description 的写法。技能描述不是给文档读者看的是给模型路由用的。模型在意图识别阶段靠 description 判断技能是否匹配所以描述要写成行为 场景 触发条件而不是功能说明。举个我踩过坑的例子。早期一个订单异常处理的技能描述写的是提供订单异常情况下的处理流程。结果线上很多用户反馈我东西一直没收到这种请求模型完全没想起来调它绕了好几个弯子最后答非所问。后来把描述改成了当用户反馈订单未发货、物流停滞、包裹丢失、金额不符时调用该技能查询订单日志并定位异常环节命中率立刻上来了。描述是给模型用的路标不是给人看的说明书。输入输出 schema 的作用是让技能执行引擎和路由层理解参数结构。schema 定义得越清楚参数填充越稳定。尤其是 nullable、枚举值、格式约束这些能减少大量的运行时参数校验错误。3. 核心实现技能定义、调度与执行细节3.1 技能文件的标准结构一个实例拆解技能在项目里以文件形式存在我用 YAML 加步骤定义来写。选 YAML 而不是纯代码是因为技能文件需要被非开发角色审查和参与维护可读性很重要。下面是一个简化但完整的示例对应订单异常解析这个技能。--- name: order_exception_resolver description: 当用户反馈订单未发货、物流停滞、包裹丢失、金额不符时查询订单日志并定位异常环节 version: 1.2.0 tags: [订单, 售后, 日志分析] permission: order:read input_schema: order_id: type: string required: true customer_complaint: type: string required: false output_schema: exception_chain: type: string suggested_action: type: string --- steps: - call: order_log_query args: order_id: ${order_id} check: condition: result.status success on_failed: retry(max2) - call: redis_cache_get args: key: order:{order_id}:exception - if: condition: exception_type timeout then: notify_customer_service - else: escalate_to_supervisor这个文件看起来简单里面藏了几个我在实战中总结的关键点。${order_id}这种变量引用是参数填充机制执行引擎会从用户请求或者上游步骤的输出里提取值填进工具调用的参数里。这里的核心原则是技能里不允许出现魔法值所有运行时数据都必须通过参数传递否则同一个技能换个场景就没法复用。check字段是步骤的守门员。每一步执行完都要校验结果满足条件才继续。比如order_log_query返回失败时走retry(max2)重试两次还不行就进入兜底逻辑。校验机制把模型觉得没问题变成了系统确认没问题这一步直接消灭了绝大部分自信的错误。if / else分支是业务流程落地的地方。异常类型是超时就走客服通知其他情况走升级负责人。技能里写清楚业务分支模型就不需要在运行时自己发挥。这里要说一句分支不要写太复杂超过三层的嵌套会显著增加维护难度真到那时候就该拆技能了。3.2 语义路由与混合调度模型怎么找到对的技能技能库建好之后下一个核心问题是来了一个用户请求系统怎么知道该用哪个技能。我在项目里试过三种路由方式最终用的是混合方案。第一种是纯规则路由通过关键词、正则、业务标签直接命中技能。优点是快、可控、零成本适合低频但触发特征明显的场景。缺点是死板用户换个说法就漏了。我在早期技能少的时候用这个方案大概七八十个技能以内还能扛。第二种是语义路由。把每个技能的 description 向量化收到用户请求时也向量化先检索出 top-k 候选技能再交给模型做精排选择。优点是召回率高对用户的各种说法都很宽容缺点是引入向量检索组件而且候选技能之间的描述如果区分度不够模型容易左右横跳。第三种是混合路由也是我最终采用的方案先跑一组轻量规则做粗筛命中规则就直接定规则没命中的进入语义检索加模型精排。大部分高频场景被规则接住了低频和模糊场景交给语义层兜底。这样既保证高频请求的低延迟又保证长尾请求的召回率。路由层还有一个细节容易被忽略路由日志。每一次请求到技能的映射结果、置信度、最终是否执行成功都要落日志。没有路由日志你根本不知道一个技能长期不被调用是因为用户没这需求还是描述写得差导致模型没识别出来。这个数据是做技能运营的基础。3.3 执行引擎与幂等设计兜住整个技能运行执行引擎是技能的运行时它负责解释步骤文件、调度工具、填充参数、执行校验和触发兜底。这里我不展开讲代码实现重点讲两个工程上最容易出问题的点。第一是并行执行的控制。技能步骤定义里可以声明 parallel 块让多个工具调用并发跑缩短整体耗时。但并行是有代价的如果两个步骤之间有隐式依赖一个工具的返回要作为另一个的输入那就不能并行。还有个更隐蔽的问题是并发调用不是幂等操作时会出现重复扣款、重复发通知这种线上事故。我遇到过并行调两个标记已处理接口响应顺序一乱状态直接覆盖错了。现在我的原则是除非能明确证明两个调用互不影响否则一律串行。第二是重试与幂等。技能执行失败会触发重试可重试有个前提被调用的工具操作本身是幂等的。所谓幂等就是同一个操作执行一次和执行一百次最终结果一样。比如把订单状态更新为已完成重复执行不会产生新的副作用这就是幂等而给用户发送一条到货通知重复执行就会造成骚扰不幂等。对付不幂等的操作我会加一个操作幂等键每次技能运行生成一个 request_id调用这类工具时带上这个 id服务端记录已处理过的 id重复请求直接返回第一次的结果。这一条建议所有做智能体落地的人都认真对待在线业务里重试机制遇到不幂等的工具迟早要出大事。3.4 技能热加载与版本管理不改代码也能更新技能技能库如果每次改一个技能都要发版重启那根本没法在日常迭代里用起来。我采用的方案是热加载技能文件放到一个独立的存储目录执行引擎启动时加载全部技能到内存平时通过文件变更事件触发增量更新。这样新增技能、修复描述、调整步骤都只有秒级的生效延迟。版本管理上每个技能带 version 字段同一技能可以同时存在多个版本并存。线上默认路由到某个稳定版本同时可以配置一小部分流量到新版本做 A/B 验证。等新版本跑稳了再把默认流量切过去。这里要提醒一点技能变更不要直接改线上版本一定要走新版本 灰度 切流的流程。我自己有过一次教训觉得只是改了一段描述直接改了原版本结果新描述在某个长尾场景里触发了一批错误分支线上收到一堆投诉。4. 实操过程在一个模拟项目中落地技能库4.1 场景盘点与技能选题不凭空造技能很多朋友一上来就问技能应该怎么设计我的回答是先从真实数据里找别坐在工位上拍脑袋。拿我们某模拟智能客服项目举例第一批技能就完全来自过去一个月的工单记录。我把历史工单按问题类型做了聚合发现三成以上的请求集中在查订单状态、核对金额明细、重发通知这三个动作上。这三个动作就是最佳的第一批技能候选。为什么因为它满足技能选题的三条标准频率高、路径清晰、结果可验证。频率高投入产出比才够路径清晰写成技能才不会模糊结果可验证才能靠校验保证质量。如果一个任务本身千人千面、没有标准答案那它不适合技能化留给模型自由发挥更合适。4.2 最小技能原型到完整闭环先跑通再完善技能写起来我推荐最小可用策略。拿查订单状态来说第一版技能只做一件事传入订单号调用订单查询接口把结果格式化返回。不要一开始就加各种分支、校验、缓存那些在原型阶段全是累赘。原型跑通之后再逐步加校验和兜底。比如发现接口偶尔超时就加一个重试策略发现有部分订单查不到就加一个兜底路径让技能返回订单不存在或权限不足的明确结果而不是让模型硬编一个答案。每加一层能力都要回到真实用例集上验证一遍不要凭感觉扩展。这个先跑通、再加固、后扩展的节奏比一开始就追求完整的技能文件高效得多也能避免把简单问题复杂化。4.3 路由接入与评测对照用数据说话技能写好接入路由层之后要立即建立评测闭环。我的做法是准备一批留出的历史真实请求至少一两百条覆盖高频和长尾场景。然后跑两套系统对比一套是没有技能库的纯 function calling 方案另一套是带技能库的 agent-skills 方案。下面是我们某模拟项目里的评测结果数据已经脱敏趋势是真实的。评测指标无技能库方案agent-skills 方案任务完成率62%88%平均工具调用次数4.32.1平均单次任务耗时8.6 秒4.2 秒平均 Token 消耗基准约为基准的 68%从结果能明显看到技能化之后完成率、耗时、成本都有显著改善。但我要强调的是这些数字不是一次性拿到的中间经历了好几轮技能描述调整和兜底逻辑补全。评测的价值不是给你一个好看的数字而是让你知道每次改动到底是变好了还是变差了。4.4 技能运营的长期机制建库只是开始技能库上线只是起点真正的功夫在运营。我给自己定了一个节奏每周看一次技能命中率、成功率、平均轮次、未命中原因分析。那些长期不命中的技能要么是描述写得有问题导致模型找不到它要么是场景本身不存在了。成功率低的技能要分清是路由问题还是技能本身问题。路由问题是指模型该选这个技能却没选大概率是 description 的表述和用户真实表达差异太大技能本身问题是指选对了但执行容易失败那就需要看步骤里的校验逻辑和工具稳定性。这两个方向的处理方式完全不同所以排查第一步就是先定位问题在路由层还是执行层。技能库里还会不断沉淀出冗余技能。一开始我总觉得技能多多益善后来发现描述相似的技能会让路由层抓狂。处理办法是定期做技能合并两个技能覆盖的场景高度重叠就保留一个另一个作为别名和跳转保留避免线上还在引用旧的技能 id。现在技能库稳定维持在两百多个左右每个技能都有明确的独特定位。5. 常见问题与排查技巧实录5.1 模型就是不选我准备好的技能怎么办这个问题我至少被问过二十次。先别急着怪模型按顺序排查三步。第一步检查 description 是否见名知意。描述有没有写出行为、场景和触发条件如果只是提供XX功能这种说明文模型识别不到是很正常的。我一般要求描述能让一个完全不了解项目的人看完就知道什么情况用我。第二步检查路由层的召回。如果是语义路由看看用户请求和技能描述向量化之后的相似度排名该技能是否进了 top-k。没进去说明描述用词和用户表达偏差大进去了但最终没选中可能是候选技能之间区分度不够。第三步某些关键场景可以直接用规则绑定。比如用户明确说我要退货不管模型怎么想规则层直接指向退货流程技能。规则路由的存在不是为了替代模型而是在确定性的地方省掉不确定性。5.2 技能执行到一半失败了如何设计兜底技能执行失败分两类一是某一步工具调用报错二是校验点发现结果不对。应对思路有三层。第一层重试瞬时故障比如网络超时、限流可以重试一两次。但重试必须满足幂等前提或者带上幂等键否则会制造更多麻烦。第二层降级主路径挂了走备用路径。比如订单查询服务不可用时降级到读本地缓存副本虽然数据可能不是最新但至少能给用户一个可用答复。第三层人工接管系统兜不住的时候把请求标记为需人工处理转给运营后台。这里的原则是宁可承认搞不定也不能让模型硬编一个看起来合理但不正确的答案。技能文件里要把兜底逻辑写清楚不要等运行的时候让模型临场想那又回到自由发挥的老路上了。5.3 技能之间边界模糊、互相冲突怎么排查技能多了之后很容易出现两个技能描述覆盖相似的场景。典型现象是模型在路由层左右横跳同一个用户请求今天走技能 A 明天走技能 B结果还都能给出答案只是路径不同。排查办法是先拉路由日志看该用户请求在候选列表里到底出现了哪些技能、各自是什么分数。如果技能 A 和技能 B 的分数非常接近说明边界确实重叠需要做技能合并。合并的原则是保留下沉场景更具体的技能另一个改为跳转别名。还有一种情况是技能本身覆盖范围太宽我建议把宽技能拆成窄技能 父级调度父级技能负责判断子任务应该分发到哪个子技能这样路由层更清晰。5.4 最常犯的设计错误把抽象当目标最后分享一个我在技能设计上绕了最久弯路的心得。最早我特别喜欢把技能做得通用恨不得所有技能都参数化、配置化幻想一个技能能应对几十种变化。结果就是技能文件越来越复杂维护成本爆炸而且模型在路由的时候根本分不清哪个变体适合当下场景。后来我意识到技能抽象要绑定用户价值场景而不是绑定代码复用意图。代码层面的抽象应该靠函数和模块去解决技能层面必须落到具体的业务场景上。一个技能就对应一类用户问题和一套稳定解法这是技能库能够持续健康迭代的底层逻辑。这个认知调整之后技能的设计、运营、路由都顺畅了很多不再为了优雅牺牲可维护性。另外还有一个高频失误是忽视技能描述的风格一致性。不同人写的技能描述风格各异有的简洁有的详细有的口语化这会直接影响语义路由的检索质量。我后来在技能库里加了描述模板约束统一用当……时调用该技能并……的句式加上关键词列表整体命中率稳定了很多。我个人在实际操作中最深的体会是技能库的表面价值在稳定和降本但真正的长期价值在于它把团队对业务的理解固化成了可迭代的资产。模型更新换代时可以换模型工具升级时可以换工具技能库却可以一直沉淀下去。如果你也在做智能体应用建议从最痛的一两个高频场景开始用最小可用技能跑通闭环再慢慢扩充——这条路经得起反复验证也是最省力气的落地路径。