做了一轮Agent项目复盘我最大的感触是决定一个智能体能否从“demo好用”走到“生产可用”的关键往往不在大模型选哪家而在agent-skills这套技能体系搭得是否扎实。所谓技能简单说就是给Agent挂上一批边界清晰、可复用的能力单元让它在面对任务时“知道能做什么、该调谁、怎么调”。这篇文章想把这套东西从设计、分类到实现、排错一整条链路拆开聊一聊不会写得太高深但尽量把该讲的原理和该避的坑都讲到位。适合正在做Agent应用、提示词工程、工具接入或者准备在自己项目里引入技能体系的朋友参考。不管你是刚开始接触还是已经踩了不少坑应该都能找到点能直接拿去用的东西。1. 技能体系整体设计与核心思路1.1 为什么单独把“技能”拎出来先说一个很多初学者容易忽略的点不要把Agent的技能和提示词混为一谈。提示词解决的是“模型该怎么回答”技能解决的是“模型能做什么事”。打个比方提示词是给员工讲工作规范技能是给员工配一套趁手的工具和标准作业流程。只会讲规范员工遇到具体活儿还是不知道手往哪儿放只有工具没有规范员工也不知道什么场景该用哪把工具。我见过不少团队第一版Agent做得非常粗糙把所有业务逻辑全部塞进一个超长的系统提示词里让模型“自行判断、灵活处理”。结果就是模型经常脑洞大开要么自己编一个流程走完要么把一个简单问题绕了一大圈。这种方案在十来个请求的demo阶段没问题一上真实流量就原形毕露回答不稳定、错误不可追踪、出了问题根本不知道是模型判断错了还是逻辑写错了。技能体系的核心思路是把“不确定性”拆开处理模型只负责两件事——判断当前该用哪个技能、把调用参数填对至于技能内部怎么执行、怎么返回全走确定性的代码逻辑。这样一来不可控的部分被收敛到一个很小的范围内其余部分都能用常规工程手段保证质量。1.2 技能体系的分层结构一套完整的agent-skills体系我习惯拆成三层来看。第一层是能力层也就是技能本身。每个技能是一个完整的行为封装对外暴露清晰的输入输出接口对内实现具体的业务操作。比如“查询订单状态”是一个技能“生成周报”是另一个技能。这一层的关键是技能的独立性和复用性做得好的话一个技能可以被多个场景、多个Agent共享。第二层是注册层负责把所有技能登记到一个统一的目录里并且给每个技能写清楚“什么时候用、什么时候不要用、参数怎么填、返回值长什么样”。这一层直接决定模型能不能在关键时刻想起这个技能。很多团队技能写了一堆模型却老是不调用八成是注册信息写得不行。第三层是编排层负责把多个技能串成一条完整的任务链路。现实世界的任务很少是单个技能能搞定的比如“帮我把上周的销售数据整理成PPT”至少涉及数据查询、数据清洗、图表生成、PPT模板填充四个技能。编排层要解决的问题就是这些技能按什么顺序执行中间状态怎么传递某个环节失败了下游怎么办。这三层如果拆得清楚后续的迭代和维护会省很多事。我之前在一个项目里见过把技能逻辑、注册描述、编排规则全部硬编码在一块儿的做法结果每次改一个技能就要重新发一版而且改着改着就没人敢动了。分层之后每个环节都能独立修改、独立测试风险可控得多。1.3 设计技能体系前先想清楚的三件事动手之前有三件事最好先明确否则后面返工的概率非常大。第一件事要解决的任务到底有多复杂。如果是简单问答、单步操作类的场景技能体系可能反而有点杀鸡用牛刀真正适合上技能体系的场景通常具备三个特征任务有明确的多步骤结构、每一步涉及外部系统交互、错误发生的代价不可忽略。你可以对照一下自己的业务场景硬上技能体系只会拖慢响应速度、增加维护成本。第二件事谁来定义技能边界。这里容易踩的坑是让算法工程师自己闭门造车不去问业务方。我见过一个案例业务方期望的“订单异常处理”包括自动退款、短信通知、客服工单生成三个动作算法团队却只做了一个“订单状态标记”技能结果上线后业务方完全不认账。技能边界一定要和业务方对齐把“这个技能到底要替代人的哪些动作”聊透再动手实现。第三件事技能失败的兜底策略。模型判断会错、外部接口会挂、参数可能填得不对这些都不是小概率事件。事先想好某个技能调用失败时是让Agent换一个技能重试还是直接返回错误提示让用户修正还是转人工兜底没有兜底策略的技能体系就像一个不让请假的考勤制度迟早会出事。2. 技能的分类与边界划分2.1 按行为模式分好技能类型接触过的Agent项目多了之后我发现技能大致能分成四类每一类的设计和维护思路都不一样。工具型技能是最常见的本质上就是模型与外部系统之间的桥梁比如查询天气、创建工单、调用内部API。这类技能的特点是逻辑简单、输入输出明确实现难度最低但也是最容易写“粗”的参数定义、触发条件稍微含糊一点模型就会乱用。流程型技能是把一个多步骤、确定性强的完整业务流程封装起来模型只需要提供入口参数流程内部按固定逻辑走完。比如“处理客户退款申请”这个技能内部可能包含校验订单状态、检查退款资格、执行退款、发送通知四个步骤这些步骤是固定的不需要模型中途介入。这类技能的价值在于把模型不擅长的精确操作从“自由发挥”变成“标准化执行”。决策型技能比较特殊它不让模型做决策反而给模型提供决策依据。比如我做过一个技能叫“历史投诉等级查询”输入客户ID输出这个客户的投诉历史、等级标签、敏感程度模型拿到这些信息之后再决定用什么样的语气和路径回复。这种技能本质上是把记忆和风险判断外置了对客服类Agent特别有用。还有一类容易被忽视的是记忆型技能负责读写短期和长期记忆。很多Agent做不好长对话就是因为把记忆和逻辑混在一起写了上下文稍微一长就丢信息。把记忆操作单独做成技能之后什么时候该记、什么时候该查变成了模型的一个显式决策行为可控得多。2.2 单一职责原则的实操含义技能划分最核心的原则就四个字单一职责。一个技能只干一件事并且把这一件事干好。我知道有人会担心技能太细会不会导致模型选择困难实际上模型在技能选择上的能力和技能数量呈正相关但前提是每个技能之间的边界足够清晰。真正导致选择困难的是两个技能夹缠不清——比如“查询订单”和“管理订单”这种模型根本分不清边界。举个我印象比较深的例子。有个项目一开始做了一个“客户支持”技能试图把退换货、物流查询、优惠券核算全部塞进去。结果模型经常分不清该用哪个参数组合退换货请求给它传了优惠券信息物流查询给它传了订单金额整个支持链路乱成一锅粥准确率惨不忍睹。后来把这三个场景拆成独立技能每个技能的触发条件写得明明白白准确率提升了将近三成。这个案例给我的启示特别大模糊的边界是模型犯错的头号来源宁可技能多而专不要少而杂。2.3 技能的“不做清单”比“做清单”更重要给技能写描述的时候大部分人都只写“这个技能能做什么”很少有人写“这个技能不做什么”。后者恰恰是防止模型乱调用的关键。举个例子。一个电商Agent有俩技能一个是“修改收货地址”一个是“查询物流轨迹”。用户说“我的地址写错了帮我改一下”正确的调用是前者用户说“我这个快递到哪儿了”正确的调用是后者。但如果用户说“订单还没到看看我地址是不是写错了”模型可能就懵了这算修改还是查询如果“修改收货地址”技能描述里加了“注意本技能不负责查询物流状态也不负责判断地址是否正确仅执行地址字段的替换操作”模型会更倾向于先调用“查询物流轨迹”确认物流状态再调用“修改地址”技能执行修改。“不做清单”写得越具体模型的行为就越收敛失控的概率就越低。3. 技能的实现方式与注册要领3.1 三种主流实现路线怎么选技能落地的技术路线目前主流的有三种函数调用、MCP标准接入、独立服务加协议封装。函数调用是最轻量的方案直接把技能定义成标准函数通过模型API的function calling机制暴露出去。它的好处是集成成本低适合单机应用、技能数量不多几十个以内、外部系统交互比较少的场景。缺点是技能和具体代码耦合较深技能数量上来之后维护会有点吃力。MCP是这两年越来越主流的一套标准相当于给所有技能订了一个统一的“插座规格”。不同的技能只要实现了这套标准就能被任意支持MCP的客户端插拔使用。它的优势是生态共享一个领域内已经有不少现成的官方技能可以搜来直接用不用从零开发。适合技能类型多样、希望跨项目复用、团队有一定工程能力的场景。独立服务加协议封装的路线最重适合大厂内部的复杂集成。每个技能独立部署成一个微服务通过统一网关和注册中心对外提供服务。好处是技能之间的隔离性最强、可独立扩容、失败影响面可控但开发和运维成本也是三者中最高的。我的建议是起步阶段别一上来就上微服务先看技能数量和稳定性要求再决定。3.2 技能定义的标准格式不管走哪条实现路线技能定义基本都围绕name、description、parameters、returns四个部分展开。这里给一个JSON格式的示例便于说明该怎么把技能写清楚{ name: query_order, description: 根据订单号查询订单的当前状态与物流轨迹。仅当用户明确提供订单号并要求查询订单进度时使用。该技能不能用于创建订单、修改订单或申请退款当用户需要上述操作时请改用对应技能。, parameters: { type: object, properties: { order_id: { type: string, description: 订单编号通常以字母开头例如 AB123456789。 }, fields: { type: array, items: { type: string, enum: [status, logistics, payment, item_list] }, description: 需要返回的字段列表未传则默认为全部。 } }, required: [order_id] }, returns: { type: object, properties: { order_id: string, status: string, logistics: string, payment: number, item_list: array } } }这里有几个细节值得特别注意。参数定义里每一项description都要写清楚格式、范围、可接受的特殊值。模型不是人它不会“猜”不说清楚就很容易填错。枚举值一定要写全而且要在描述里说明“如果不在枚举内不要强行传值”。required字段要克制非必要的参数就不要标成必填。有一个常见错误是给某个技能标了五个必填参数但实际场景里用户根本不会一次性提供这么全的信息结果技能根本无法调用。必要参数能少则少留给模型更多容错空间。returns部分很多人会忽略其实非常关键。模型需要知道调用技能之后能拿到什么样的返回内容才能决定下一步用什么话术回应给用户。返回值结构写得越清楚模型组织回答就越准确。3.3 技能描述写作的四个进阶技巧描述写得好不好直接决定模型调用准确率这里有四个技巧值得反复推敲。第一个技巧是描述里要有触发条件而不是只写功能。好的触发条件写法是“当用户明确提到XX并要求YY时使用”而不是“处理XX相关请求”。前者给了模型清晰的判断依据后者则过分模糊。第二个技巧是在描述里写“用户的真实意图”而不是“技能的执行逻辑”。比如某个技能内部会调三个接口但给模型看的描述应该是“查询指定日期范围的销售额统计”因为模型的判断基准是用户需求语义而不是代码流程。第三个技巧是给模型举一个正反例。有些技能的判别条件确实容易混淆比如“内容审核”和“内容安全评分”这时候可以在描述末尾加一句“示例用户说‘帮我看看这篇文案有没有敏感词’应调用内容审核‘帮我评估这篇文案的风险等级’应调用内容安全评分。”实测下来给正反例对准确率的提升非常明显。第四个技巧是阈值类参数要避开模糊表达。像“较大金额”这种描述模型根本没概念直接写“金额大于5000元”才有执行力。这一点在处理退款、风控这类技能时尤其关键一个模糊阈值可能让整个技能行为变形。4. 技能编排与协同机制4.1 多技能协作的三种常规模式技能多了以后下一个问题就是怎么编排。我一般把协作模式分成三种链式、并行、分支。链式编排最直观就是一个技能的输出作为下一个技能的输入像流水线一样。比如“分析用户购买力”这个任务先调用“查询用户消费记录”拿到历史订单数据再调用“消费行为分析”生成报告最后调用“报告格式化”输出成标准文案。链式的优点是逻辑清楚、容易追踪缺点是一旦中间的某一个环节失败整个链路就得重来因此每个环节的容错设计要单独考虑。并行编排适合几个技能之间没有依赖关系、可以同时执行的场景。比如生成一份季度复盘报告时“销售数据汇总”“客户满意度统计”“市场活动效果分析”三个技能互不依赖就可以并行调用显著缩短整体响应时间。实现并行编排要注意的是结果汇总阶段几个技能返回数据的格式可能不统一需要有一个汇总模块做归一化处理。分支编排本质上是一个决策节点加多条执行路径把决策权交给模型让它根据当前对话状态从多个技能中选择一个继续执行。客服Agent是最典型的分支场景用户表达退货意图时模型先调用“订单查询”确认订单状态接着根据状态结果决定走“创建退货单”“转人工协调”还是“补发商品”三类分支中的哪一个。这种编排方式最灵活但对模型判断能力的要求也最高建议在分支节点做好日志埋点方便后面分析模型决策准确率。4.2 编排过程中的数据传递与状态管理多技能协作绕不开一个工程问题技能与技能之间的数据怎么传。我觉得最省心的方法是引入一个统一的“上下文对象”把整个任务执行过程中的中间数据都放在这个对象里每个技能只读写自己关注的那部分字段。这比让技能之间互相直接传参要稳妥得多因为直接传参会形成链式依赖一旦技能B要的字段和技能A的输出格式不一致又要改代码。状态管理要特别注意“一个任务的生命周期”概念。技能A执行完并不代表任务完成只有整个编排流程跑完上下文对象的状态才应该从“执行中”变成“已完成”。实践中有个容易踩的坑某个技能内部自己改了上下文状态导致编排层误判任务结束下游技能还没跑完整个任务就终止了。最好约定只有编排层有权修改任务级状态技能内部只能修改业务数据字段。这条约定看着简单能避免的坑却是成堆的。4.3 编排冲突的处理思路技能多了冲突不可避免。最常见的一种冲突是多个技能对同一个用户请求都有响应模型不知道怎么选。比如用户说“我实在理解不了这个东西怎么用”既可能是要“帮助文档检索”也可能是要“人工客服转接”。这时候如果两个技能的描述里都写了“当用户表达困惑时使用”模型就会犯难。解决办法有两个方向一是在技能描述里明确优先级例如在“人工客服转接”的描述里加一句“当用户表达强烈不满或重复求助多次时优先使用本技能”二是在编排层引入一个前置仲裁规则比如先调用“用户情绪判断”技能打一个标签模型根据标签再决定后续走哪个分支。还有一种冲突是技能之间出现循环调用。我遇到过的情况是Agent在A技能和B技能之间反复横跳了好几次既浪费了时间和token也让用户等着莫名其妙。这种问题通常是因为两个技能的边界没有做干净排查的时候应该回头审视技能描述把“不做清单”补完整同时可以在编排层设置最大技能调用次数超过阈值就直接转人工防止死循环吞掉系统资源。5. 技能评估与迭代调优5.1 用评测集来卡技能质量线技能体系有没有效不能靠感觉得靠评测数据说话。我常用的做法是构建一个评测集从真实历史对话里抽出一批带正确答案的样本再结合专家构造一批边界case和异常case形成一套固定的测试集。评测集里的样本最好覆盖这几类正常场景模型应该正确调用技能、混淆场景多个技能相似但应该选另一个、参数敏感场景同样一句话用户强调的是不同字段、拒绝场景请求不适合调用任何技能模型应该拒绝或求助人工。每一类都标注正确答案然后定期跑一遍看技能调用准确率和最终回答质量的变化。这个评测集的价值在于它是回归测试的基准。没有评测集的团队改技能全靠拍脑袋改完自己感觉变好了实际可能已经搞坏了某个场景有了评测集任何改动都能量化评估心里比较有底。5.2 关注的四个核心指标我日常盯的指标有四个。调用准确率是最核心的分子是模型正确选对了技能的样本数分母是评测集总样本数。它衡量的是模型“分诊”能力这个指标不达标后面一切优化都白搭。参数正确率衡量的是模型填写参数的质量有些场景模型技能选对了但参数填错比如字段传成另一个调用准确率会虚高。需要单独统计参数完全正确的比例才能发现这类问题。空转率指的是模型有调用技能的能力但面对本应调用技能的场景却直接给了文本回答或者面对不该调用的场景反而瞎调用。空转率高说明技能描述和用户表达之间还有距离要么补触发条件要么补负面示例。失败恢复率衡量的是技能调用出错之后Agent能否快速给出用户可接受的后续方案。这个指标很重要因为技能内部执行出错是常态恢复能力决定用户体感。5.3 技能迭代的节奏与数据驱动技能体系不是一锤子买卖上线之后需要持续迭代。我建议的迭代节奏是新技能先灰度、观察数据、再全量。灰度阶段可以挑一部分流量用户进入新技能路径同时完整记录调用日志。重点看两件事一是技能在被真实场景触发时的命中率怎么样二是模型是否把该调这个技能的场景判给了别的技能。把这两类日志捞出来人工看一遍基本就知道新技能的描述和边界该调哪里了。还有一个小经验每两周做一次技能健康度巡检把近两周的调用数据进行统计看看哪些技能一周都没被调用过。长时间未调用的技能要分清原因是业务场景真的没有了还是模型压根想不到这个技能。后者多半是描述触发条件写得太窄调整完再观察一周还是没有调用就考虑下线。数据驱动的核心原则是所有调整都基于日志和分析不要靠猜。我曾见过有团队凭感觉把某个技能描述越写越长结果调用率反而更低了最后一看日志才发现是描述里的无效信息太多把关键的触发条件挤没了。6. 常见问题与排查技巧实录6.1 模型反复不调用技能这个问题几乎每个做技能体系的人都会遇到。排查的第一步先确认模型版本是否支持函数调用不要在这个环节浪费时间。第二步检查技能描述里有没有明确的触发条件很多技能描述写得跟功能说明书似的模型根本看不出什么时候该用。更隐蔽的原因是技能注册数量过多挤占了模型有限的上下文注意力。实测下来一次性暴露给模型的技能数量超过五十个以后调用准确率会有明显下降。解决办法是引入“分组技能”把技能按领域分组根据对话意图先动态加载对应分组的技能而不是每次把全部技能都塞给模型。6.2 技能内部执行失败率高技能被正确调用了但内部经常报错这时候问题多半在外部接口和参数转换环节。排查顺序建议先看日志里技能接收到的参数和实际调用的接口参数是否一致再看外部系统的响应时间和限流策略最后看技能返回数据有没有做规范化处理。有一个很容易被忽略的点模型填参数靠的是description里的值外部接口一旦调整了枚举范围、字段格式技能内部一定要同步更新。不少项目出现“昨天还能用今天全失败”的诡异问题查到最后都是外部系统更新了数据结构而技能层没有适配。建议给技能层加一层适配器外部系统变的时候只改适配器不动技能主逻辑。6.3 技能返回内容模型“看不懂”有的技能执行结果是正确的但Agent给出的最终回答还是错的这说明模型没吃透技能的返回数据。最常见的原因有两个一是返回结构太复杂一坨嵌套JSON直接砸给模型它理解起来很费劲二是返回字段命名和业务口语对不上比如返回的是“code200”模型不知道这代表什么业务含义。比较通用的解法是让技能层在返回数据里附带一段“字段解读”用自然语言简单说明这段结果对用户意味着什么。这段解读不是给终端用户看的是辅助模型组织回答的。别小看这个改动它对最终回答质量的提升非常可观。6.4 常见问题速查表问题现象可能原因排查顺序参考解法模型完全不调用某技能描述缺少触发条件技能分组被隐藏先查日志确认技能是否暴露补全触发条件和不做清单多个相似技能被混用边界描述不清、不做清单缺失对照混淆样本逐条核对拆分技能或补充正反例描述技能被调用但参数频繁出错参数描述含糊、枚举值未写全检查参数级别日志细化参数格式和取值范围技能执行失败外部接口变更或限流查看技能层和外部系统日志增加适配器和重试机制最终回答质量差返回数据模型看不懂检查返回结构复杂度增加字段解读辅助段6.5 一个常用的日志埋点方法分析问题离不开日志日志埋点建议至少覆盖四个关键节点模型决策点命中了哪个技能、置信度多少、参数生成点模型生成参数原文是什么、技能执行点执行成功还是失败、耗时多少、最终回复点模型最终输出内容。四个节点的日志对齐之后任何一次失败链路都能还原出来是模型选错了还是参数传错了还是外部系统挂了还是模型理解不了返回数据。我见过太多Agent项目上线之后黑盒运行出了问题只能靠猜最后耗时几天还找不着根因。日志是技能体系的大实话埋点埋清楚了调优路上能省掉大半冤枉时间。最后分享一个我个人常用的技巧新技能上线之前手动构造十到二十个边缘case在评测集里跑一遍尤其是用户请求里带着情绪词、模糊词、多意图混合的样本。这些case最能暴露技能设计的缺陷。别嫌麻烦这一遍跑完能帮你少看半夜的告警日志、少接几次业务方的投诉电话。技能体系这东西打磨得好是杠杆打磨不好就是负担关键要把每一分力气花在真正影响行为正确性的地方。