Agent技能框架设计指南：把模型会聊天变成模型会干活

说实话这几年做大模型应用我越来越觉得“Agent能不能干活”这件事瓶颈根本不在模型智商而在技能组织方式。模型本身再聪明如果连该调哪个工具、传什么参数都摸不着头脑干起活来照样像无头苍蝇。我一直在做的一个内部项目叫agent-skills就是为了把“模型会聊天”变成“模型会干活”的那层胶水层。这篇文章就围绕这个项目聊聊一个技能框架到底该解决哪些问题设计时哪些地方最容易翻车以及我是怎么一步步把它补成能稳定落地的。1. 从“会聊天的模型”到“会干活的Agent”技能体系到底解决了什么1.1 我为什么开始做 agent-skills先说个背景。之前我给一个客服机器人接了一堆工具有查订单的、有退款的、有查物流的还有一个改地址的。刚开始觉得工具都封装成函数了模型function calling也调得动这总该稳了吧。结果一上线就露馅用户说“我那个快递送错了地方帮我改一下”模型把退款的函数给调了差点给用户产生经济损失。后来排查发现问题不在于模型笨而在于我们只给模型暴露了一堆“函数”却没有给它一套“什么时候该用哪个函数”的决策上下文。这就是 agent-skills 这个项目最开始的动机不再把一个可调用模块当成孤零零的 API 函数而是把它当成一个完整的“技能单元”来管理——技能里有明确的功能描述、适用场景、参数规则、边界条件甚至包括用错了会有什么后果。模型不再靠猜来选工具而是靠一份结构化的技能契约来做决策。1.2 技能、工具、插件先分清这三个概念很多人会把 Agent Skills、工具函数、插件混为一谈。我在做这个项目时先把边界切清楚了否则后面很多设计都会跑偏。工具Tool/Function最小可执行单元通常就是一个函数有明确的输入输出比如get_order_status(order_id)。它不关心业务语义只负责把事情做完。技能Skill在工具之上加了一层“决策语义”。它包含工具的调用方式还包含何时调用、何时不调用、调用前需要满足什么前置条件、调用后结果如何解读。一个技能可以封装一个工具也可以编排多个工具。插件Plugin一组技能的打包分发形态。比如“订单管理插件”可能包含查订单技能、改地址技能、退款技能。插件解决的是安装部署和权限域的问题而不是决策问题。很多项目失败就是因为直接把工具层当技能层用。工具层只回答“怎么执行”技能层才回答“什么时候执行”而后者恰恰是 Agent 稳定性的关键。1.3 技能体系要解决的三件事我做了半年多 agent-skills 之后把它的核心价值总结成三句话能力解决的问题反面案例可发现性模型能从技能列表里快速锁定正确目标技能列表80个模型每次都选中第二个可调用性模型能生成符合规范的参数完整跑通调用链参数名对了但类型错执行器直接报错可校验性执行结束后Agent 能判定结果是否符合预期工具返回“成功”但业务上其实没干成所以说技能框架不是把函数包装一下给模型调用那么简单它是一套围绕“模型决策”设计的系统工程。理解了它要解决什么问题后面的每一步设计才不会跑偏。2. 设计一套技能目录描述文件、参数协议与语义清晰度2.1 一个技能单元应该长什么样我给 agent-skills 里的每个技能都设计了一份独立目录目录下固定几个文件技能描述文件、参数校验规则、执行脚本、依赖清单。看起来很简单但这个目录结构是我踩了很多坑之后才定下来的。一个典型的技能目录长这样skills/ └── order-tracking/ ├── SKILL.md ├── schema.json ├── run.py └── requirements.txtSKILL.md是给模型看的用自然语言描述这个技能是干嘛的schema.json是给校验器看的用 JSON Schema 描述参数规则run.py是给执行器看的真正做事的代码。三层分离是我觉得最舒服的结构——各管各的互不污染。很多人忽略的一点是requirements.txt。技能一旦复杂起来会有自己的第三方依赖。如果所有技能都共用一个依赖环境版本冲突早晚爆发。给每个技能一个独立依赖清单部署时就多了一层隔离这也是 agent-skills 设计里很关键但容易被忽视的细节。2.2 描述文件写法让模型不看代码也能安全调用SKILL.md是技能框架里最重要的一份文件没有之一。模型不会看run.py它只会通过SKILL.md来理解这个技能。所以这份文件的写作质量直接决定模型调用技能的准确率。我自己的写法有一套固定套路--- name: order-tracking description: 根据订单号查询订单的当前物流状态和配送进度。 when_to_use: 当用户询问“快递到哪了”“订单什么时候送到”“物流更新”等问题时使用。 when_not_to_use: 当用户要修改配送地址、申请退款或投诉快递员时不要使用本技能。 parameters: order_id: type: string description: 订单编号通常以字母 ORD 开头 required: true --- - 调用前确认用户提供的订单编号格式正确。 - 调用后如果返回状态为 delivered主动告知用户签收时间。 - 注意仅支持查询最近3个月内的订单。为什么要有when_not_to_use这是我踩过最深的坑。早期只写了“这个技能是干嘛的”没写“不是干嘛的”模型一脸迷茫时会把不相关的请求也往这个技能上赖。加上了反向约束之后误调用率直接下降了一大截。还有 description 里的关键字密度。模型对描述文本的语义匹配非常敏感描述里尽量覆盖真实用户会用的说法比如“快递”“物流”“到哪了”而不是冷冰冰的系统术语。这有点像是给技能写SEO文案让模型更容易命中。2.3 参数协议设计类型、枚举、默认值与必填项的取舍参数协议我直接用 JSON Schema简单通用生态也成熟。不过实际设计时有好几个细节值得说道说道。第一个细节字符串类型的参数一定要限制格式。订单号可能是有固定前缀的日期时间可能是YYYY-MM-DD格式。在描述里写清楚了还不够最好在 schema 里加pattern校验让执行器跑起来之前就拦住脏数据。第二个细节枚举值宁可多一点也不要靠模型自由发挥。比如你要让模型判断用户情绪别让模型传一个 open 的字符串而是给它一个enum: [positive, neutral, negative, unknown]。模型在封闭集合里做选择比开放式生成稳定太多。第三个细节默认值要谨慎使用。有的技能参数没传也能执行于是给了一个默认值。结果模型发现不传也行后面干脆全都不传导致业务结果偏差。我的经验是默认值一定是“被明确设计过”的不能是“图省事”的。如果不确定默认值是否合理宁可设成必填。{ type: object, properties: { order_id: { type: string, pattern: ^ORD\\d{6,}$, description: 订单号以ORD开头后跟至少6位数字 }, include_history: { type: boolean, default: true, description: 是否包含历史物流节点 } }, required: [order_id] }这段 schema 看起来简单但它保证了三个事参数格式可预期、模型输出可回退、执行器真正运行时不至于因为类型问题崩溃。3. 实现链路拆解从技能注册、路由匹配到执行回传3.1 技能注册中心加载机制和可见性控制技能不是写好了就能自动被模型看到中间还有个注册中心在把关。agent-skills 里的注册中心维护一张活跃技能表只有注册过的技能才会出现在模型的工具列表里。注册时我会顺带带上几个控制字段技能所属领域、运行环境沙箱还是生产、是否可用状态、统计权重。其中“统计权重”帮了大忙——某些冷门技能容易被模型忽略就给它临时调高权重让它在工具列表中排前面某些技能调用率异常低还占 token就直接下线。加载机制上我也分了两层全量加载和按需加载。技能数量少的时候全量加载进上下文没问题技能数量上了几十个prompt 上下文会变得巨长响应变慢而且模型容易“看花眼”。按需加载是先根据用户 query 做一个粗召回把可能相关的10个技能灌进上下文等模型选定后再真正执行。这一步优化之后响应速度提升了大概30%准确率也没掉。3.2 路由匹配模型选错技能时的兜底策略路由匹配是整套框架里模型的“主战场”但模型毕竟不是确定性的程序总会有选错的时候。我在 agent-skills 里设计了三层兜底把选错率的负面影响压到最低。第一层前置澄清。用户的请求本身语义模糊时不急着调技能让 Agent 先反问一句“您是要查物流还是修改地址”。虽然多了一轮对话但比起调错技能之后的补救成本这轮澄清便宜太多。第二层相似技能冲突消解。两个技能的功能描述高度重叠时光靠描述区分不靠谱就需要加一道规则在两者描述里主动写明“如果你觉得这个请求也适合另一个技能请优先选择另一个”。有点像是技能之间的“谦让协议”。第三层执行前校验。即使模型已经选定了技能执行器在跑之前还要做一次参数和上下文校验。比如模型想调用退款技能但对话上下文中没有可退款的订单号那这个调用就直接拦截不给执行器丢脸的机会。这层兜底思路和微服务里的熔断非常像上游不可信下游要自保。模型是不可信的上游技能执行器就是需要自保的下游。3.3 执行与回传结果反馈给模型的格式设计技能执行完不是把结果原样丢回给模型就完事了回传格式的设计直接影响 Agent 下一步能不能正确接话。我用的回传结构大致是{ status: success, execution_time_ms: 132, result_summary: 订单 ORD123456 已签收签收时间为今天上午10:23, data: { status: delivered, delivered_at: 2025-06-18 10:23:00, tracking_events: [ {time: 2025-06-16 09:00, location: 转运中心, desc: 包裹已到达}, {time: 2025-06-18 10:23, location: 前台, desc: 已签收签收人前台} ] }, next_steps: [可以进一步询问用户是否需要电子发票] }这里最有用的是result_summary和next_steps两个字段。result_summary是给模型看的“人话版”执行摘要模型直接基于它组织回复就行不用自己读data里的原始数据next_steps是给模型的“下一步建议”能有效引导对话继续下去而不是每次执行完就卡住。试想一下如果只给模型一堆tracking_events数组模型还得自己总结签收时间总结错了就是事故现场。直接把摘要给到它出错的概率就小得多。4. 踩坑实录agent-skills 落地中最容易翻车的五个细节4.1 描述文件措辞不准确导致模型反复调用错误技能有段时间我发现日志里模型特别爱调一个“订单备注修改”的功能但这个技能本来应该是低频操作。查了很久才发现问题出在技能描述里写了“修改订单信息”而用户问“帮我改一下收货地址”时模型把“改地址”也理解成了“修改订单信息”技能就误触发了。后来我把措辞改成了“仅修改订单内商品备注不影响收货地址、商品信息、优惠信息”并且加上“改地址请调用地址变更技能”的提示。这种显式的“不要做什么”写进描述里比单纯细化“做什么”管用得多。我现在的习惯是写完描述后用20条典型用户query去测看模型选技能的结果是否符合预期不符合就调描述直到全对为止。4.2 参数类型漂移JSON Schema写对了但实现没跟上还有一次技能跑着跑着突然开始报错而且只在特定用户的操作路径上出现。排查后发现schema 里定义order_id是 string 类型但执行脚本里有一段历史代码把它当 int 用了。模型传参是按 schema 来的传了个123456字符串脚本一执行 int 转换直接崩。这个问题很隐蔽因为它不是每一次都会触发只在模型规规矩矩按 schema 传参时才出现。这提醒我一个事schema 必须和执行代码是同一份契约的两种表现改了 schema 就得同步检查执行代码。后来我在 CI 流程里加了一步每次改动 schema自动生成一组随机测试参数跑一遍执行脚本参数类型的漂移问题基本杜绝了。4.3 技能冲突两个技能都匹配用户意图时怎么排序技能多了之后必然出现“看起来都能干这事”的情况。比如我有个“查询余额”技能和一个“获取账户汇总”技能用户一句“帮我看看我还有多少钱”两个技能都能对上。面对这种冲突我给每个技能定义了一个priority字段同时让 Agent 在判断时遵循一个规则如果多个技能高度匹配选择优先级更高且执行成本更低的一个。但更根本的解法是“拆清楚边界”——我把“获取账户汇总”明确限制为“查询总资产、总负债、各账户汇总”把“查询余额”限制为“单个账户的可支用余额”。边界清晰之后冲突自然减少。靠规则强排是治标语义边界清晰才是治本。4.4 动态技能热加载的安全问题这个点可能偏工程向但必须提醒一句。技能本质上是可执行代码而 Agent 的技能加载往往需要动态热更新。如果技能来源不可控等于放开了一个任意代码执行的口子。我在 agent-skills 里做了三件事第一所有技能只能从私有仓库拉取禁止从公网直接安装第二技能运行在受限的沙箱环境里不能访问宿主机的敏感路径和环境变量第三技能声明的权限必须显式列出执行时动态校验。听起来这些都是安全常识但实际做项目时特别容易为了省事而省略等出事了才来后悔。4.5 日志与追踪出问题时根本查不了最后这个坑是纯经验之谈技能调用的链路追踪越早做越好。早期的版本我只记录了“哪个技能被调用了、参数是什么”但没记录“模型决策时看到了哪些技能描述”“为什么最后选中了这个”。一旦模型选错技能我根本没法复盘决策过程。现在的日志结构大概是[request] 用户帮我取消订单 ORD123456 [candidate_skills] order-tracking, refund, address-change, cancel-order [rank_result] cancel-order(0.82), refund(0.31) [selected_skill] cancel-order [execution] cancel-order executor started [execution_result] success, 取消成功有了这种日志每次模型选错技能都能定位到具体环节是候选召回没召回对是排序权重设置不合理还是描述文件语义有歧义没有日志的时候排查靠猜有了日志之后排查靠证据这个差异在项目中期之后会越来越明显。5. 技能拆分的“取舍艺术”与调优实践5.1 什么时候拆分技能、什么时候合并技能粒度的问题我一开始以为越大越好一个技能解决所有问题多省事。后来发现大技能就是个灾难模型描述写了几百字参数有十几个执行脚本里塞满了一堆 if-else每加一个新场景就改一次老的逻辑最后谁也hold不住。现在的拆分原则比较朴素一个技能只负责一个业务决策点。查订单是一个技能改地址是一个技能申请退款是一个技能不要搞一个“订单全能王”。拆细了之后每个技能的描述更短模型更容易理解每个参数协议更简单校验更可靠每个执行脚本更短维护成本直线下降。但合并的需求也真实存在。当用户的意图明确指向一步完整操作时把多步操作封装成一个技能反而更好。比如“下单并支付”这种操作如果拆成“创建订单”“计算金额”“发起支付”三个技能模型中间任何一步接错了都会出大问题。这时候把它们合并成一个 “checkout” 技能内部串起来对外只暴露一个入口是对模型最友好的设计。一句话总结决策点多就拆流程固定就合。技能拆分本质上是在给模型降低决策难度而不是在给代码做模块化。5.2 通过小样本评测推进技能优化我现在每个技能都配了一个“评测集”里面放10到20条典型的用户 query每条都标注了期望选中的技能。每次改动技能描述或 schema 之后就跑一遍评测集看正确率变化。这个习惯帮我避免了好几次“改一个技能搞坏另一个技能”的悲剧。因为技能之间是有语义干扰的A 技能的描述写得越长B 技能的可见性就越低。通过评测集能快速发现这种负面的语义偏移。评测集的做法也比较轻量query: 我的快递到哪了 - order-tracking query: 修改收货地址 - address-change query: 我不想要这个订单了 - cancel-order我用一个简单的脚本把 query 灌给模型让模型从技能列表里选一个然后和期望值对比。差不多20分钟能跑完一轮改完描述立刻知道效果这种即时反馈对调优太重要了。5.3 下一步扩展多Agent共享技能库与技能版本管理最后聊点扩展的方向。agent-skills 现在在我这边已经不只是单个 Agent 在用了多个业务线的 Agent 都在共享同一套技能库。这就带来两个新的问题技能版本冲突和权限隔离。版本管理我现在用的是语义化版本主版本号不兼容时不允许混用次版本号向后兼容可以渐进升级。实际跑下来定义清楚“哪些改动算破坏性变更”是最耗精力的但也是最值得做的一件事。权限隔离这块我采用了“技能归属”的概念一个技能可以声明自己属于某个业务域这个业务域的 Agent 才能加载它。跨域调用必须显式授权。这样从机制上杜绝了“客服机器人错误调用了财务技能”这类事故。Agent 的技能体系做到这个阶段我最大的体会是技能的兵家必争之地不是代码实现而是信息架构和语义设计。模型本身不关心你的代码写得多么巧妙它只关心能不能从描述里准确理解“这是干什么的、什么时候用、别什么时候用”。与其追着新模型版本跑不如先把技能描述、参数协议、回传格式这些基本功打磨好。说到底agent-skills 不是一个库也不是一个框架它是一套让模型“用对技能”的方法论。每次加新技能时多花半小时把描述写清楚把边界画明白后面就能省下十几个小时的排查时间。这个投入回报率怎么算都不亏。