1. “agent-skills”到底是什么——先把这个概念拆清楚1.1 一个翻车案例让我重新审视“技能”上个月在给一个客户做基于大模型的企业知识库问答 agent 时我犯了个典型的错误一股脑往 agent 里塞了十几个 API 工具包括查天气、查汇率、算运费、查库存……结果系统跑起来之后模型经常把工具搞混。用户问“上海到北京的运费是多少”它先调了天气接口然后煞有介事地给出一堆毫不相关的数字最后告诉用户运费需要咨询客服。你说它错了吧它流程走得挺完整你说它对了吧结果完全没法用。后来我把这些工具砍到只剩三个重新组织成真正的“技能”效果立刻翻倍。这次踩坑让我意识到一个很重要的点agent 的能力边界不在模型而在你怎么把“工具”变成“技能”。聊 agent-skills 之前必须先定义清楚。我这里说的 agent-skills指的是一套能让大模型驱动的智能体“学会并执行特定任务”的能力封装它通常包含自然语言描述、可执行的工具调用逻辑、输入输出的约束说明以及对应的测试和纠错机制。换句话说单个 API 只是原材料技能是把这些原材料打磨成工作流之后能被智能体真正稳定调用的完整能力。如果你最近在开发 agent 应用一定对这样的场景不陌生模型聪明是聪明但让它稳定完成一个多步骤的真实业务任务就总是差点意思。问题往往不在模型智商而在你交给它的“能力单元”有问题。1.2 技能、工具、插件边界到底在哪很多刚接触 agent 开发的朋友会问技能不就是工具吗不完全是。工具是一个狭窄的接口技能是一套完整的、自洽的、可复用的行为模式。比如“查天气”是一个工具但“安排一次周末露营计划”是一个技能——它在内部可以调用查天气、查地图、查装备清单等多个工具并且知道按什么顺序调用、结果怎么组合、出错时怎么兜底。插件这个概念的粒度就更大了它通常指一套包含 UI、权限、依赖关系的完整软件包常见于各种集成平台。技能则更轻、更聚焦它不关心界面只关心“模型需要什么能力来完成任务”。我做了一个很简单的对照表方便大家快速区分概念粒度核心关注点类比API 工具最细单一接口的输入输出一把螺丝刀Agent 技能适中完成一个业务任务的完整行为链一条装配工序插件较大集成、配置、运行环境一整套工具箱举个生活化的类比你不会因为家里有一把螺丝刀就说自己拥有了家具安装技能。真正的技能是知道先拼框架、再上背板、最后固定铰链知道螺丝拧到什么程度不会滑丝知道装错了怎么拆。把这种“流程感”和“经验判断”封装起来才叫技能。说到这大家可能也反应过来了agent-skills 更适合谁来用两类人一类是正在做 agent 应用开发的工程同学想找一个更稳的能力组织方式另一类是业务侧想把自己的领域经验沉淀成 agent 可调用能力单元的专家。前者关注技术框架后者关注技能建模但两条路最终会汇合在同一个问题上如何让智能体稳定、可预期地完成业务任务。2. 设计 agent-skills从需求到可用的思考路径2.1 别从“我能加什么功能”出发从“任务完成为什么失败”出发我在做技能设计时有个习惯先跑 20 条真实任务统计模型的失败模式再决定要做哪些技能。很多团队反过来先看模型平台支持哪些工具再想能做什么功能这种做法我强烈建议改掉。原因是agent 在真实场景里的失败通常不是“缺一个接口”而是“少了一段流程判断”。举个例子。你做一个电商客服 agent任务里有“查询订单物流”模型经常犯的错是用户给了订单号模型却忘记了先去查询订单对应的快递公司直接就调用物流查询接口然后接口返回数据格式错误模型一脸懵。这种情况下你需要的不是一个查物流工具而是一个“订单物流跟踪”技能先把订单信息解析出来查询快递公司再调用物流接口最后把多段物流轨迹整合成一句人话。技能定义的第一原则以任务结果为导向而不是以接口功能为导向。每次新建技能之前先问自己三个问题这个技能要稳定完成什么结果现在模型在哪一步容易出错技能能把哪段容易出错的过程固化成确定性逻辑如果这三个问题想不清楚那我建议先别写技能回去把任务流程再梳理一遍。2.2 给技能划定边界输入、输出、约束条件一个高质量的技能设计至少要写清楚四件事。我这里给一个我自己常用来检查的描述模板你在设计任何一个新技能时都可以对着它过一遍技能名称必须是名词短语能概括这个技能在干什么不要用比如“工具A”“方法B”这类模糊命名。名称起得好不好直接影响模型对技能的理解。触发条件模型在什么场景下应该使用这个技能写清楚关键词和行为模式最好带上一两个正例。输入要求需要哪些参数参数格式、单位、必填可选参数的默认值是什么参数从哪里来。输出规范返回什么格式的数据哪些字段是必须的失败时怎么表达错误是否需要对用户隐藏内部细节。比较关键的一点是输出规范一定要给模型一个“数据失败也按格式返回”的指令。否则模型在技能异常时经常会自己编一个结果这是 agent 应用最危险的隐患之一。我在实际开发中还会额外加一条规则所有技能必须返回一个状态字段success 或 error并且 error 时必须携带错误码和错误描述这一步能省掉后期大量排查时间。边界设计上还有一个容易被忽略的点技能不要设计得“太贪”。一个技能只做一件事做到极致。有些同学喜欢把相关的操作揉成一个技能比如“订单管理与售后处理”结果模型判断“这个订单异常我要不要用这个技能”然后它犹豫半天选择了别的技能。技能粒度过粗等于把判断题出成了阅读理解模型当然容易失分。2.3 技能描述是与模型之间的接口不是给人看的文档我见过不少团队把技能描述写得像开发文档动词、术语、细节堆一大堆模型看起来特别费劲。要记住模型的注意力有限技能描述本质上是给模型看的“使用说明书”不是架构文档。好的技能描述第一句话就要告诉模型“什么时候用”第二句告诉它“最后输出什么”然后才是“具体怎么做”。这里给一个对比。烂描述“该接口用于调用内部订单系统查询订单信息支持通过订单号查询订单详情同时可通过订单号关联物流信息……”好描述“当用户询问订单状态或物流进度时使用此技能输入订单号返回订单当前状态及最近一条物流记录。”后者读起来一气呵成模型执行时跑偏的概率会低很多。我在团队里经常说一句话工具是给代码调用的技能是给模型调用的。这段话要刻在脑子里。代码调用接口关心的是参数类型和返回字段模型调用技能关心的是“我该不该用”“用了会得到什么”。所以技能描述里的措辞不要用开发文档式的客观描述多用业务场景式的指令表达。描述里可以适当加入第一人称视角比如“当用户向你询问物流信息时”让模型更容易代入执行场景。3. 落地实现搭一个可复用的 agent-skills 模块3.1 目录与文件结构设计技能的组织方式我介绍一下目前比较主流的一种结构灵感来自于社区经典的 Claude Skills 设计现在很多开源项目也逐渐形成了类似约定skills/ 01-order-tracking/ SKILL.md main.py requirements.txt tests/SKILL.md 是技能的说明书用 Markdown 写清楚上面的触发条件、输入输出、使用方法。main.py 是技能的具体实现逻辑。requirements.txt 声明依赖最好固定版本号防止漂移。tests/ 放测试用例后面我会专门讲测试怎么设计。目录名最好带序号方便 agent 在多个候选技能中快速理解优先级。序号本身也有语义比如 01 表示核心能力02 表示辅助能力排序在前面的技能会被模型优先考虑。当技能数量涨到十几个以后这套排序规则能显著降低模型选错技能的概率。3.2 SKILL.md 是技能调用的说明书我个人觉得 SKILL.md 是整个技能栈里最容易被低估的部分。很多团队随便写两行结果模型根本不知道技能能干到哪一步。这是一个比较完整的模板你可以直接参考# 订单物流跟踪 ## 何时使用 用户询问订单的物流状态、快递进度、包裹到哪了或者主动提供订单号要求查询物流时。 ## 输入 - order_id: string, 必填用户提供的订单号 - 可选期望回复风格简洁/详细 ## 输出 返回 JSON - status: success | error - message: 给用户的自然语言结果 - logistics_events: 最近三条物流轨迹时间地点事件 ## 执行步骤 1. 调用 get_order(order_id) 获取订单信息和快递公司 2. 调用 get_express(company, order_id) 查询物流轨迹 3. 如果步骤 2 返回错误检查快递公司字段尝试修正后再调 4. 整合结果返回 message ## 注意事项 - 不要假定所有订单都有物流轨迹生鲜订单可能在特殊时段无轨迹 - 物流状态为“已签收”时务必提取签收人姓名 - 任何接口异常都返回 statuserror不要伪造数据这样一个结构模型读一遍基本就能学会在什么条件下调用怎么传参怎么处理异常。还有一个额外的收益这套 SKILL.md 可以直接拿来做测试用例的基准后面的 4.1 我会具体展开。写 SKILL.md 的时候要刻意控制长度我建议控制在 60 到 120 行之间。太短了描述不全面模型用的时候会漏步骤太长了模型的核心注意力会被稀释反而记不住关键指令。这跟人看说明书一样一百页的说明书很少有人读完还能记住重点。3.3 把编排逻辑留在代码层别让模型现场编技能内部的调用逻辑应该尽量把复杂的编排放进代码里而不是让模型在 prompt 里临时编排。我举个反例一个技能如果需要按顺序调用多个 API有的团队就把这几个 API 都暴露给模型让模型自己决定先调谁后调谁。这种做法在简单场景下能跑但一旦上下文变长或者任务变复杂模型大概率漏步骤。更稳的玩法是把编排逻辑写在代码层。比如上面的物流跟踪技能main.py 里直接实现“订单查询快递公司识别物流查询消息组装”这条链暴露给模型的只有输入 order_id 和输出 message。模型只需要决定“要不要用这个技能”不需要关心技能内部的细节。这个思路其实就是把技能当作一个原子单元来使用模型的思辨能力放在任务拆解和结果解释上而不是放在低层的 API 调用序列上。这样做还有一个明显好处当第三方接口升级或某个步骤需要调整时只改 main.py 就行不需要动模型侧的任何东西。模型侧的技能描述保持稳定意味着模型学到的行为模式不会频繁波动这在生产环境里非常省心。3.4 一个简单的实操示例周末活动策划背后的两个技能接下来看一个从零开始的具体例子。假设我要做一个周末活动策划 agent需要两个基础技能查周末天气和查附近公园。查天气技能的核心逻辑可以这样写def get_weekend_weather(city): urls [ fhttps://api.weather.local/city/{city}?days3 ] data fetch_json(urls[0]) return { status: success, weather: [ {day: d[date], condition: d[condition], temp_low: d[low], temp_high: d[high]} for d in data[daily][:3] ] }查附近公园技能的逻辑def find_nearby_parks(city, radius_km5): parks query_park_db(city, radius_km) return { status: success, parks: [ {name: p[name], distance_km: round(p[distance], 1), features: p[features]} for p in parks ] }然后给每个技能配一段简洁的 SKILL.md比如天气技能的关键描述# 周末天气查询 ## 何时使用 用户提到周末出行、户外活动、是否需要带伞或增减衣物时使用。 ## 输入 - city: string, 必填城市名 ## 输出 返回未来三天天气预报包含天气状况和最高最低温度。 ## 注意事项 - 只有用户明确表达周末出行相关意图时才使用 - 如果用户只问“今天天气怎么样”使用即时天气技能不要用本技能这个示例看起来简单真正有价值的是设计思路两个技能拆开、各管一件事模型组合起来非常自然。用户说“周末想找个凉快的公园走走”模型先调天气技能判断周六日温度再调公园技能筛出周边选项最后组装成一段建议。如果当初我把这两个功能揉成一个“户外活动推荐”技能模型反而要在很多无关参数里做选择了。4. 训练与验证技能好不好用测了才知道4.1 测试用例覆盖成功能路径更要覆盖异常路径技能上线前必须有一套测试集。除了覆盖正常调用路径我强烈建议专门写异常路径的用例。所谓异常路径包括用户输入缺失、第三方接口超时、返回数据结构变化、技能执行结果语义不对等。这些异常场景才是 agent 在真实环境中翻车的高发区。针对上面的物流跟踪技能测试集至少要有这几条用例输入预期正常查询有订单号快递状态正常返回 message 中包含“运输中”或“已签收”订单号无效随意填一个 12 位数字返回 errormessage 提示订单不存在物流接口超时模拟快递公司接口 5 秒无响应返回 error不向用户显示堆栈信息已签收订单最近一次签收记录包含姓名message 中包含签收人姓名测试的时候不要只看最终返回格式还要看错误分支时的用户体验。agent 技能的错误返回理想状态是给用户一个可以下一步操作的提示而不是一句“系统错误”。比如接口超时时返回“查询超时请稍后再试或联系客服”就比裸抛一个 exception 要好得多。测试哪些内容需要持续迭代。我建议每两周回看一次线上日志把真实用户的失败案例补充进测试集。测试集本身不是静态的它是技能能力的体检报告会随着你对业务的理解加深而越长越全。4.2 自动跑分和人工回归怎么取舍技能效果评估我建议用两层第一层自动化跑分第二层人工回归。自动化跑分适合监控改动是否引入回归人工回归适合判断输出语义是否自然。我们之前吃过亏把自动化指标调到 98%实际用户体验还是不好因为自动评分只检查格式不会检查语气是否生硬、信息是否冗余。后来我们在自动跑分之外每周抽 10% 的交互日志专门看“用户对 agent 输出的不满意的反馈”和“agent 自己承认错误的情况”这些信息比准确率更有价值。人工回归不需要把每个 case 都过一遍重点是看两类一类是自动跑分通过但用户反馈差的另一类是边界输入比如超长文本、口语化表达、含有错别字的输入。真实用户永远不会按你设计的标准姿势输入人工回归的根本目的就是把模型和技能从“考场模式”拉回到“实战模式”。4.3 技能版本的演进与管理另一个容易被忽视的问题是技能版本。技能不是一次性写好就完了随着业务变化和模型升级需要持续调节。我的习惯是每次修改技能时先更新 SKILL.md再更新代码最后跑一遍全量测试集。如果改动涉及输入输出格式变更还要检查所有引用该技能的 prompt 模板。这些步骤听起来繁琐但正是它们防止了“上一个版本还能用新版本直接崩”的尴尬。版本管理上我建议用语义化版本号主版本号变更表示输入输出格式不兼容次版本号表示逻辑增强修订号表示 bug 修复。每次发布在变更说明里标注清楚“模型侧需要感知的变化”和“纯代码层面的变化”这个信息直接同步给上层编排逻辑的维护者。团队多人协作时有条件的话可以引入自动化 CI跑完测试再合并把人工检查的点降到最少。5. 常见问题与避坑指南5.1 技能没生效的三种典型情况最常出现在工作群里的问题就是“技能没生效”我总结了三种典型情况技能描述没有被加载进上下文。这种情况发生在接入框架时把技能列表漏传了或者上下文超过模型窗口技能描述被截断。排查时先打印传给模型的完整 Prompt肉眼确认技能描述是否在。模型选择了技能但参数传错。多半是输入描述不清晰导致模型不知道参数来源。比如技能输入要求 user_name但对话里用户从头到尾没报过名字模型只能瞎填。解法是把技能接收参数设计成可以从上下文推导出来的值同时给默认值让模型即使拿不到精确值也不至于直接报错。模型调用了技能但技能内部报错。这类错误往往出现在第三方接口上外面包装得再漂亮里面一个 request 超时整个流程就断了。我的经验是技能内部必须做完整的异常捕获不仅 try/except还要给每个可能失败的点标注清晰日志最好给错误码。错误码要设计成一看就知道是哪个环节出了问题比如 ORDER_NOT_FOUND、EXPRESS_API_TIMEOUT而不是一串数字。这三类问题的共性根源是模型、技能描述、技能实现三者之间的信息不对称。所以排查时不要一头扎进代码里看先用“ Prompt 里有什么、模型收到了什么、技能返回了什么”三段日志对一遍基本一分钟内能定位。5.2 权限与安全技能是系统敞开的门技能能访问外部系统本身就是给 agent 开的“门”。我见过一个团队给客服 agent 加了一个“订单金额计算”技能结果技能定义里带上了内部数据库连接串用户在对话里诱导模型输出技能源码把连接串套走了。这个问题不是说几十行代码的问题而是权限模型的设计问题。我的做法是技能代码里禁止硬编码任何密钥一律从运行时环境变量读取技能的运行环境与主应用隔离网络策略最小化只放行必要的外部端点输入参数严格校验过滤掉命令注入和路径穿越的常见 payload所有对外调用必须有日志方便出事时审计敏感操作技能比如退款、改地址、删除数据这类必须增加二次确认环节。模型在调用这类技能前先向用户复述请求并请求确认确认后再执行。这个设计不是为了防用户而是防模型在幻觉状态下执行危险操作。算是给 agent 加一道保险栓别嫌麻烦真的出事的时候你会庆幸有这道流程。5.3 多技能并发时的优先级与路由当技能数量超过 10 个时会出现一个新问题模型经常选错技能。我建议从两个方向解决。一是做技能分组和路由先让模型判断任务类别再只暴露这一类下的技能而不是一次性把所有技能都给出。二是给 SKILL.md 的“何时使用”增加排除描述明确告诉模型哪些场景不要用它这种负例往往比正例更有用。我做过的最高纪录是 28 个技能同时在线当时就是用分组路由撑起来的。分组规则直接写在系统提示词里比如把技能分为“订单域”“商品域”“优惠域”模型先判断用户问题属于哪个域再加载对应域的技能描述。效果很稳定推荐尝试。排除描述也很关键比如一个“改签机票”技能要明确写上“仅适用于已出票订单预订未出票时不要使用”否则模型会拿着它处理所有跟机票相关的问题。多技能场景还有一个细节给技能排序和分组的时候把互斥技能放到不同组里避免模型在同一组里做困难的二选一。比如“标准退货处理”和“生鲜品特殊退货”两个技能最好放在不同业务域下模型先判断商品品类再加载对应技能显然比同时把两个技能亮出来让它选要稳得多。我个人在实际操作中的体会是agent-skills 最大的价值不是让模型变聪明而是让工程团队能把业务经验沉淀成一系列稳定、可测试、可演进的能力单元。测试集和版本管理可以解决一半的问题剩下的要靠你对业务场景的理解。最后再分享一个让整个流程更顺畅的小技巧把技能开发当成一个独立于单一业务线的平台来维护每个技能都有独立的负责人。这样当上层 agent 需要新能力时不用重新造轮子直接从技能仓库里查有没有可复用的模块。技能孤岛比数据孤岛更可怕因为模型更容易被混乱的技能引入歧途。能读到这里的同学你大概率已经遇到了类似的问题不妨按这套思路把技能体系重新捋一遍会比预想的简单。