1. 从抽象概念到可落地的技能一条务实路线做了几年大模型应用落地我有一个越来越强烈的体感Agent 能不能干活和Agent 能不能稳定地干好活中间隔着的不是模型智商而是技能化程度。所谓 agent-skills我倾向于把它理解为一套围绕智能体构建的技能体系——把原本零散、靠临时写 prompt 拼凑的能力沉淀成可复用、可评估、可组合的结构化模块。这听起来不像什么颠覆性技术但恰恰是 Agent 从演示 Demo 走向生产环境的分水岭。过去我见过不少团队兴致勃勃地搭了一个 Agent让它能查天气、算个题、写段文案感觉万物皆可 Agent。可真到了要做成一个面向特定业务场景、希望它稳定交付结果的项目时问题会瞬间暴露同样的需求换个说法结果可能完全走样多步骤任务做一半就迷路不知道该调用什么能力一个 Agent 里堆了几十个 function调哪个、什么时候调、调完怎么校验全凭模型心情。这些问题都不是换个更强的模型能解决的。真正有效的做法是把技能当作一个独立的工程对象来设计。我在这篇文章里要分享的不只是一堆概念名词而是我自己在项目里反复踩坑、不断修正后沉淀下来的一套方法技能的拆解方式、结构定义、开发流程、测试评估体系以及多人协作时怎么维持 Agent 项目的秩序。无论你是刚接触 Agent 开发的小白还是已经带团队做 AI 应用落地的技术负责人这篇文章应该都能给你一些直接能用的参考。需要先说明的一点是业界关于 agent-skills 并没有一个完全统一的标准化定义。我讲的这套框架本质上是基于大量社区实践、开源项目经验和我自己的工程验证后形成的一种可行解。你可以把它当作一个方法论草稿再根据自己项目的实际情况去裁剪。接下来的内容我会按一条完整的落地路径展开先解决技能到底是什么、为什么值得做然后讲清楚怎么给技能做边界和定义再深入开发一个技能时会涉及的技术选型与实现细节最后聊聊多 Agent 协作下的技能编排以及一个很关键但容易被忽略的话题——技能质量的测试与长期维护。整篇文章都会围绕我个人的项目经验来讲遇到有取舍的地方我会把当时的判断逻辑一并说清楚。2. 什么是技能Agent 能力拆解的最小平凡单位2.1 从一堆 Function 到一套 Skill本质差别在哪很多教程会把技能和函数Function画等号给大模型配一个 JSON Schema 的函数调用让它去查数据库、调 API这就是技能了。从 API 层面讲没错但站在工程视角这两者的抽象层次相差很大。Function 描述的是能做什么而 Skill 描述的是怎么把一件事做成。这就好比你会说一个人会炒菜但会炒菜背后实际上包含了一系列非常具体的子能力怎么备菜、怎么控制火候、怎么调味、怎么摆盘。只告诉模型你有炒菜的能力它依然不知道怎么完成一桌完整的宴席。在真实的 Agent 系统里一个功能完整的函数只是技能的最小底料。一个完整的技能至少包含以下组件组件作用类比技能描述说明这个技能在什么场景下使用、能解决什么问题岗位职责说明书触发条件什么输入、什么上下文才应该激活这个技能工作受理范围参数协议调用这个技能需要哪些输入返回什么结构接口文档执行逻辑技能内部是单次 API 调用还是多步流程作业指导书校验规则技能跑完后怎么判断结果可不可用质检标准失败处理出现错误、超时、结果不合法时怎么办应急预案我见过很多 Agent 项目函数定义了两百多个但 Agent 干活依然一塌糊涂。原因就是只写了参数协议其他组件全部缺失。模型根本不知道在什么场景下优先调哪个函数也不确定调完返回的数据会不会错更别提在出错时怎么补救。2.2 技能粒度查天气是技能吗围绕技能设计大家问得最多的一个问题是技能的粒度到底切多细以天气查询为例如果只做一个get_weather(city)它足够简单但查天气对一个真正的 Agent 任务而言几乎算不上一个可交付的能力。真实需求往往是用户问明天适合出门吗Agent 需要判断用户的出行意图、查天气、结合交通信息、给出建议。这个过程中可能需要调用不同的外部接口并且产出结构化的结论。我总结了一套判断技能粒度是否合适的经验法则技能必须对应一个可验收的产出物。不能只输出一段中间数据要输出一个任务完成级别的结果。技能的边界应该对齐业务心智。用户不会说帮我调一个天气 API用户会说帮我规划明天的出行。前者是函数后者才是技能。技能的复杂度应该有上限。如果一个技能内部的步骤超过 8~10 步就要考虑拆分成多个子技能否则排查问题和复用灵活性会明显下降。拿我做过的一个客服类 Agent 举例。最初我把查询订单和处理售后各做成一个大技能结果模型经常在两种场景里混淆而且 Agent 在售后的多步流程里动不动就半途而废。后来拆成了订单查询退款申请判断退款方案生成退款执行确认四个子技能反而每个环节都稳定了很多。稳定性和技能粒度是强相关的而这个相关性不以技能少、Agent 简单为目标以技能职责清晰、模型好判断为目标。2.3 技能是 Agent 的肌肉记忆回到底层逻辑。大模型的优势是海量的常识和强大的语言理解能力但单靠理解去完成一切任务好比让一个从没进过厨房的天才凭直觉做满汉全席——理论上行实际翻车概率极高。技能体系做的事情是把语感变成肌肉记忆。当模型遇到特定场景时它能快速感知这一步我该动用哪套已定义好的动作序列而不是每次都在脑内重新推理完整流程。尤其是面对阶梯式高复杂度任务时技能化带来的稳定增益会非常明显。一次两次的推理可能有随机性但一套被反复验证过的技能链路是确定性的。Agent 的生产可用性本质上就体现在把不确定性压缩到可控范围。3. 技能设计的第一步先写一份技能说明书3.1 很多项目死于还没想清楚就开始写代码在我参与过的 Agent 项目里开发过程最混乱、最返工频繁的不是因为模型不够强而是因为团队对技能的需求理解不一致。产品经理说做一个能帮用户写周报的技能开发听成了调用一个文本生成接口测试想的是输入关键词输出成段落——最后做出来的东西常常既不是产品想要的也不是用户想要的。后来我强制团队在开发前写一份技能说明书格式固定内容不允许偷懒。它的核心作用是统一对技能边界、验收标准、特殊情况的理解把我以为你说的是什么变成我们都同意这是什么。我做技能说明书常用的结构是技能目标用三句话以内说清楚这个技能完成的是什么任务面向什么用户。输入边界明确哪些输入是这个技能必须的哪些是可选的哪些是它不负责处理的。写清楚超出边界的请求要如何转交或拒绝。输出契约定义结果的结构、格式、信息完整度标准。最好给一个实际的示例输入和示例输出。依赖资源这个技能依赖哪些外部数据源、API、工具以及各自的可用性假设。质量验收标准什么样算做得好什么样算不合格。这条必须能量化或能明确判断否则测试环节无从下手。已知限制与典型失败场景提前列出这个技能一定会遇到什么问题以及当前打算如何兜底。有人觉得做这份文档太耗时尤其在节奏很快的创业团队里恨不得上午说需求下午上功能。但从我的实际经验看在技能说明书上每多花一小时后期能省下至少三小时的联调与返工时间。而且这份文档本身就是很好的新人培训材料、测试用例来源和代码注释的补充。3.2 技能边界什么该做、什么不该做、什么要拒绝技能的边界设计是这份说明书里最难控制的部分。边界划得太宽模型容易误用技能去处理超出能力范围的事边界划得太窄技能的适用场景太少Agent 不得不在大量场景下无技能可用退化为裸模型硬推理。我常用的边界定义方法叫三圈法内圈这个技能绝对擅长、每次都做的核心场景。技能说明里要用最强烈的语气描述引导模型优先调用。中圈有一定相关性但表现不稳、偶尔需要兜底的场景。说明里明确可以尝试使用但结果需要额外校验。外圈明确不负责的场景。说明里直接写请不要使用此技能处理 XX 类问题并给出正确的替代路径。实际操作中内圈和外圈对 Agent 的引导价值最大。模型对外圈描述的反应往往很好因为明确的不要做什么比做什么更容易在 embedding 空间里形成区分。中圈描述在 prompt 过长时容易被忽略所以尽量合并精简。3.3 输出契约模型说的话必须变成系统能用的数据在传统开发里一个接口的返回结构是强制的字段缺失、类型不符都会导致调用失败。但在 Agent 场景里模型输出的结构稳定性非常值得重视。同一个技能运行十次模型可能给出十种措辞、三种字段顺序、两种空缺格式。因此在技能说明书里就要把输出契约定义得非常死板。我通常这样做明确强制字段和非强制字段给每个字段一个类型定义和取值范围提供一段理想输出作为标准样例写进 prompt 让模型模仿。这里有个很实用的技巧在技能说明书中放入一个与真实任务贴近的 few-shot 示例而不是抽象的 JSON Schema 描述。模型对示例的跟随能力远强于对规则文本的跟随能力。我甚至在部分场景里会把示例输出直接做成模板让模型在这个模板上填空而不是自由发挥。这个改动带来的稳定性提升比我预想的大得多。4. 技能的开发与实现从选型到细节4.1 技能载体选型Function Calling、代码内嵌还是独立服务技能最终以什么形式落地是我的技术选型里比较纠结的一环。根据项目规模不同可以划分为三种情况先说结论小项目用 Function Calling 最省事中大型项目建议把技能独立成服务或模块。形态适合场景优点主要痛点Function Calling技能数量少10 个、逻辑简单开发快和模型交互直接技能多了之后描述文本过长、上下文膨胀代码内嵌函数技能逻辑与主流程耦合度高、依赖内部状态调用开销小调试直接协同时容易互相污染边界容易模糊独立技能服务技能数量多、或技能本身有较重计算/多步链路可独立部署、独立扩缩、独立监控需要处理服务间通信与鉴权开发量增加我在一个中大型项目里最初把所有技能都堆在 Function Calling 里模型工具列表一度超过 40 个。那时候 prompt 里工具描述占了大半 token模型抉择困难经常在相近技能之间选错。后来把核心技能拆成独立服务Function Calling 只保留一个轻量级的技能路由调度器情况立刻好转。这个调度器执行器的分离思路我后面还会详细讲。4.2 技能描述怎么写才有效模型视角的说明开发者常犯一个错误把技能的描述写得像给同事看的 API 文档充满术语和字段名。那个描述实际上是说给大模型听的而大模型不是一个优秀的软件使用者它是一个语言理解者。它理解的是意图不是字段映射。因此技能描述最好用自然语言写清这个技能要解决的人类问题是啥在什么情境下出现时去调用它不应该在什么情境下调用它。举个例子。假设要给 Agent 做一个查询用户积分的技能差的描述是GET /api/v1/user/credit 查询用户积分余额好的描述是用户询问自己有多少积分、积分能换什么、兑换记录的时候用这个技能。注意只处理查询类请求如果用户要求下单兑换实物商品不要使用这个技能应该转交商品兑换技能。描述的核心是情境识别不是接口说明。模型拿到描述后先做的是语义匹配匹配的是情境而不是字段。这个认知转变让我优化的许多技能就靠描述重写不改任何代码效果都有明显提升。4.3 多步技能如何防止 Agent 在中间环节迷路不少技能内部其实是一个多步骤流程。比如生成一份周报并发送给指定人至少包括收集数据、组织内容结构、撰写草稿、检查格式、定位收件人、发送邮件、确认发送成功。让模型一口气完成全部步骤很容易走一半就停或者跳过某个关键校验。我的做法是把多步技能改造成内部分层控制外部统一暴露。外部看是一个技能内部其实是一个小型状态机Agent 判定进入该技能技能服务接收任务上下文逐阶段执行每个阶段有独立的子 prompt 或代码逻辑阶段间传递结构化的中间产物全部完成后统一返回最终结果。举一个实际做过的场景发票报销单审核 Agent。它的审核报销单技能内部大致有五个阶段票据要素提取、合规规则匹配、金额核算、风险标记、出具审核意见。每一阶段我都对应一个独立函数并且规定阶段与阶段之间必须传递规范化 JSON。如果中间某一步输出数据格式不对流程立刻终止并进入人工兜底流程而不让脏数据一路流到最终结论里。这样设计之后审核结果的可审计性和稳定性都有了质的提升。4.4 参数提取的可靠性比想象中更关键的环节Agent 调用技能时参数的提取尤其是从用户自由文本里提取经常是最大的不稳定点。用户说帮我查一下上个月和这个月的支出技能接口可能要求 start_date 和 end_date。模型能不能准确把上个月解析成具体日期区间直接决定技能能不能正确执行。我积累了几个提升参数提取可靠性的细节把日期、金额、数量这类可结构化的信息在描述中给出解析规则。比如规定所有时间相关参数一律换算为 YYYY-MM-DD 格式并注明时区。对关键参数提供缺失兜底值。比如用户没说年份让模型默认取当前年并在结果中提示用户该假设。对参数做二次校验。代码层面检查日期是否合法、数字是否大于零、枚举值是否在范围内。永远不要盲目信任模型提取出来的参数值这是我在生产事故里学到的深刻教训。有一次我们的车票查询 Agent 把用户说的今天下午三点解析成了凌晨三点导致推给用户的建议完全错误。问题不在模型笨而是我们没有在参数层面对时间段做合理性校验。后来加了一个简单规则如果时间的语义与地点属性存在冲突比如深夜出现的车次查询触发提示确认机制错误率立刻降了下来。5. 技能编排多个 Agent 之间怎么协同5.1 单 Agent 包打天下劝你尽早放弃很多刚接触智能体的团队习惯把所有技能塞进同一个 Agent 里觉得反正模型都能调。等技能数量超过 15 个效果一定会出现明显下降。模型面对超长工具列表时选择准确率会走下坡而且对话上下文里充斥着与当前任务无关的技能描述会稀释注意力。我现在的项目里普遍采用多 Agent 技能路由的架构一个主管 Agent 不负责具体执行它只做两件事——理解用户意图、把任务分发给正确的 Agent不同的专业 Agent 各自维护少量专属技能技能列表控制在 5~8 个先把调用准确率稳住。5.2 技能路由策略意图识别与动态优先级路由是整个架构里最微妙的部分。最初我把它做成让主管 Agent 在一份全量技能目录里做一次文本匹配结果发现效果并不好模型会基于表面词面去匹配而不是基于语义场景去匹配。查物流和查订单在文字上重叠度高模型经常选错。后来我改用意图分类技能绑定的方式预先定义好约 20 种常见用户意图每类意图绑定一个默认技能当用户的输入落在多个意图的模糊地带时再用一个追问确认路由。这个改动看着简单但效果很明显——把让模型选变成让模型在有限的选项里做判断准确率好把控得多。5.3 技能的冲突处理与降级路径多技能场景不可避免会遇到冲突用户的需求同时命中两个技能或者一个技能链路上某个依赖服务挂了。技能编排时必须把降级路径当成一等公民来设计而不是事后补救。我在架构里定义了这样的降级优先级优先用备用技能替代比如主搜索技能挂了用备用的垂直搜索技能顶上其次用简化流程兜底多步技能退回单步查询只返回最核心的信息最后用人工接管作为终态出口明确告诉用户当前能力受限无法完成并保留上下文交给人来处理。降级路径最好用确定性代码去实现而不是依赖模型临场发挥。系统检测到某服务不可用时直接按预设路径切换不要让模型去随机应变。模型在异常状态下给出的方案通常频率不稳定风险不可控。6. Agent 技能的测试与质量评估没有评测就没有改进6.1 传统测试方法在 Agent 技能上的失灵做传统软件开发时我们习惯写单元测试断言函数的输入输出关系。但技能测试没法这么干——同一个输入模型两次输出可能措辞不同但都不能算错而另一个输入前后只差一个标点结果可能走向两个相反的结论。我一开始试图给技能写严格断言后来发现失败率惊人不是结果差是断言方式不对。技能测试真正该测的不是精确答案而是关键维度上的边界与底线。6.2 我用的技能评测方法三层校验在项目实践里我总结出三层校验法来判断一个技能的好坏第一层结果完整性校验。技能返回的结果结构上是否完整关键字段有没有缺失必要内容是否都覆盖。这层可以用代码自动断言。第二层语义合规校验。结果的语义是否与任务目标一致。这层通常需要借助一个评估模型LLM-as-a-judge做参考人为设定评分标准比如是否包含关键决策依据是否回避了敏感表述。第三层真实效果校验。放到真实用户场景里跑观察任务完成率和用户反馈。这是最耗时但最有说服力的测试。6.3 构建你的技能回归测试集技能像代码一样修改一次就应该回归测试一次。我会为每个技能维护一个测试集里面通常包含30~50 条覆盖不同子场景的输入20 条边界输入边界内外各半10 条对抗输入故意模糊的表述、缺少关键参数的输入、用户意图反转的输入5 条崩溃输入包含极端字符、超长文本、多语言混杂等。每次调整技能描述或调用逻辑先把整个测试集跑一遍输出一份对比报告确认修好 A 问题的同时没有破坏 B 场景后才允许上线。这个方法虽然简陋但已经是保证 Agent 项目长期稳定最管用的手段了。6.4 评测中的隐忧与纠偏用 LLM-as-a-judge 做评估有一个隐忧评估模型本身也会有偏好和盲区。比如它倾向于给措辞更流畅的结果打高分有时和真实业务标准不一致。我处理这个问题的办法是在评测 prompt 中给出业务标准作为对照而不是让评估模型凭空评价。比如对报销审核技能我会把公司的报销规则原文贴在评估 prompt 里让评估模型按规则一项项核对而不是让模型凭常识说看起来合理。同时定期抽出一部分评测样本由人工复核找出评估模型和人工判断的系统性偏差。7. 上生产之后成本、监控与长期维护7.1 Token 消耗的隐性膨胀点技能化之后Agent 的 token 消耗会明显增加因为每个技能描述、示例、中间结果都要占用上下文空间。很多团队上线前没算这笔账上线后账单一出来才傻眼。我的控制方法技能描述按信息密度最大化、字数最小化标准反复精简能用三十个字说清的不用五十个字只在必要时给技能附带 few-shot 示例常用轮次从 3 个示例降到 1 个调用阶段结束后立刻清理非必要上下文避免中间结果长时间占用窗口对高成本技能做配额控制比如同一对话内最多触发三次某种重度技能超出则改用轻量替代方案。7.2 可观测性技能链路的数据留着干嘛上生产后的 Agent 必须做全链路日志而且日志要能回答这几个问题用户最终意图被路由到了哪个技能技能执行过程中每一步的参数和返回值是什么哪一步耗时最长、失败最多输出结果有没有触发过兜底逻辑把这些数据沉淀下来不仅是为了排查事故更是为了持续改进。我每个月会把日志里累计出现的高频失败场景汇总一遍集中优化技能描述或调整流程设计。日志是技能的显微镜没有这层数据优化全靠猜。7.3 维护意识技能是易腐品不是一次成型技能上线之后不等于可以躺平。外部 API 会变、用户表述会变、业务规则会变技能的生命周期管理必须排上日程。我的团队会为每个技能标注三个状态健康最近一次评估通过、需观察边缘场景准确率下滑、废弃业务已下线。每月给所有技能做一次健康体检跑一遍回归测试集检查真实使用数据里的完成率和人工接管率。发现某项指标连续两个周期下滑就启动技能优化专项绝不拖延。等到用户明显觉得 Agent 变蠢了再去修修复成本高得多口碑损失也难以追回。8. 节流给 Agent 减负的技巧清单这节的内容更贴近踩坑后的经验总结我把最常见的隐性减速来源和相应处理方式列成一张表方便你自检项目里有没有同类问题常见问题典型表现处理方式技能描述太长模型选择技能时间明显变长精简描述描述只留触发情境 关键边界工具列表冗余无关技能也占据上下文按意图分组只向路由 Agent 开放当前可能用到的技能多步技能内部重复调用模型每步一次大模型推理延迟叠加把固定逻辑挪到代码层仅关键决策用模型上下文历史无上限对话越来越长响应越来越慢设计上下文裁剪策略保留摘要 关键事实技能内部无缓存同类问题重复调用外部服务对高频技能设计简单缓存层按用户与参数维度命中其中多步技能内部重复调用模型这一项是很多新手最容易忽略的。不少开发者的第一直觉是让模型一步步决策看起来灵活实际延迟居高不下而且每一步都有概率出错错误还会逐级放大。能够用确定性代码表达的流程不要因为贪图灵活而交给模型反复推理。模型的正确用法是在需要语义理解和语言生成的地方介入其余环节越机械越好。9. 团队协作多人开发 Agent 技能时怎么保持秩序当 Agent 项目从一个人扩展到一个团队时最大的问题往往不是技术而是协作规范。几个工程师同时往一套技能体系里加东西Git 冲突还是小事真正头疼的是技能命名混乱、职责重叠、个人风格差异导致的体系腐化。我几个比较关键的经验第一技能命名要像命名公共 API 一样严肃。统一采用领域_动作_对象的结构。比如finance_query_invoice、hr_verify_attendance这样排序、搜索、路由都很顺。不要出现get_data、process_info这类没有任何语义区的名字。第二每个技能必须且只能有一个 Owner。技能出现问题从排查到修复到决策是否下线都应该由 Owner 负责推动。多人都有改一个技能的权限最终一定会变成没人负责。第三技能上线要经过 Review。我把技能 Review 分为三关产品关需求对齐、技术关实现与描述合规、数据关用预置测试集跑一遍准入评估。三关都过技能才能进入生产环境。第四技能的变更要走变更记录。哪怕只是改了一句描述也记录下来改动时间、原因、影响评估一并留痕。否则一个月后效果下降你根本不知道是哪次改的哪个描述出了问题。协作体系看起来很重但一旦技能数量超过 30 个流程的约束力就会从负担变成保护。没有这套秩序项目越叠越乱最后必然面临整体返工。10. 写在最后的个人体会从最早一股脑把所有函数塞给模型的莽撞期到现在沉淀出这套围绕 skill 定义、路由、测试、维护的方法论中间最痛的一条教训是Agent 能力的上限不由模型参数数量决定而由技能的工程化成熟度决定。模型提供的是骨架和智力底座技能体系才是让 Agent 真正长出肌肉和神经的那个部分。如果你正准备入局 Agent 项目我建议先别急着堆功能花一周时间把核心业务场景里的三五个技能好好做透定义清楚、描述写好、测试集建起来再慢慢往外扩。Agent 项目没有一个做完的时刻它是一个持续演化的过程。保持对技能质量的敏感、对用户反馈的敬畏、对数据事实的尊重这条路就能越走越顺。最后分享一个实操技巧当你觉得一个技能在场景里表现不稳定先不要急着改代码把技能的描述原文拿出来重新读一遍问自己换成一个小白看到这段描述他会在什么情况下调用它这个简单的问题已经帮我修好了大量看起来是模型问题、其实是描述不清的疑难杂症。希望这条经验也能给同样在 Agent 落地上挣扎的你帮上忙。