刚复盘完手上这个Agent项目突然想把“agent-skills”这个主题好好聊一聊。原因很简单最近大半年我看了太多团队把Agent做成了“高级if-else”凡是遇到任务就写死一个工具调用链模型层面根本没体现出任何“能力组合”的意思。真正让我觉得值得记录的是当我把技能skills从概念变成一套可拆解、可度量、可复用的体系之后整个Agent的稳定性、可维护性和效果上限都发生了质变。这篇内容我打算从一个实际落地者的角度把agent-skills这件事彻底掰开揉碎讲清楚技能与工具调用的边界、技能描述怎么写模型才“看得懂”、参数契约和校验链路为什么是生产环境的生死线以及多技能并发时系统应该如何决策。无论你是正在做AI Agent应用开发还是只是想把大模型的能力真正沉淀成团队资产这篇都值得你花二十分钟认真读一遍。1. 技能体系与工具调用一字之差天壤之别很多团队第一版Agent都是这么起步的定义几个函数把函数列表塞进system prompt然后让大模型自己决定调用哪个。跑demo的时候效果惊艳一上生产就崩盘——要么模型选错工具要么参数传得离谱要么面对稍微复杂的任务直接逻辑断裂。问题出在哪出在大家把“技能”和“工具调用”混为一谈了。1.1 从“会调接口”到“会做事情”的质变工具调用的本质是模型在给定选项里做一个“选择加填参”的动作。它的核心是API契约输入什么、输出什么模型只需要按格式执行。技能则完全不是一回事。技能是一段可以被模型理解、被系统执行、被结果验证的完整能力单元它包含明确的目标、适用范围、输入输出契约、执行路径、错误处理策略和成功判定标准。用一个生活化的类比工具调用像是给一个实习生一张“电话清单”告诉他用户要订机票就打航司电话要订酒店就打酒店电话。他能完成任务的前提是需求刚好落在清单上而且流程完全标准化。技能则是你教会这个实习生“出行规划”这件事本身——他得知道用户出差要考虑预算、时间、偏好得知道订票之前先确认行程得知道航班取消该怎么改签甚至得知道什么情况下该请示上级而不是自作主张。放到Agent场景里这个差别直接决定了天花板。工具调用只能做单点动作技能却能承载“把一个任务闭环做完”的完整逻辑。我见过最典型的反面案例某团队给Agent接了十几个API包括天气查询、日历读写、邮件发送结果用户说“帮我把明天的会议改到下午三点顺便通知参会人”Agent直接懵了——它不知道该先改日历再发邮件也不知道发邮件之前要先生成会议变更的正文内容。这就是典型的“有工具没技能”。1.2 技能的三个核心属性目标性、可复用性、结果契约要判断一个能力单元是不是合格的技能我不看实现方式只看三个属性。首先是目标性。每个技能必须能回答一个问题它为用户或系统达成什么目标比如“sendEmail”不是技能“通知参会人会议变更”才是技能。前者的粒度是动作后者的粒度是目标。区别在于目标导向的技能实现可以动态变化——可以用邮件通知也可以用IM消息甚至可以用短信只要目标达成即可——而动作导向的工具只有一条路走到黑。其次是可复用性。技能不能被绑死在单一场景里。“翻译文档”这个技能可以在阅读论文、处理合同、回复外籍客户邮件等多个场景中被调用这才叫可复用。如果某个技能换一个场景就失效说明它的边界定义出了问题得重新拆解。最后是结果契约。这是我在所有项目里最强调的一条技能执行完系统必须能判定“成功还是失败”而且这个判定不能依赖模型自己说了算要有客观的校验逻辑。比如技能是“查询订单状态”结果契约就是“返回结构化订单状态字段且状态值在约定的枚举范围内”。校验通过才算成功否则必须走重试或降级路径。1.3 为什么会有人把Agent做得像“高级if-else”我在技术社区看过不少Agent项目也帮几个团队做过代码评审发现大家把Agent做成高级if-else的原因惊人一致图省事。直接让大模型在一长串函数列表里做function calling是最快能让demo跑起来的方式。但demo跑起来之后问题就开始了。函数列表超过二十个模型的选择准确率显著下降——这不是玄学是语义距离问题。当“发送周报”“生成周报”“汇总周报数据”三个函数名字相似又有细微差别时模型经常选错。用户提一句“帮我把本周的工作内容整理一下发给领导”模型可能直接调了“生成周报”就结束根本没执行发送动作。反观用技能体系来设计我们把“周报自动发送”定义成一个完整技能内部包含内容生成、格式检查、收件人确认、发送执行、结果确认五个环节模型只需要理解一个入口目标是完成周报的自动发送。剩下的细节全部封装在技能内部。另一个原因是对模型能力的过度信任。很多人觉得大模型理解能力强给个schema就能填对参数。实际曝露的是大模型对参数值的“编造”倾向非常顽固它会在订单号字段里填写一个不存在的ID会在日期字段里填“明天”而不是具体的2025-01-15会在金额字段里缺单位。如果没有技能层的校验与修正机制这些幻觉参数会直接打穿下游系统。关于这部分后面我会专门展开讲校验链路的设计。2. 拆解一个可落地的技能从需求到接口契约技能体系的第一步不是写代码而是做技能清单盘点。我强烈建议在动手之前先把你希望Agent具备的能力全部列出来然后逐一判断哪些是单步工具调用就能解决的哪些必须做成完整技能。这决定了整个架构的复杂度。2.1 技能清单盘点先列你会做什么再谈你会用工具做什么我习惯的盘点方法分三层域、能力、动作。域代表业务范围比如“客户管理”“订单处理”“内容生产”能力是域下的子能力比如“客户管理”下可以有“客户分群”“客户触达”“客户健康度评估”动作则是具体执行选项。盘点的核心判断标准是如果一个“能力”只需要执行一个原子动作就能完成那它就是工具而非技能。例如“查询客户联系方式”是动作“根据用户一句话生成客户触达计划”才是技能。盘点过程中最容易犯的错是“能力想象得太大”。我见过有团队把“市场分析”直接定义成一个技能结果实现的时候发现里面既有数据采集、又有竞品研究、又有报告生成根本没法用一个入口承载。正确的做法是把这种大能力拆成技能组由编排层负责任务规划把大目标拆成多个技能的调用序列。技能本身保持“单目标、可判定、可复用”的最小完整单元这是我一直坚持的原则。2.2 技能描述的设计让模型“看得懂、选得对”技能清单定完之后下一步就是写技能描述。很多团队在描述上偷懒直接用一句话带过比如“生成订单摘要”。这句话看似明确但模型并不知道订单摘要要给谁看是要简洁版还是详细版需不需要包含退款信息要不要附带物流状态我推荐一个技能描述的“五要素”框架目标、触发条件、执行流程、输入、输出。目标描述技能存在的意义触发条件描述什么情况下该调用这个技能执行流程描述技能内部会经历哪些关键步骤输入定义参数契约输出定义结果契约。用前面“订单摘要”的例子好的描述应该是“当用户需要查看订单核心信息时生成结构化摘要包含商品明细、金额、状态、物流节点输出为JSON格式金额需同时给出原币种金额与折算金额。”这里有个实操技巧描述里要刻意放入“排除条件”。比如“本技能适用于已完成支付的订单查询未支付订单请调用支付引导技能”。为什么因为大模型在技能选择阶段非常容易“过度套用”给它一份订单摘要技能它恨不得把所有订单类问题都往里面塞。清晰的排除条件能大幅降低误选率。我在多个项目里验证过加上排除条件后技能选择的准确率能提升五到八个百分点。还有个关键细节技能名称要和描述保持语义一致。我常用“动词业务对象目的”的命名法比如“generateOrderSummaryWithLogistics”而不是“order_summary”。后者在模型语义空间里太模糊前者则能让模型快速定位到“这是要生成、对象是订单、并且带物流信息”。不要小看这个细节在几十上百个技能并列时名称就是第一层筛选器。2.3 参数契约与校验LLM填的参数不能直接信参数契约是技能设计中最不被重视、却最致命的部分。你可以把大模型理解成一个“母语使用者但不太负责任的外包人员”——你让它填一个日期它不一定填成标准格式它可能填“下周”可能填“2025年1月15日”如果prompt里没规定它甚至会填“明天晚上六点左右”。这在对话里没问题但若直接透传给订单系统、日历系统或数据库查询就是灾难。我的经验是把参数校验做成技能内部的强制逻辑而不是依赖模型自觉。具体分四步第一步是类型强制校验。凡是枚举值参数比如订单状态、客户等级、通知渠道必须在schema里明确枚举范围并在运行时校验模型填的值是否在范围内不在就拒绝重来。第二步是格式规范化。日期、时间、金额、手机号、邮箱等有标准格式的字段用解析器做规范化处理比如把“明天”解析成具体的date对象把“下午三点”解析成14:00或15:00需要考虑用户语境这一步尽可能用确定性代码完成而不是让模型自行处理。第三步是数值合理性校验。金额不能为负、时间不能早于当前时间、手机号要符合位数规则这些规则全部写入校验逻辑。第四步是必填参数检查。技能定义时标出哪些参数是必需的、哪些是可选执行前先检查漏项漏了就向模型或用户发起缺参追问。这套机制我称之为“契约锁”。它最重要的作用不是防模型错误——错误防不完——而是把错误拦截在系统副作用发生之前。我自己经历过最痛的一次Agent生成的参数把客户ID填错了结果系统给一个完全不相关的账户发送了敏感通知后续排查和补救花了好几天。从那以后任何技能的参数都必须过契约锁没有任何例外。3. 技能的三层实现路径提示词、API、代码逻辑技能设计好了具体怎么实现按我的经验技能落地的路径大致分三层每一层的适用范围、心智成本、维护成本都不一样。选对了路径能省掉大量无效工作。3.1 提示词技能适合轻量化任务第一层是纯提示词技能也就是把一套稳定的prompt模板固化成技能。这类技能适合那些不需要外部数据、不触发系统副作用、只靠模型自身能力就能完成的任务。比如“提炼会议纪要待办事项”“把技术术语改写为通俗表达”“给一段代码生成单元测试场景列表”——这些任务的输入输出都发生在文本层不需要调用任何工具也不产生系统状态变更。提示词技能的核心价值在于“策略沉淀”。同一个任务普通用户写prompt和资深工程师写prompt效果差异很大。把最优的prompt策略锁定成技能就能保证每次执行的质量下限。我通常会为这类技能配置多轮自校正机制模型先给出初版结果再让模型根据预设检查清单对初版结果做复核与修正。这样做能让文本类任务在零外部依赖的条件下提高不少稳定性。但提示词技能有个显著短板它无法与真实系统交互。凡是涉及到查询数据库、调用外部API、写文件、发消息的操作型需求纯提示词都满足不了。所以这类技能在真实生产Agent里占比一般不超过百分之三十更多是作为“能力杠杆”存在。3.2 API技能标准化的外部能力接入第二层是API技能也是目前Agent应用里最普遍的形式。所谓API技能是把一个或多个外部服务接口封装成“有业务语义”的技能单元。等到集成阶段要做的事情是对API能力和技能定义之间的缝隙做填补——例如一个“查询天气”API只有“城市名日期”两个入参但技能定义里允许用户用“北京明天会不会下雨”这种自然语言提出需求这就需要技能内部有一个意图解析与参数映射过程。我建议API技能封装时至少做三件事。第一参数映射层要独立于API实现。因为大模型输出的参数是“语义参数”比如“明天”“上海”而API需要的是“2025-01-15”和“101020100”中间的翻译必须用代码逻辑完成。第二要对API的响应做变形与标准化。不同API返回的数据结构千奇百怪技能对外暴露的结果契约却必须是统一的。第三要处理API失败场景。状态码异常、超时、限流、数据为空这些情况技能内部要先兜住再决定是重试、降级还是向上抛错。3.3 代码技能把确定性逻辑锁死在工具内部第三层是代码技能也是最容易被忽视但往往最有用的一层。代码技能的本质是把那些完全不需要模型发挥创造力的确定性逻辑封装成独立可执行单元。比如“计算两个日期之间的工作日天数”“把金额按汇率折算并返回JSON”“对一段文本做敏感词过滤”——这些逻辑如果在Agent链路里每次都靠模型生成或理解不仅慢、贵还存在随机出错的风险。我为什么强调这类逻辑必须锁死在代码里举个实际例子。有一次我们做财务场景的Agent需要根据用户收到的费用凭证自动归类入账科目。模型做语义理解没问题但具体到“这个发票是办公用品还是差旅费用”不仅涉及发票品名、还涉及费用金额阈值、部门属性等多维规则模型如果每次都靠猜必然出错。后来我们把归类规则全部写成了代码技能模型只负责从自然语言里抽取结构化要素剩下归类全部由确定性规则完成。准确率直接拉满而且链路耗时和时间成本大幅下降。所以我的建议是凡是“规则可写死”的任务都优先考虑代码技能。让模型只做它最擅长的事情——语义理解、意图判断、内容生成——其余交给确定性代码。这种“模型做决策、代码做执行”的分工是整个Agent技能体系稳定性的根基。4. 技能编排当多个技能同时可用时系统如何决策技能做多了之后真正的复杂度才浮现出来Agent面对一个真实任务时该调用哪个技能多个技能都能响应时怎么办技能和技能之间如何传递上下文这一章我会重点讲编排层的设计。4.1 技能路由与优先级设计技能路由是编排层的核心。路由的本质不是让模型在“所有技能”里自由选择而是提前建立一张“技能索引表”并辅以必要的筛选机制。我常用的做法是“多级路由”策略。第一级是领域过滤根据用户意图命中的业务域直接筛掉无关技能比如用户聊的是订单问题就只在订单域内做路由。这能大幅缩小模型的决策空间提升准确率。第二级是语义匹配把剩余技能的描述和用户请求做相关性排序取top-k。第三级是规则仲裁如果多个技能相关度接近就根据预设优先级决定谁先被尝试——比如“查询信息类技能”优先于“生成内容类技能”因为信息类动作副作用小、执行成本低。需要强调的是路由层不能完全依赖模型打分。有规则的场景尽量用规则。比如用户请求里出现“退款”字样且订单状态字段存在就直接路由到退款流程出现“投诉”字样直接路由到客诉工单创建技能。规则兜底加模型匹配两条腿走路才稳。4.2 链式技能与组合技能的取舍场景真实任务往往不是单个技能能完成的。用户说“帮我分析一下上个月的销售数据并生成一份给管理层的总结报告”这里面至少有“数据查询”“数据分析”“报告生成”三个技能。编排层需要支持链式调用。我在设计链式调用时有几个原则。第一尽量把链路设计成“前一个技能的输出恰好是后一个技能的输入”。这就要求技能的结果契约在设计阶段就考虑上下游衔接。比如“数据查询”技能的输出必须是结构化的表格数据而不能是模型的一段总结文字——否则“报告生成”技能就无法可靠地消费它。第二链路中尽量插入“路由确认点”。比如数据查询完成后编排层先展示查询结果给用户确认再进入报告生成环节。这一步不是画蛇添足而是为了及时打断幻觉的传导如果查询结果本身就是错的后面再生成报告只会错得更远。第三链路深度需要限制。经验值上单次任务内链式调用最多五到八个技能超过这个数错误率和时延都会指数级恶化。如果任务真的复杂到需要更多步骤建议拆成多个子任务分轮执行每轮之间重新修正计划。组合技能则是另一种形态多个技能并行执行结果汇聚后统一处理。比如“市场调研Agent”同时调用“搜索竞品新闻”“抓取社交媒体热词”“查询行业报告”三个技能最后汇总。组合技能的关键是结果汇聚层的合并逻辑要定义清楚——是简单拼接、结构化合并还是需要再做一轮模型综合。4.3 技能运行中的上下文管理与成果沉淀最后一个编排层问题是上下文管理。技能调用过程会产生大量中间数据如果不做隔离和沉淀很快就会把上下文窗口塞爆或者让模型在后续决策中被无关信息干扰。我的实践方案是“技能沙箱”加“共享黑板”。“技能沙箱”指的是每个技能执行时只允许读取自己的输入参数和自己有权访问的数据域不直接看到用户的完整历史。这既保护了上下文空间也降低了误读概率。“共享黑板”则是技能之间交换成果的公共区域技能A的输出如果满足契约就写入黑板技能B能从黑板里拉取自己需要的数据。这样既能控制上下文规模又保证了链路上下游的数据衔接。上下文沉淀还有一层提示词层面的技巧当一个技能执行完成后编排层把结果的关键摘要写回对话记忆而不是把技能输出的完整原文直接塞进历史。比如“订单查询技能”输出了一大段JSON最终回写到对话历史里的应该只是一句“已完成订单查询订单号ORD-2025-001状态为已发货预计1月18日送达”。这样既保留了用户可感知的信息又避免大块结构化数据污染后续语义。5. 实测中的常见问题与调优经验技能体系建好之后真正的考验来自生产环境。下面这些问题全是我在真实项目里踩过的坑每一条都有对应的调优思路。5.1 幻觉参数校验链路必不可少幻觉参数是技能体系里出现频率最高的问题。模型在对话里言之凿凿地给出一个订单号、一组金额或一个日期结果查无此单、金额错位、日期不存在。这类问题在设计阶段如果没上契约锁运行阶段就只能靠人为审计去发现代价非常大。我的调优经验是双重校验第一层在参数进入技能执行前做第二层在技能执行后做结果合理性校验。前者的逻辑前面已经讲过了后者常常被忽略。举例一个“提交退款申请”技能执行前参数校验一切正常但下游API返回“退款金额超过原订单金额”的错误。结果层的校验就要能识别这种业务异常并把错误转换为Agent可理解的反馈——比如“退款金额不应超过订单实付金额请重新确认”而不是把一段裸的API异常JSON丢给模型。结果校验逻辑要写在技能内部编排层收到的不应该是“报错”而应该是“结构化失败原因可执行建议”。5.2 技能冲突多个技能都能响应该如何收敛另一种高频问题是技能冲突。用户一句话触发多个技能同时明确可响应比如“帮我把苏州出差的行程安排一下”——既可以用“出差行程规划”技能也可能触发“酒店预订”技能甚至“火车票查询”技能。如果路由层不做冲突消解模型就会随机选一个或连续触发多个给用户完全不可预期地跑偏。处理方式分两层。第一层是路由层消解优先级规则要覆盖常见的业务重叠场景。以出差为例优先触发“行程规划”整体技能在其内部再按需编排“酒店”“车票”等子技能而不是让它们在同一个路由平面里并列。第二层是执行层确认如果路由层无法确定就向用户抛出选择项——“请问您是需要完整的行程规划还是只需要其中的酒店预订”一次确认的成本远低于跑错链路之后返工的成本。5.3 失败重试与降级策略生产环境刚需生产环境的真相是外部服务不稳定是常态API超时、限流、网络抖动、数据源宕机都会发生。Agent技能体系如果对失败没有预案用户感受到的就是“机器人突然不说话了”或“机器人报了一句看不懂的错误”。我的失败处理策略遵循三级降级第一级是技能内部重试针对可重试的瞬时错误超时、限流做最多两次指数退避重试。第二级是技能内部替代路径比如主查询API挂了就切换到备用数据源主生成模型不可用就降级到更小但稳定的模型。第三级是编排层降级技能整体失败时编排层要能回退到“人工兜底”或不执行副作用动作同时用明确的自然语言向用户解释当前状态而不是让用户面对一条冰冷的失败码。这里有个非常容易被忽略的细节降级策略要在设计阶段就写在技能描述里而不是等运行阶段才补。比如技能描述里明确写“当主数据源不可用时尝试备用数据源若均失败则返回结构化错误并建议用户稍后再试”模型执行意图会更坚定不会在失败时自作聪明地编造数据替代真实查询结果。模型在失败场景下的编造倾向比正常场景高出很多必须用约束条件顶住。6. 技能可观测性与持续迭代路径技能体系不是一个一次性建设完就能躺平的系统需要一整套观测、评估和迭代机制否则只能知道“Agent不好用”却不知道“到底哪个技能拖了后腿”。6.1 技能调用链的全链路追踪别等用户投诉才排查每个技能的每次调用都应该落日志。日志至少要覆盖以下内容技能ID与版本号、输入参数快照、路由决策原因、执行耗时、中间步骤关键输出、最终结果、失败原因分类。链路追踪的要求是用户的一句话到最终的技能执行每一步都可回放。实现上可以用一个traceId贯穿全链路在关键节点埋点上报。这个层面的投入回报是巨大的。以前团队查Agent问题靠用户录音复述“当时它跟我说了什么”接入全链路追踪后直接看日志链路就能定位是路由选错、参数幻觉、外部API异常还是结果校验失败。我强烈建议在技能体系上线第一天就把观测打点做上补测的成本远高于首日埋点的成本。6.2 技能基准集用回归测试守住效果下限技能迭代最怕的是“改好一个、改崩一片”。比如你优化了“报告生成”技能的prompt结果发现某些场景下技能行为变了连累了下游“数据分析”技能的效果。要规避这个问题就需要一个技能基准集。基准集的形式是“输入-期望行为-关键约束”三元组集合。每个技能维护几十到几百条典型case和边界case。每次技能调整后自动跑一遍基准集比对结果是否符合预期。关键约束可以包括输出格式是否合法、关键字段是否准确、是否误用了其他技能、是否规避了敏感行为等。这个机制最大的意义是让优化不再是玄学——我们可以明确地说“这版改动让准确率从89.2%提升到92.7%”而不是“感觉变聪明了”。6.3 技能版本的平滑升级别把灰度发布落下技能体系必然要迭代迭代就涉及版本管理。技能的prompt、参数schema、代码逻辑一旦变化线上行为就可能变化。因此技能版本管理和灰度发布不可省略。我的做法是每个技能都有独立的版本号线上Agent锁定在一个技能包版本上新版本上线前先在基准集上跑分再按流量比例灰度。灰度期间实时看调用成功率、失败分布和用户反馈稳定后再放全量。如果线上某技能出问题还能一键回滚到旧版本。这个机制看起来“重”但在生产环境里能避免大量事故——我有一次就因为在调优一个技能prompt时没做版本隔离结果新prompt在十个场景里有一个崩了全量用户跟着受牵连排查时连“之前是什么行为”都很难复原。技能体系的建设最终追求的就是这种“每个环节都可控、每次改动可验证”的工程状态。它不是一次性的开发任务而是一个伴随业务持续演进的能力底座。我自己做完这套体系后最大的感受是Agent应用真正的分水岭不在模型选得多强而在技能体系能不能把模型的智能稳定地兑现成用户可感知的确定性价值。如果你恰好也走在Agent落地的路上希望这篇实操笔记能帮你少踩几个我踩过的坑把技能体系一步建扎实了。