最近一年身边聊 Agent 的人肉眼可见地变多了。但聊归聊真正把手头事情跑通的没几个。我也在被问过能不能让 Agent 帮我们把周报自动写了之后被现实狠狠教育了一顿光靠提示词写出来的 Agent演示的时候挺聪明一上真实数据就翻车。后来我把思路从写更好的提示词换成了给 Agent 配技能也就是 agent-skills 这条路效果才真正稳定下来。这篇文章想把这套东西掰开揉碎讲一讲技能到底是什么、和工具调用怎么区分、技能库该怎么搭、我踩过哪些坑。适合正在做 Agent 应用、被模型输出不稳折磨过的开发者以及想从提示词工程往 Agent 工程方向进阶的朋友。1. 从会聊天到会干活Agent 技能为什么突然成了焦点1.1 大模型不缺理解力缺的是可复用的执行能力大模型的对话能力已经不需要我多说了。你给它一段需求它能给你一个像模像样的回答。但一旦让它去完成一个具体任务——比如查一下这个客户的上月消费记录并生成分析——问题就来了模型可能理解对了但执行路径五花八门有时用错了查询条件有时跳过了某个关键步骤有时输出格式和下游系统对不上。我最早处理这类问题的方式也俗套往提示词里堆细节把每一步写得清清楚楚甚至把错误示例也塞进去。结果呢提示词越来越长模型反而更容易被无关信息干扰。后来我试了一个笨办法把任务拆成固定的几个阶段每个阶段让模型调用一个封装好的函数函数内部做参数校验和结果格式化。就这么一改任务成功率从六成左右跳到了九成以上。这个固定阶段封装函数的组合其实就是技能的雏形。1.2 技能的本质把不可控行为装进可控框架要想说清楚技能得先区分两件事提示词是告诉模型怎么想技能是告诉模型怎么做。打个不严谨的比方提示词像是给实习生讲了一遍业务逻辑技能则是给实习生一份带检查清单的标准作业手册。前者依赖对方的理解力和临场发挥后者把关键动作固化成了步骤错了能定位漏了能发现。一个标准的技能通常由以下几个部分组成触发条件说明这个技能在什么情况下被调用模型需要根据用户目标和技能描述做匹配。输入参数定义技能的入参结构以及每个字段的取值范围、默认值、是否必填。执行逻辑技能内部的实际操作可能是调用一次工具也可能是多个工具按序编排。输出校验对执行结果做结构化检查确保返回给模型或下游系统的数据是合法的。失败兜底当校验不通过或者执行报错时技能应该返回什么、下一步该做什么。有了这层封装模型的自由度被限制在选择技能和填写参数这两个环节而不是整个执行过程。自由度一收稳定性自然就上来了。2. 技能不等于工具三个层级一次讲清楚2.1 原子技能最短的调用路径很多人刚接触技能时最容易混淆概念觉得技能不就是工具吗让模型调一下 API 而已。实际上工具的粒度太细了一个工具只负责一次原子操作比如查询用户信息发送短信通知。在真实业务里模型很少只靠一次工具调用就能完成用户目标它需要连续调用多个工具、处理中间结果、根据上一步的输出决定下一步动作。原子技能就是把一次工具调用包装成一个可被模型理解和执行的完整动作。它比工具多了一层描述信息告诉模型这个动作是干什么的、什么时候用、参数怎么填。比如工具层只有一个 get_order(order_id)技能层可以把它包装成根据订单号查询订单完整信息包括状态、金额、物流轨迹并返回格式化后的文本摘要。同样一个工具在不同的技能描述下模型对它的使用方式会完全不同。2.2 复合技能把多个原子动作编排成流程当任务需要多步操作时原子技能就有点不够用了。举一个高频场景生成数据周报。这个任务涉及查询多个数据源、计算同比环比、生成趋势描述、排版成报告格式。如果让模型临时决定每一步怎么做结果通常不够稳定更合理的做法是把这套流程直接固化成复合技能。复合技能内部维护了一个小型的执行编排第一步调数据查询技能第二步调分析计算技能第三步调报告生成技能。每步之间可以传递中间结果也可以根据上一步的输出做分支选择。对模型来说它只需要做一次把这个任务交给周报技能的决策剩下的流程全部由技能内部脚本接管。这样既减少了模型的决策负担也让失败率集中在可观测的固定环节上。2.3 工作流技能跨越系统边界的长期任务再往上一层是工作流技能。它和前两者的区别在于工作流技能往往涉及多个外部系统运行时间很长并且可能包含人工审批、条件等待、异常恢复等环节。典型的例子是跟进一个工单从创建到关闭创建工单、分配处理人、定时跟踪进度、超时自动提醒、结束后归档整个周期可能持续数天。工作流技能需要一个持久化状态存储记录当前进行到哪一步、依赖哪些数据、下一步何时触发。这部分已经超出了普通工具调用的范畴更像是一个轻量级的业务流程引擎。实际项目中如果要自己做一套完整的工作流技能框架会比较重我更推荐先引入现成的状态机或任务队列组件把状态流转从技能逻辑里剥离出去。层级典型执行时长是否涉及多个系统状态管理适用场景原子技能秒级否无单次查询、单次写入、单次通知复合技能秒级到分钟级可能临时上下文数据报表、信息整理、批量处理工作流技能分钟级到天级是持久化状态工单跟进、审批流、定时任务三者之间没有绝对的优劣之分核心判断标准是模型需要参与决策的环节有多少。能固化到流程里的就尽量固化给模型留的决策空间越小整体越可控。3. 从零搭建技能库目录、描述与注册机制3.1 技能目录别让 Agent 在代码库里大海捞针技能数量一多第一个问题就是模型怎么找到对的技能。如果项目里只有十个技能靠提示词把技能列表贴进去就够了但涨到几十个、上百个技能以后直接把所有描述都喂给模型既浪费 token 又容易互相干扰。这时候必须建立技能目录。我的做法是按业务域来做顶层划分比如客户域订单域数据域通知域每个域下面再按使用场景拆子类。每个技能有一个全局唯一标识命名规则统一为领域_动作_对象例如 customer_query_orders、data_report_weekly。目录不只是给人看的也是给技能检索模块用的。模型在响应用户请求时先经过一层检索只把和当前任务相关的几个技能描述和参数 schema 注入上下文而不是一股脑把全部技能倒给模型。3.2 技能描述怎么写这是触发率的胜负手我花了很长时间才意识到一个技能被成功触发的概率很大程度上取决于描述文本写得清不清楚而不是技能本身的实现复不复杂。模型通过语义匹配来做技能选择描述里的措辞、场景覆盖、边界说明直接影响匹配准确率。一个好的技能描述应该包含几个要素动词开头、明确触发场景、给出典型用户表述样例、说明什么时候不要用。以客户流失预警这个技能为例我前后改了三版才达到比较理想的触发率。第一版描述写的是客户流失分析功能对客户进行流失风险判断。这个描述太笼统模型在遇到帮我看看最近有没有要跑的大客户时并不觉得自己该调用这个技能。第二版加了一些场景词效果有所提升但误触发仍然不少比如用户说查一下这个月新增客户时模型也误调了流失预警。第三版在最后加了一行反面示例本技能仅适用于存量客户流失风险判断不适用于新增客户统计、客户画像查询。加了这一句之后误触发率明显降了下来。3.3 参数 Schema少一个字段技能可能当场废掉技能描述决定模型选不选这个技能参数 Schema 决定模型能不能正确使用它。如果参数定义太严格模型在不确定时容易放弃调用如果太宽松技能内部拿到的数据质量又会很差。我的经验是遵循三个原则。第一必填参数要少。能用默认值兜底的字段尽量给默认值让模型只需要填它真正有把握的内容。第二给模糊信息留一个入口。用户很少会说清楚请传入订单号 123456这种话他更可能说帮我看一下最近那笔大额订单到哪了。最近大额这些描述模型无法直接转成订单号所以我通常会在参数里增加一个描述字段允许模型把原始表述写进去由技能内部做自然语言到参数的转换。第三每个参数要写清楚取值范围和格式尤其是日期、金额、状态这类容易出错的字段。3.4 注册机制让技能可被动态加载技能不应该和主项目代码强耦合。我在项目里采用的方式是技能包模式每个技能是一个独立目录包含描述文件、参数 Schema、执行脚本、测试用例。启动时技能管理器扫描技能目录把每个技能的元信息加载到注册表里并对外提供检索和调用接口。这样新增一个技能不需要改主项目的任何代码只需要往技能目录里放一个符合规范的技能包重启或执行一次热加载就能生效。注册表里还要维护技能之间的依赖关系。复合技能在元信息里声明自己依赖哪些原子技能注册的时候会做一次依赖检查避免出现技能注册成功但运行时找不到内部依赖的尴尬情况。4. 技能质量怎么保证测试、评测与回归4.1 不确定输出下的确定性校验技能的逻辑本身是确定性的但技能被模型触发和填参的过程是不确定性的。这意味着测试不能只盯着技能内部函数的正确性还要覆盖模型能否正确触发、正确填参这一层。我在每个技能包里放三类测试单元测试、集成测试、评测用例。单元测试验证技能内部逻辑比如给一个固定参数的输入检查输出是否符合预期。集成测试则把模型接入进来模拟真实用户请求观察模型是否会触发该技能、参数是否填对、最终输出是否可用。评测用例是数量最多也最费精力的一部分我会从历史对话里收集真实的用户表述整理成一组固定的测试集要求技能在升级前后都得在这组测试集上保持住水平。4.2 评测集要包含正常、边界和对抗三类场景评测集如果只放几个顺风 case测试完了等于没测。我的习惯是每个技能准备至少三十条以上的评测用例并且分成三类正常场景用户意图明确表述规范模型应该稳定触发。边界场景用户意图模糊、包含缺失信息、需要追问澄清。模型至少要能给出合理的澄清动作而不是胡乱执行。对抗场景用户问题看似相关但实际超出技能范围。模型应该拒绝触发或转交其他技能而不是硬凑。对抗场景通常最容易被忽略但恰恰是它决定了一个技能能不能在真实嘈杂环境下存活下来。真实用户不会像测试集那样规规矩矩地说话他们可能一句话里同时包含多个意图甚至用词和你技能描述里的关键词完全错开。评测集的作用就是用固定样本守住底线的同时暴露出这些语义匹配层面的漏洞。4.3 回归测试技能升级时的安全网技能不可能一次写好就不动了。业务在变上游接口在变模型底座也在变。每一次变化都可能让原本稳定的技能开始犯错。我经历过一次印象很深的翻车底层模型从旧版本升级到新版本之后原本一直正常触发的一个技能突然几乎不再被触发。排查了很久才发现新版本模型在语义相似度上的行为发生了变化旧版能匹配上的表达在新版看来距离变远了。那之后我把模型版本升级视作一次重大变更任何模型底座更新都得先跑一遍全部技能的评测集对比新旧版本在各场景下的表现差异。这个流程看起来笨重但它能避免很多线上问题。技能本身的代码改动同理改动后要跑回归特别是复合技能内部的执行顺序哪怕调整一步都可能影响下游输出。5. 踩坑实录那些异常隐蔽的技能触发问题5.1 技能描述越写越长触发率反而降了我一开始以为技能描述写得多就是周全于是把各种场景、各种细节都塞进去。结果模型在决策时被大量冗余信息干扰反而更倾向于选择那些描述更短的通用类技能。后来我专门做了一组对照实验同一个技能分别用长描述和短描述跑同一批测试集发现短描述加反面示例的组合表现最好。现在我的原则是描述控制在两百字以内把核心触发场景和核心排除场景说清楚其余细节放到技能内部文档里。5.2 参数校验太严格模型被逼进死胡同给技能加参数校验本来是为了防止脏数据进入下游但有一次我把校验条件设得太苛刻。模型在连续几次填参被拒之后会陷入一种反复重试的状态不停用近似值重新提交不仅浪费大量 token还把技能的调用队列堵死了。后来我调整了策略校验不通过时不是直接返回错误而是返回一个半成品结果加一个明确的提示信息告诉模型哪几个字段有问题、正确格式是什么。模型拿到提示之后下一次填参就规范多了。5.3 多个技能互相覆盖路由规则必须排优先级技能库膨胀到一定规模后必然出现两个技能在语义上很接近的情况。比如查询客户消费记录和查询客户订单记录在某些表述下边界非常模糊。模型选错技能的直接后果就是输出牛头不对马嘴。我最终靠两件事解决了这个问题一是在目录检索阶段增加一个相关性阈值低于阈值的技能直接不参与候选二是在注册表里维护一个显式互斥列表当两个技能同时被选中时强制按优先级排序。虽然这看起来有点粗暴但实际效果立竿见影。5.4 模型升级带来的技能行为漂移前面提到了模型升级后技能触发率下降这只是漂移的一种表现。另一种常见漂移是参数填写的习惯变了。比如旧版模型在时间参数上倾向于使用日期范围新版本模型则总喜欢用相对时间描述。技能内部如果不做二次归一化处理很容易因为这些隐形变化而拿到错误数据。现在我对每个技能都要求入参必须经过归一化层把模型提供的任何合法但不统一的参数格式统一转换成下游系统需要的标准格式从机制上降低漂移的影响。6. 从能用到好用技能库的演进路线与个人体会6.1 先切场景再封技能不要一上来就大而全技能库建设最大的敌人是规划过度。我见过有人花很大精力设计完美的技能分类体系结果真实业务场景只有两三个大部分技能被封存后一次都没被触发过。我现在的做法是反过来的先列出业务里最频繁、最耗时、最需要稳定性的几个任务场景每个场景用少量几个技能先跑通跑通之后观察一段时间看哪些技能被触发得多、哪些始终没被触发。触发得多的继续优化始终没被触发的直接下线或者合并。这样技能库是顺着真实需求长出来的而不是纸面上规划出来的。6.2 技能的可观测性日志、追踪与指标一样都不能少技能一旦上线调试就变得非常困难因为问题可能发生在模型决策层也可能发生在技能内部执行层。如果日志不够详细排查一个问题可能得花上大半天。我给每个技能都加了三类观测信息调用链追踪、决策记录、执行明细。决策记录尤其重要它保存了模型在选技能和填参时拿到的完整上下文以及模型给出的原始输出。这样当一次调用失败时我可以立刻看到模型当时是怎么想的、为什么选了错误的技能或者填了错误的参数。没有这层数据所有排查都是盲猜。6.3 技能包的可共享性定义一套轻量的发布格式做到这里技能库的形态已经很接近社区化了。我们给每个技能包定义了版本号、依赖列表、作者信息和 changelog发布时生成一个不可变的版本快照。这样一套技能库可以被多个项目复用也方便回滚。如果你有多个 Agent 项目在跑我强烈建议把技能包做成独立仓库项目侧通过依赖管理引入而不是在每个项目里复制粘贴技能代码。经过这几个项目的折腾我最大的体会是Agent 的能力提升不该寄托在模型突然变聪明上而该寄托在工程侧把不确定行为逐步收敛成确定能力。技能正是这个收敛过程的核心载体。往小了说它让我的 Agent 从偶尔能用变成了稳定能用往大了说它把个体经验沉淀成了组织资产。如果你现在正被模型不听话搞得焦头烂额不妨换个思路别再死磕提示词了认真给 Agent 配一批技能可能会有完全不一样的体验。