我先说句实在话这两年聊AI Agent的人很多但真正能把手上的模型变成一个指哪打哪的角色核心瓶颈往往不在模型本身而在技能这一层。标题里这个agent-skills看起来只是两个英文词拼在一起实际上它指向的是智能体技能工程化这件事——怎么让Agent稳定地调用工具、完成任务、编排流程。这篇文章我想从自己的实操经验出发拆清楚技能体系应该怎么设计、怎么写、怎么调以及最容易踩的那些坑。适合正在做Agent应用、又觉得提示词已经救不了我的开发者参考。1. 技能体系设计先搞清楚Agent到底需要什么样的技能1.1 技能不是函数而是模型与工具之间的翻译层很多朋友一上来就把Agent的技能等同于调用外部API觉得我会写个Python函数能联网搜索、能算个加减乘除这就是技能了。错。技能的核心不是执行逻辑而是让模型理解什么场景该用、输入输出长什么样、边界在哪里。说白了技能是模型和工具之间的翻译层。模型本身不会知道你要我查天气我该去看哪个服务它只知道我该给某个函数传参了但参数格式我不确定。技能体系要做的事情就是把一件任务的语义描述、触发条件、参数结构、执行方式用模型能读懂的方式写清楚。我在早期的项目里吃过亏当时把内部的订单查询接口直接丢给模型调用接口文档写得很规范但模型经常把参数传错——后来才发现问题不在模型笨而是我没有给这个接口配一份模型友好的技能描述。所以一个合格的技能描述至少包含四块技能名称简短、无歧义最好是动词开头的短语比如查询订单状态功能描述一到三句话说明这个技能能做什么不能做什么适合什么场景参数Schema每个参数的名称、类型、取值范围、是否必填、默认值返回结果说明告诉模型会拿到什么样的数据以及这些数据怎么理解这四块信息缺一不可尤其是返回结果说明很多技能定义里根本没写导致模型拿到返回值后不知道怎么用。我见过一个很典型的例子技能返回了JSON里面有订单号、金额、状态但模型不知道status1到底代表什么于是就开始瞎猜甚至还编出个status2表示已发货。后来在技能描述里加了状态码的枚举说明准确率一下就上去了。1.2 技能粒度怎么定太粗容易失控太细容易低效技能拆到什么程度是衡量Agent系统设计水平的分水岭。我见过两种极端一种是把整个业务逻辑塞进一个技能里比如处理售后这样一个技能里面涵盖了退款、换货、人工介入、物流查询模型根本搞不清楚该走哪个分支另一种是把技能拆得极细比如计算字符串长度这种也在技能列表里导致模型每次决策都要从几十个技能里去选推理速度明显变慢选错的概率也在上升。我的经验是技能粒度应该根据任务闭环来定而不是根据API粒度来定。什么叫任务闭环就是一件用户从提出诉求到获得结果的事情。比如查物流是一个任务闭环根据物流状态判断是否需要自动理赔是另一个闭环。前者应该是一个技能后者如果已有业务规则应该也是独立技能而不是混在一起。粒度定完之后还有一个重要动作——给技能分级。核心技能高频使用、跟主流程强相关应该放在最前面边缘技能低频、辅助性往后排。因为很多Agent系统在意图路由时会对技能描述做语义匹配描述越靠前被选中的概率越高。实测下来把高频技能放到列表头部之后路由准确率能提升不少这个优化成本极低性价比非常高。1.3 技能描述怎么写模型才真正看得到写技能描述跟写API文档是完全不同的思路。API文档是给人看的可以用大量专业术语和精确格式技能描述是给模型看的要追求语义清晰、边界明确、样例充分。模型在做技能选择时本质上是拿用户的输入跟技能描述做语义匹配所以描述写得越贴近真实用户话术选得越准。我在写技能描述时会刻意用这个技能可以处理...,不能处理...的句式把边界直接画出来。比如说一个天气查询技能描述写成根据城市名称查询当前天气和未来天气预报支持国内主要城市不支持查询历史天气数据。后半句很重要因为用户如果说帮我看看上周三的天气模型知道这个技能干不了就会去走其他路径而不是硬调。参数Schema这块我强烈建议给每个参数写一个参数含义和示例值。比如城市参数示例值写北京、上海、广州模型就知道该传中文城市名而不是拼音。再比如时间参数示例值写2025-06-01模型就知道日期格式是YYYY-MM-DD不会给你传一堆乱七八糟的东西。这个细节别偷懒我统计过加上示例值之后参数传错率大概能下降好几成。2. 技能实现与运行机制从定义到落地的关键细节2.1 技能描述文件的结构用JSON还是YAML怎么设计才科学现在主流的Agent框架里技能描述基本都走声明式配置常见格式是JSON或YAML。我个人偏好JSON Schema风格因为工具链成熟而且很多模型在微调和少样本学习时都见过JSON结构理解成本低。一个完整的技能描述文件我通常按下面这个模板来写{ name: query_order_status, description: 根据订单号查询订单的当前状态支持的状态包括待支付、已支付、已发货、已签收。不支持查询历史订单。, parameters: { type: object, properties: { order_id: { type: string, description: 订单号一般为数字或字母组合, examples: [SO20250601001] } }, required: [order_id] }, returns: { type: object, properties: { order_id: string, status: string, status_desc: string } } }注意我把returns单独拉出来定义了这不是JSON Schema标准里的字段但对模型理解输出结果帮助极大。很多框架不会额外定义返回结构模型只能靠执行结果自己去猜猜就容易出错。加上这块之后Agent拿到返回值就能直接判断任务是否完成结果是否符合预期尤其是在多轮对话场景下模型需要基于返回值决定下一步动作这个信息非常关键。2.2 技能执行器的设计把描述文件变成真正能跑的代码描述文件只是剧本真正执行还要靠技能执行器。我推荐把每个技能实现成一个独立的Python类或者函数统一继承一个抽象基类这样做的好处是统一管理生命周期、统一处理异常和日志。设计执行器时有一个常被忽略的点——超时控制。任何一个外部API调用都可能卡住如果不给技能执行设置超时整个Agent的响应就会被拖死。我通常在技能执行器里做三层防护第一层是模型调用层的超时控制在几秒内第二层是工具执行层的超时外部API或数据库查询单独计时第三层是整体任务级的超时整个Agent一次回复的时间上限。这三层超时配合至少能保证Agent不会因为某个技能卡壳就彻底失联。实操中我遇到过MicroService响应极慢导致Agent超时的线上故障当时排查了很久最后发现就是缺了工具执行层的超时设置。另外技能执行器里一定要留钩子hook用来做日志埋点。每次技能被选中、被调用、执行成功、执行失败都要记录下来。这些日志不仅是排查问题的依据更是后续评测和优化技能路由的直接素材。2.3 技能注册与发现运行时如何知道有哪些技能可用技能定义好了执行器也写好了接下来要解决的是模型怎么知道有哪些技能。常规做法是在系统提示词里把技能列表塞给模型但这有个问题——技能过多时提示词会越来越长模型在长上下文中做工具选择的准确率会下降。我见过有人塞了30多个技能描述进提示词结果模型经常选错而且每次请求的token消耗也很大。解决思路有两个方向。一是分层路由先做粗粒度意图分类比如订单相关支付相关售后相关再在子类里选具体技能这样可以显著减少模型单次决策的候选集。二是动态技能发现根据用户输入先做一个检索召回从技能库中选出Top5相关技能再让模型在候选技能中做选择。第二种方式更灵活适合技能数量几十上百的场景。我自己的做法是静态清单动态召回混合把高频核心技能固定在提示词里其余技能放技能库每次请求先做向量检索召回合并后再交给模型决策。这样做之后技能选择准确率提升了差不多十个点token成本也降了不少。向量检索不需要多复杂的模型普通的Embedding模型就够用关键是技能描述文本要写得规范检索质量才有保障。2.4 技能参数注入与校验从模型输出到函数入参的最后一公里模型输出参数经常是差不多对但不完全对这最后一公里处理不好前面做的所有工作都白费。常见的坑包括模型给出参数值类型不对字符串传成了数字、参数名跟Schema对不上多了或少了前缀、字段缺失、枚举值写错。我的做法是在技能执行器入口加一个参数校验层用JSON Schema的校验库来做格式校验同时对关键字段做二次转换。比如日期参数模型可能给你6月1号或2025/6/1这种格式执行器里就要做归一化。再比如手机号参数模型可能给你1 3 8 0 0 0 0 0 0 0 0这种带空格的东西不清理就往API里传基本就是错误。这些转换逻辑千万别放在技能业务代码里要集中放在参数校验层统一处理否则每个技能都要重复实现一遍维护成本直线上升。还有一个我自己踩过的坑模型偶尔会在参数里带上跟任务无关的信息比如用户说帮我查一下订单订单号是SO123顺便告诉我今天天气怎么样模型可能把今天天气怎么样也塞进查询参数的某个字段里面。所以参数校验层除了格式校验还要做超出范围的数据过滤该拒绝的字段就拒绝不要惯着。3. 技能编排与组合调用单技能能跑通之后真正的挑战才开始3.1 技能编排的本质让模型学会先做什么再做什么单技能调通只是第一步。真实业务里大部分任务都需要多个技能组合完成。比如用户说我的订单超时未发货帮我申请退款这背后至少涉及查询订单状态、判断是否满足退款条件、执行退款申请、通知用户可能还要调用客服系统留工单。这里面的执行顺序是有依赖的——不查订单就没法判断不判断就不能退款。技能编排的核心是让模型理解依赖关系和执行顺序。我在设计技能路由时会给每个技能标注前置技能和后置技能的关系模型在生成执行计划时会优先检查前置条件是否满足。比如退款技能的前置技能是查询订单状态模型在计划阶段发现还没查订单就会先插入查询动作而不是直接跳到退款执行——这能避免一大批逻辑错误。编排的控制权不完全在模型手上还要有硬规则兜底。我的建议是让Agent框架中的Planner负责生成执行计划用一个轻量级的规则引擎来做计划校验检查是否有循环依赖、是否缺少必要前置、是否调用了不存在的技能。规则校验通过后才真正下发执行。纯靠模型自动编排在复杂任务上翻车率很高加一层规则校验能让稳定性有质的提升。3.2 串行与并行什么场景并行什么场景必须串行技能编排中有一个非常影响体验和成本的决策——并行还是串行。有些技能之间没有依赖关系完全可以并行执行省将近一半时间有些技能有严格依赖必须串行等待结果。判断规则很简单后一个技能的输入是否依赖前一个技能的输出。比如查询订单状态和查询当前用户信息互不依赖可以并行但查询订单状态和根据状态判断是否退款强依赖必须串行。我在实际系统中的做法是把无依赖的技能放入一个并行组组内技能同步发起调用等所有结果返回后再进入下一阶段。这样做不仅省时间还能减少模型多轮推理的次数提升整体稳定性。但是并行也不是免费的——多个外部API同时调用对系统资源、下游服务的并发能力都有要求如果下游服务扛不住并发强行并行反而会把服务打崩。所以并行之前先确认下游服务的限流阈值。3.3 组合技能的复用把固定套路沉淀成独立技能在编排过程中我慢慢发现一个规律某些技能组合方式是固定套路。比如查订单-判断状态-给用户反馈这套流程在很多对话场景里反复出现。与其每次让模型现场编排不如直接沉淀成一个组合技能也叫复合技能。组合技能的内部逻辑固定下来对外暴露一个简洁接口模型只需要调用一次内部自动跑完整条链路。这样做有三个好处减少模型决策负担提高执行一致性方便统一调优。坏处是灵活性降低如果业务规则经常变组合技能的维护成本就上去了。我的建议是把稳定成熟的流程做成组合技能把易变的分支逻辑保留为单技能让模型自己拼装。这个分寸需要在实际业务中反复拿捏没有统一标准。组合技能的实现也不复杂本质上就是执行器内部调用其他技能。关键是在组合技能的描述里写清楚这个技能已经包含了哪些步骤调用前需要满足什么条件避免模型在组合技能外部又重复调用内部技能造成重复执行。4. 技能评测与调优拿数据说话别靠感觉4.1 建立评测集这是技能优化最容易被跳过的一步技能效果好不好不能靠感觉还行。最容易被偷懒跳过的一步就是建立评测集。我见过太多团队把Agent上线后遇到问题第一反应是改提示词改了几轮发现还是不行才想到要做评测。评测集不需要一开始就很大但覆盖面要足够每个技能至少准备几十条典型用户输入包含正常情况、边界情况、异常情况以及容易被混淆的相似输入。评测集做好之后要跑一个自动化评测流程。每次修改技能的描述、参数Schema、编排逻辑都要重新跑一遍评测集对比前后效果。我踩过的坑是改了一个技能描述结果A任务的准确率上去了B任务开始频繁选错技能如果不跑全量评测根本发现不了。有了评测集回归问题才能被及时拦下来。这个过程很像传统软件工程里的自动化测试只是断言的粒度从代码逻辑变成了模型选对技能并正确执行。评测维度上我建议至少看四类指标技能选择准确率、参数传递正确率、任务完成率、单任务耗时和token消耗。前三个是效果指标第四个是成本指标。很多团队只盯任务完成率忽视了token消耗结果模型为了完成任务疯狂调用多个技能链路上每一步都要跟模型交互成本涨三五倍都不奇怪。4.2 常见问题排查描述冲突、上下文污染、串联失败评测跑起来之后最常暴露的问题是三类我一个个说。第一类是描述冲突。两个技能的功能描述太像模型分不清该用哪个。排查方法是把用户的真实输入拿出来分别跟两个技能的描述做相似度计算如果分数很接近说明描述写得不够有区分度。解决办法是把你期望的边界写得更清楚或者加更适用于...这样的偏向性描述。第二类是上下文污染。模型在长对话过程中把之前轮次的内容错误地带入技能调用。典型场景是用户先问了A订单再问B订单模型可能把A订单号当成B订单号传给了查询技能。这个问题的根源在于Agent框架把历史对话全塞进了上下文模型区分不了当前意图和历史信息。我的解决办法是在模型做技能调用的那一轮只把当前用户输入和必要的会话摘要传给模型不要全量灌入历史记录。第三类是串联失败。组合技能内部某个环节出错导致整个流程中断但模型又不知道错在哪。解决思路是给组合技能的执行器加上阶段状态返回机制内部哪个环节失败就把错误信息结构化成返回值的一部分这样外层模型就能基于错误信息做下一步决策比如重新调用或向用户解释而不是盲目重试。4.3 迭代方法论每次改动都要回答三个问题技能体系的调优是一个持续的过程。我在实践中逐渐形成了一套固定的迭代节奏每次改动前先想清楚三个问题——这次改动想解决什么问题、预期带来什么变化、如何评估是否成功。想不清楚这三个问题就不要动手。举个例子如果你发现查询天气技能经常被选错成查询空气质量技能你要做的不是急着改两个技能的描述而是先搭建一个评估集专门准备十来条涉及天气和空气质量的用户输入跑一遍基线数据确认选错的比例。改完描述后再跑一遍同样的评估集对比准确率变化。整个过程可能只需要一两个小时但比凭感觉改提示词靠谱得多因为你有了可量化的依据。另外技能列表不是越长越好。技能数量膨胀到一定规模后模型选择成本上升、准确率反而下降。我一般每个季度做一次技能盘点把长期未被调用的技能下线把重叠度高的技能合并。技能库保持精简模型的路由压力就小整体稳定性也会更好。5. 写在最后的一点经验技能体系做到后面你会发现它跟写业务代码越来越像——不是堆Prompt技巧而是设计接口、管理依赖、做测试回归、控制复杂度和成本。如果非要说一条最重要的实操体会那就是技能描述是给模型看的文档不是给人看的文档每个自然语言的措辞都值得反复打磨因为它直接影响模型的选择和执行。我最后一次踩到的大坑是上线前没做全量回归改了一个共享技能的返回结构结果下游三个组合技能全部间接受到牵连线上出现了一堆看似正常但实际上跑错了逻辑的会话。那次之后我给自己的团队定了一个硬规矩任何技能改动必须跑通全量评测集才能合入哪怕是一次措辞微调。这条规矩看起来麻烦但长期来看省下来的返工时间远超投入成本。希望这篇基于agent-skills整理的实操笔记能帮你把Agent从能聊推进到能干。技能体系没有一劳永逸的方案数据驱动、小步迭代才是走得很稳的姿势。