让我先理清一个概念这里说的不是传统意义上的“技能树”或“学习路径”而是给大语言模型驱动的Agent装配一套可复用、可插拔、可独立迭代的能力模块。把Agent的能力拆成“技能”本质上是把“模型知道什么”和“模型能做什么”彻底分开。我最早做Agent项目时踩过一个很深的坑把所有工具逻辑都塞进System Prompt里让模型“自由发挥”。结果Prompt越来越长模型越来越“笨”偶尔还会出现幻觉式的工具调用。后来我意识到问题不在于模型的推理能力而在于我把能力的边界和调用的逻辑混在一起了。Agent需要的是“技能”——边界清晰、行为可预期、能独立验证的模块而不是一段写在提示词里的愿望清单。这篇文章不聊泛泛的架构概念就讲我在实际搭建一个agent-skills体系时做的事情为什么要把能力拆成技能、技能的描述怎么写才不会被模型误读、参数提取和校验怎么做才不会翻车以及技能调用链路里最容易被忽略的几个隐患。适合正在做Agent应用、被“工具调用不稳定”折磨的开发者看。1. 先把“能力”和“知识”分开——agent-skills的起点1.1 一个让模型变“笨”的错误做法我之前有个项目叫“自动写周报Agent”初版实现非常简单在System Prompt里写了十几条工具调用规则把公司内部接口的URL、鉴权方式、参数格式全堆进去然后让模型根据用户输入自己决定调哪个接口。那版本实际跑起来之后问题非常典型提示词有2000多token模型每轮对话都要把这些内容重新“读一遍”响应速度肉眼可见地变慢。更离谱的是当用户说“帮我写一下本周的周报”时模型有时会直接调用“获取用户信息”接口而不是“获取本周任务”接口——因为没有边界约束模型会凭语义相似度猜。后来我把这些接口能力重构为一个个独立技能每个技能包含能力描述、输入参数schema、执行函数、触发条件示例。模型只需要看到一份技能清单按需求选择技能ID并传参剩下的执行逻辑全部由代码接管。效果立竿见影Prompt缩短到300token以内工具调用的准确率从最初的不到70%提升到95%以上。1.2 什么是“技能”在Agent语境下的准确定义在agent-skills体系里一个技能需要满足三个条件边界清晰能明确说清楚“这个技能负责什么、不负责什么”。做不到这点的技能拆分就是失败的拆分。输入输出严格定义输入是结构化的参数而不是自然语言输出是结构化结果而不是自由文本。这是为了后续的校验和可观测性。可独立测试一个技能应该能脱离Agent单独被调用和验证。如果你的技能函数只能在完整Agent环境里跑通那测试和排障的成本会成倍增加。这三个条件中最容易出问题的是第一个。“负责什么”稍微模糊一点LLM就会在边界上犯迷糊。比如我当时把“获取用户信息”和“获取用户部门组织架构”分成两个技能结果模型经常在用户问“我们部门多少人”的时候调用前者——语义上有相关性但实际不是同一个能力。1.3 技能拆分的粒度怎么拿捏这是每个做Agent的人都会纠结的问题。拆太细技能数量爆炸模型在清单里翻找都费劲拆太粗技能内部逻辑太多参数schema复杂到模型无法正确填充。我的经验是遵循“动作最小化”原则一个技能对应一个不可再分的原子操作。举几个对比例子错误的拆分正确的拆分理由查询任务列表查询本周任务列表、查询已归档任务列表、查询待办任务列表同样的底层数据源但过滤条件和返回结构差异大混在一起会让参数模型混淆操作数据看板创建看板、更新看板、删除看板不同动作的参数集差异明显合并会让可选参数过多处理用户消息解析消息意图、生成回复草稿、发送消息这三个操作之间不是调用关系而是流水线关系各自需要独立的失败处理“处理用户消息”这个拆法我特别说明一下。我见过不少项目把“消息处理”做成一个大技能内部顺序调用好几个功能。表面上看起来只暴露了一个技能模型很“省心”但一旦消息发送失败你无法确认是意图识别错了还是草稿生成错了。拆成独立技能后每个环节的输入输出都清晰排障成本大幅下降。2. 技能描述的艺术——写给模型看的说明书不是写给代码的注释2.1 模型看技能描述的方式和程序员想的不一样很多开发者写技能描述时习惯性地站在“代码阅读者”视角写一堆技术细节函数签名、数据结构、内部实现逻辑。但LLM读技能描述时它实际上是在做两件事语义匹配这个技能和用户请求是否匹配和参数映射用户请求里的字段对应哪个参数。所以我后来总结出一个原则技能描述要站在“调用者”视角写清楚“什么情况下用我、用了我会发生什么、需要注意什么”。我之前写过一个“获取任务详情”的技能描述一开始是这样的获取任务详情。参数task_id任务ID字符串类型。返回任务标题、状态、负责人、截止时间。这个描述给我的感觉是太“干”了。模型确实能看懂但在多技能场景下它很难区分“获取任务详情”和“获取任务评论列表”该用哪个。改成这样之后效果好了很多当用户请求查看某个任务的完整信息时使用。需要提供任务ID。返回内容包括任务标题、当前状态、负责人、创建时间、截止时间、优先级。注意本技能不返回任务下的评论内容查询评论请使用获取任务评论列表技能。如果用户没有提供任务ID不要调用本技能应该主动向用户询问。区别在哪里新版描述多给了模型三个关键信息触发场景对“什么时候用”做了明确定义减少了二义性。负向排除明确指出“不返回评论内容”防止模型把评论和详情混在一起。缺参处理指引明确告诉模型“参数不齐时该干什么”避免模型在缺参时强行猜一个ID。这三个信息在你只有两三个技能时可有可无但当你技能清单到了十个以上它们就是区分稳定和不稳定的关键。2.2 技能清单的组织方式分组、排序、默认行为技能数量多了以后怎么把清单呈现给模型也是一个问题。我试过几种组织方式最后比较有效的是“三级结构”技能组: 任务管理 技能: - id: task.get_detail description: 获取任务详情 - id: task.get_comment description: 获取任务评论 默认技能: task.get_detail 技能组: 用户管理 技能: - id: user.get_info description: 获取用户信息 默认技能: none分组有什么实际好处好处是模型在决策时多了一个先验信号——先根据用户请求判断属于哪个领域任务/用户/项目再在该领域内选择具体技能准确率明显更高。默认技能这个设计尤其好用当模型不确定用户要干什么、但能大致判断属于哪个技能组时优先调用默认技能而不是返回“无法处理”。当然分组信息本身也消耗token。我的实测数据是30个技能分组展示比平铺展示多消耗约100-150token但工具选择的准确率从86%提升到94%这个开销非常值得。2.3 参数schema降低模型幻觉的关键战场参数schema设计是agent-skills体系里最容易被低估的环节。很多人直接拿Flask或FastAPI的路由参数定义来当schema用结果LLM把参数填得乱七八糟。我觉得核心问题在于LLM不是按类型系统思考的是按语义和上下文理解的。所以参数schema不仅要定义类型还要给出示例和约束。pythonskills_config { task.create: { description: 创建新任务, parameters: { type: object, properties: { title: { type: string, description: 任务标题一句话描述要做什么, maxLength: 100 }, priority: { type: string, enum: [low, medium, high, urgent], description: 优先级默认medium }, due_date: { type: string, format: date, description: 截止日期格式YYYY-MM-DD如果用户没说日期可能为空 }, assignee: { type: string, description: 负责人姓名如果用户没有指定则为null } }, required: [title] } } }注意上面这段schema的写法每个参数都给出语义说明枚举值写全还特别标注了“用户没说时该怎么办”。这比单纯写priority: string有效得多。原因也很简单——LLM在填充参数时会尽力利用description里的信息来决定这个字段填什么。你把约束写清楚模型就不会乱来。还有一点非常重要required数组要保守。尽量少于真实所需。因为LLM在缺参时倾向于“猜”而不是“问”。与其让它在required参数上强行编造不如把参数设计成可选然后在代码层做校验和追问。比如上面的assignee设为可选如果用户没指定负责人后端再主动通过追问技能来获取比让模型凭空猜一个合法但错误的名字要稳妥得多。3. 技能注册与触达机制——不要让模型在30个技能里大海捞针3.1 为什么你的技能越多模型越容易出错一个容易被忽略的事实是LLM在候选技能特别多时选择的准确率并不会线性下降而是会“雪崩式”恶化。我做过一个对照组实验5个技能时准确率97%15个技能时92%到了30个技能时直接降低到76%。原因不复杂——模型在做工具选择时本质上是在计算“用户请求”和“技能描述”之间的语义相似度。当候选集膨胀时不同技能描述之间的差异性反而变小了模型就更容易发生混淆。解决这个问题的思路不是“让模型变得更强”而是“减少模型做选择的负担”。3.2 按需加载只在需要的时候把技能放上桌我的做法是给技能加上触发条件trigger condition。系统在每轮对话开始时先根据用户消息做一次轻量级的意图预判只会把可能与当前任务相关的技能加载到上下文里。简单说我维护了一个路由模块它会做两件事将用户请求映射到一个或多个技能组而不是具体技能。把命中的技能组内所有技能的描述、参数schema加载到上下文里。举个例子用户说“帮我看看这个任务”。路由模块判断这是“任务管理”领域的请求于是把task.get_detail、task.get_comment、task.update等5个任务相关技能加载进来用户管理、报表分析等25个无关技能一概不出现在模型视野里。这样做的收益非常明显上下文长度大幅缩短响应变快。无关技能彻底“隐身”模型不可能误选。技能清单可以无限扩展只要同一时刻的候选技能保持在小规模即可。3.3 路由规则怎么写才不容易误判路由模块本身也可以是一个小型LLM调用也可以用规则或embedding相似度来做。我的实践是三层策略配合使用硬规则优先用户消息中包含特定关键词时直接映射到对应技能组。比如消息里出现“创建/建立一个”时优先挂到task.create对应的技能组。Embedding召回把用户消息向量化和历史对话中各个技能组被调用的embedding做相似度匹配取Top2作为候选。LLM最终裁决如果前两层的候选不一致或置信度都不高才调用一次LLM来最终判断技能组归属。层级策略的目的可以理解为“默认不麻烦大模型只有小模型搞不定才找大模型”。大部分请求在硬规则或embedding阶段就能解决LLM裁决每天最多用到几次但每次都能兜底防止覆盖面不足尤其是在用户表达模糊的时候。3.4 技能预加载的边界不要加载无关参数还有一个容易忽略的细节——“按需加载”不仅在技能选择层面需要在参数schema层面同样需要。比如user.get_info这个技能在正常情况下只需要一个参数user_id。但如果你为了后端方便在schema里塞了include_permissions、include_department_tree、include_recent_activity等一堆可选参数模型反而会犯难它不确定该填哪个、填几个。结果就是它经常把这些可选参数填成true导致后端查询变慢、返回结果臃肿。我的建议是一个技能暴露给模型的参数最多不要超过5个。多于5个参数时想办法把参数拆成子对象或分成多个技能。模型处理5个以内的参数最稳定超过这个数参数幻觉概率显著上升。4. 调用链路的设计——模型不背锅的工程实现4.1 从用户输入到技能执行的完整闭环一个技能从被选中到最终执行成功中间经过的环节比大多数人想象得多。在完整闭环中每个环节出错的可能性都是独立的。我当时梳理出的主要链路如下用户输入 → 意图路由意图路由 → 候选技能集合锁定候选技能 → 参数抽取LLM根据用户输入填充参数参数抽取 → 参数校验 / 补全代码层完成参数校验通过 → 技能执行函数调用执行结果 → 格式化返回给模型 → 模型生成回复在这条链路上第4步是最多项目容易缺失的环节。很多人都以为把参数从用户输入里抽取出来直接传给执行函数就完事了。但LLM的输出天然带有不确定性抽取出来的参数可能有缺失、格式不对、甚至根本是凭空编造的。代码层必须有参数校验和补全环节。4.2 参数校验与主动追问不要装模作样地“猜”我在参数校验上定的规则比较明确必须参数缺失不调用技能生成一个“追问用户”的响应而不是编一个默认值塞进去。格式不对统一做一次轻量级修正比如日期格式修不了就追问。有枚举约束的参数如果LLM给的枚举值不在预置列表里优先查一下是不是同义词映射到正常枚举值映射不了就追问。医学界有个基本法则是“先治病别添乱”我在Agent这里也是这个态度——参数不齐时可以追问但绝不能让代码瞎编数据。比如用户说“帮我订明天下午的会议室”但没有说订哪个。模型如果把会议室ID猜成meeting_room_3后端如果刚好有这个会议室就会订错。这个结果的破坏力比“无法处理”要大得多。所以我后面专门做了一个“追问断言”机制技能执行前系统会检查是否所有标记为critical的参数都是真实存在的值不是的话就直接返回一个追问模板。模型只在拿到用户补充信息后才会真正执行技能。4.3 技能执行结果如何反馈给模型才算“高质量”技能执行完成后返回给模型的结果同样需要精心设计。直接返回原始的JSON dump会让模型在生成回复时“抓不住重点”。我后来养成了一个习惯技能执行函数返回给模型的内容不仅包含原始数据还要包含“数据摘要”和“建议表达”。举个例子任务详情技能执行完返回给模型的东西是{ raw: { ... }, summary: { task_title: 完成登录页改版, status: in_progress, assignee: 张三, due_date: 2025-03-20 } }前后对比来看这个设计就能让模型参考summary来组织回复不用在原始JSON里自己找重点。这样既降低了生成出错的风险也提升了回复的人性化程度。因为LLM直接参考摘要信息来组织回复原始JSON可以自由扩展到任意长度不会对回复质量产生影响。5. 技能执行的稳定性问题——你可能遇到的坑和解决思路5.1 问题是“技能没被调用”还是“技能调用后没按预期工作”Agent落地过程中稳定性问题最让人头疼。我发现排查链路走不通的根源往往在于初期的定位方向就错了——没有区分“模型没选中技能”和“技能被选中但执行出问题”是两种完全不同的bug。我自己的排查SOP是先做信息切分判断现象可能原因验证方式技能完全没被调用技能描述与用户请求语义不匹配、技能不在候选集中、路由模块误判查看模型决策日志确认候选技能ID列表技能被调用但参数错误参数schema与用户输入不匹配、description有歧义查看参数抽取结果与用户原始输入对比技能执行报错代码bug、外部依赖问题、超时直接调用技能函数做单元测试技能执行成功但回复不对返回结果格式问题、模型摘要逻辑问题检查返回给模型的原始数据和summary先把现象固定下来再往上追溯一般能在很短时间内找到问题源头。我最崩溃的那几次调试经历全都是因为一上来就在模型提示词上改来改去结果最后发现是技能描述有个中英文标点导致embedding完全错位。这种问题的成本其实都能通过日志前置阶段来规避。5.2 技能间的竞争干扰与处理思路二义性排除清单当技能数量增多两个技能描述天然会有部分重叠。比如“获取项目进度”和“获取任务进度”看起来是父子关系但在LLM看来就是两个高度相似的候选。处理思路是给技能描述添加排除性声明——明确写清楚它“不负责什么”。我称之为“负向描述法”。这两个技能如果都加了负向描述get_project_progress: 获取项目整体进度。返回项目里程碑完成情况和当前迭代状态。注意本技能不返回单个任务的进度查询任务进度请使用get_task_progress技能。 get_task_progress: 获取单个任务或子任务的进度。返回任务状态、完成百分比。注意本技能不返回项目级别的里程碑信息查询项目进度请使用get_project_progress技能。模型就能正确区分“项目”和“任务”这两个概念的交叉干扰会显著减少。当然负向描述也不能滥用——如果每个技能都写一大堆“这不是我干的”本身也会引入噪音。最好的时机是当你发现两个技能的混淆率超过了10%的时候才加负向排除不要在没有混淆问题的情况下提前加。5.3 技能依赖与顺序约束的表达实际项目里有一些技能之间存在依赖关系。比如“创建任务”之前必须先“获取项目ID”。但LLM本身不关心技能间的依赖它只会按语义匹配去选择。如果不加约束它可能会在用户说“在XX项目下创建新任务”时把项目名直接填到project_id参数里而不是先调用“获取项目ID”技能。解决这个问题的办法分两种场景参数缺失型依赖在参数校验阶段直接捕获。如果在task.create的参数里发现project_id为空或不是合法ID就自动插入“获取项目ID”的追问而不是让模型自己“猜”。这种方式不需要暴露给模型完全在代码层解决。流程强约束型依赖需要在技能描述里明确说明前置技能是什么。比如“发布上线”技能描述里就写“调用本技能前必须先调用‘获取待发布版本列表’技能”。实测下来这类强约束描述能有效减少LLM跳步骤的问题但也不是100%所以最稳妥的做法是在发布执行函数内部再做一次校验——如果发现前置条件不满足直接返回错误比让模型“意会”更安全。5.4 技能内部超时和失败重试的策略技能执行在真实场景下不可能一直不失败。外部接口可能超时数据库可能锁表内部服务可能临时不可用。这些失败如果不被处理Agent就会在生成回复时“硬编”一个天真的答案。我的策略分享是技能返回的结果中带上状态标记。{ status: error, error_type: timeout, retryable: true, message: 获取任务列表超时请稍后再试 }然后LLM看到retryable: true时会生成一个“当前服务暂时不可用是否需要我重试”的回复看到retryable: false时会生成“这个请求失败了原因是XXX”的回复。这个设计让模型区分“该不该重试”的决策由返回结果驱动而不是让模型自己去判断一个外部接口是不是临时故障。也经历过一个重试导致的重放问题。当时没有设计idempotency_key一个“创建任务”的技能在网络超时后重试了3次结果创建了4个一模一样的新任务。这是个非常严重的线上事故式bug后来所有带副作用的技能创建、更新、删除都强制要求支持幂等键重试请求必须带上同一个idempotency_key目标接口才能正确判断“这个请求我已经处理过直接返回上一次的结果”而不是再执行一次。6. 实测中比较有效的技能管理技巧6.1 让技能带“状态”和“版本”——可观测性的关键一步我见过很多Agent项目的技能都是无状态的函数集合没有统一的状态上报、版本管理、调用量统计。在初期或许能跑通等技能一多了就完全抓瞎。我给每个技能增加了一个薄薄的装饰层统一做三件事记录每次调用的输入输出脱敏处理后可存入本地日志。记录每次调用的耗时和结果状态。给技能函数挂版本号。这样每个技能就变得和一切可观测的后端服务一样能单独看成功率和P95耗时能比对不同版本技能的参数抽取差异。这听起来不算什么创新设计但在调模型行为时这个“可观测性层”远比反复试Prompt有效。6.2 技能“退路”设计——同一个能力有多套实现策略一个技能如果只有一种实现方式当它失败时这个技能就等于废了。但如果你给技能设计了多条实现路径系统的鲁棒性一下就上来了。举个例子“获取用户任务列表”这个技能第一实现方式是调用内部任务服务的API。如果这个API超时了第二实现方式是直接查询数据库归档表。如果两者都不可用第三实现方式是返回一个缓存过的快照。这样技能在外部依赖故障时仍然能提供降级结果而不是直接崩溃。关键是“退路”需要让模型知道吗不需要。这属于技能内部实现细节对模型不可见。模型只需要知道技能调用成功了或者技能明确返回失败。它的稳定性不会因为内部退路设计而改变接口约定只是内部的成功率提高了。6.3 新技能上线后的“灰度”策略新技能上线时我一般不会直接把它加入主候选集。原因很简单一个描述没调好的新技能不仅自己会犯错还会和其他老技能产生干扰导致老技能的准确率也跟着下降。我的策略是新技能先上线到“附加技能池”——它在被路由模块明确命中时才会加载不会出现在默认候选集里。运行一段时间后如果它在真实流量下的调用准确率达到95%以上就把它提升为主力候选。这个过程有点像“试用期转正”把新技能的试验成本控制在一个较小范围。这样做的另一个好处是新技能和老技能之间的混淆数据可以通过日志累积出来。如果新技能频繁在“用户请求明显是老技能场景”的情况下被误选说明你的描述边界还没写清楚还不适合转正。6.4 技能描述和路由模块的评估机制Agent技能体系上线后没有评估机制就无法迭代。很多人凭感觉改描述、改路由最后越改越差还不知道改了哪里导致变差。我们后来搭了一套轻量评估集机制固定了100条典型用户输入每条都标注了期望调用的技能ID和期望参数。每次调整技能描述或路由逻辑就跑一次这100条输入把技能选择的准确率和参数抽取的准确率都记下来。这套评估集成了后续技术选型和方案对比的决定性判据——比如有一次同事提议把所有技能描述改成更简短的英文版声称“token更少、语言更通用”。跑了评估集之后发现虽然token少了200但技能选择的准确率从94%掉到了89%。我们果断放弃了那版修改。评估集的设计也比较有意思——不要只放“标准问法”还要放模糊表达、省略表达、跨技能场景的表达。因为真实用户的输入永远不会像你写评测用例那么规范。模糊表达的覆盖比例至少占30%评估结果才比较可信。7. 从agent-skills到更长远的Agent能力演进思路技能体系的演进方式本身也是一个值得长期思考的话题。我目前的观察是技能的定义不是一成不变的它会随着业务场景的变化而生老病死。有些技能用了一阵子后发现问题太多不如直接废弃有些技能被拆得更细有些技能之间会慢慢合并成一个更大的领域能力。技能归档对不再使用的技能不要直接删除。保存到归档池里标注废弃原因和替代技能ID。这个操作在未来做技能复用或复盘时非常有用。技能模板化同类型的技能比如所有“列表查询”类技能往往有相似的描述结构。把这些模板沉淀下来新技能上线时照着模板写描述可以大幅减少因为描述风格差异带来的选择波动。跨项目迁移如果你的多个项目都跑在agent-skills体系上技能是有机会跨项目复用的。前提是你在设计之初就把技能描述得尽量与业务领域解耦让“获取任务列表”这类技能不绑定某个特定产品的内部术语。这样当新项目启动时很多技能可以直接从技能库导入不用推倒重来。回到开头那个问题——Agent的智能不完全来自模型本身更多来自你怎么组织它和世界交互的方式。agent-skills这条路我走下来最大的体会是把能力模块化了之后系统的行为才能被预测才谈得上优化和迭代。如果你的Agent还在为一堆不可解释的调用行为发愁不妨从技能化的重构开始至少能快速定位出问题的边界。最后说点实际的。做技能拆分的第一个月你的工作速度可能会变慢——每个技能都要写描述、定义schema、做验证、挂日志。但第二个月起这个积累就会开始回报你新需求的接入速度会变得非常快大部分场景都能从已有技能库里组合出来而不是每次都要重新调试模型行为。技能库这个东西越早建越香。
让我先理清一个概念这里说的不是传统意义上的“技能树”或“学习路径”而是给大语言模型驱动的Agent装配一套可复用、可插拔、可独立迭代的能力模块。把Agent的能力拆成“技能”本质上是把“模型知道什么”和“模型能做什么”彻底分开。我最早做Agent项目时踩过一个很深的坑把所有工具逻辑都塞进System Prompt里让模型“自由发挥”。结果Prompt越来越长模型越来越“笨”偶尔还会出现幻觉式的工具调用。后来我意识到问题不在于模型的推理能力而在于我把能力的边界和调用的逻辑混在一起了。Agent需要的是“技能”——边界清晰、行为可预期、能独立验证的模块而不是一段写在提示词里的愿望清单。这篇文章不聊泛泛的架构概念就讲我在实际搭建一个agent-skills体系时做的事情为什么要把能力拆成技能、技能的描述怎么写才不会被模型误读、参数提取和校验怎么做才不会翻车以及技能调用链路里最容易被忽略的几个隐患。适合正在做Agent应用、被“工具调用不稳定”折磨的开发者看。1. 先把“能力”和“知识”分开——agent-skills的起点1.1 一个让模型变“笨”的错误做法我之前有个项目叫“自动写周报Agent”初版实现非常简单在System Prompt里写了十几条工具调用规则把公司内部接口的URL、鉴权方式、参数格式全堆进去然后让模型根据用户输入自己决定调哪个接口。那版本实际跑起来之后问题非常典型提示词有2000多token模型每轮对话都要把这些内容重新“读一遍”响应速度肉眼可见地变慢。更离谱的是当用户说“帮我写一下本周的周报”时模型有时会直接调用“获取用户信息”接口而不是“获取本周任务”接口——因为没有边界约束模型会凭语义相似度猜。后来我把这些接口能力重构为一个个独立技能每个技能包含能力描述、输入参数schema、执行函数、触发条件示例。模型只需要看到一份技能清单按需求选择技能ID并传参剩下的执行逻辑全部由代码接管。效果立竿见影Prompt缩短到300token以内工具调用的准确率从最初的不到70%提升到95%以上。1.2 什么是“技能”在Agent语境下的准确定义在agent-skills体系里一个技能需要满足三个条件边界清晰能明确说清楚“这个技能负责什么、不负责什么”。做不到这点的技能拆分就是失败的拆分。输入输出严格定义输入是结构化的参数而不是自然语言输出是结构化结果而不是自由文本。这是为了后续的校验和可观测性。可独立测试一个技能应该能脱离Agent单独被调用和验证。如果你的技能函数只能在完整Agent环境里跑通那测试和排障的成本会成倍增加。这三个条件中最容易出问题的是第一个。“负责什么”稍微模糊一点LLM就会在边界上犯迷糊。比如我当时把“获取用户信息”和“获取用户部门组织架构”分成两个技能结果模型经常在用户问“我们部门多少人”的时候调用前者——语义上有相关性但实际不是同一个能力。1.3 技能拆分的粒度怎么拿捏这是每个做Agent的人都会纠结的问题。拆太细技能数量爆炸模型在清单里翻找都费劲拆太粗技能内部逻辑太多参数schema复杂到模型无法正确填充。我的经验是遵循“动作最小化”原则一个技能对应一个不可再分的原子操作。举几个对比例子错误的拆分正确的拆分理由查询任务列表查询本周任务列表、查询已归档任务列表、查询待办任务列表同样的底层数据源但过滤条件和返回结构差异大混在一起会让参数模型混淆操作数据看板创建看板、更新看板、删除看板不同动作的参数集差异明显合并会让可选参数过多处理用户消息解析消息意图、生成回复草稿、发送消息这三个操作之间不是调用关系而是流水线关系各自需要独立的失败处理“处理用户消息”这个拆法我特别说明一下。我见过不少项目把“消息处理”做成一个大技能内部顺序调用好几个功能。表面上看起来只暴露了一个技能模型很“省心”但一旦消息发送失败你无法确认是意图识别错了还是草稿生成错了。拆成独立技能后每个环节的输入输出都清晰排障成本大幅下降。2. 技能描述的艺术——写给模型看的说明书不是写给代码的注释2.1 模型看技能描述的方式和程序员想的不一样很多开发者写技能描述时习惯性地站在“代码阅读者”视角写一堆技术细节函数签名、数据结构、内部实现逻辑。但LLM读技能描述时它实际上是在做两件事语义匹配这个技能和用户请求是否匹配和参数映射用户请求里的字段对应哪个参数。所以我后来总结出一个原则技能描述要站在“调用者”视角写清楚“什么情况下用我、用了我会发生什么、需要注意什么”。我之前写过一个“获取任务详情”的技能描述一开始是这样的获取任务详情。参数task_id任务ID字符串类型。返回任务标题、状态、负责人、截止时间。这个描述给我的感觉是太“干”了。模型确实能看懂但在多技能场景下它很难区分“获取任务详情”和“获取任务评论列表”该用哪个。改成这样之后效果好了很多当用户请求查看某个任务的完整信息时使用。需要提供任务ID。返回内容包括任务标题、当前状态、负责人、创建时间、截止时间、优先级。注意本技能不返回任务下的评论内容查询评论请使用获取任务评论列表技能。如果用户没有提供任务ID不要调用本技能应该主动向用户询问。区别在哪里新版描述多给了模型三个关键信息触发场景对“什么时候用”做了明确定义减少了二义性。负向排除明确指出“不返回评论内容”防止模型把评论和详情混在一起。缺参处理指引明确告诉模型“参数不齐时该干什么”避免模型在缺参时强行猜一个ID。这三个信息在你只有两三个技能时可有可无但当你技能清单到了十个以上它们就是区分稳定和不稳定的关键。2.2 技能清单的组织方式分组、排序、默认行为技能数量多了以后怎么把清单呈现给模型也是一个问题。我试过几种组织方式最后比较有效的是“三级结构”技能组: 任务管理 技能: - id: task.get_detail description: 获取任务详情 - id: task.get_comment description: 获取任务评论 默认技能: task.get_detail 技能组: 用户管理 技能: - id: user.get_info description: 获取用户信息 默认技能: none分组有什么实际好处好处是模型在决策时多了一个先验信号——先根据用户请求判断属于哪个领域任务/用户/项目再在该领域内选择具体技能准确率明显更高。默认技能这个设计尤其好用当模型不确定用户要干什么、但能大致判断属于哪个技能组时优先调用默认技能而不是返回“无法处理”。当然分组信息本身也消耗token。我的实测数据是30个技能分组展示比平铺展示多消耗约100-150token但工具选择的准确率从86%提升到94%这个开销非常值得。2.3 参数schema降低模型幻觉的关键战场参数schema设计是agent-skills体系里最容易被低估的环节。很多人直接拿Flask或FastAPI的路由参数定义来当schema用结果LLM把参数填得乱七八糟。我觉得核心问题在于LLM不是按类型系统思考的是按语义和上下文理解的。所以参数schema不仅要定义类型还要给出示例和约束。pythonskills_config { task.create: { description: 创建新任务, parameters: { type: object, properties: { title: { type: string, description: 任务标题一句话描述要做什么, maxLength: 100 }, priority: { type: string, enum: [low, medium, high, urgent], description: 优先级默认medium }, due_date: { type: string, format: date, description: 截止日期格式YYYY-MM-DD如果用户没说日期可能为空 }, assignee: { type: string, description: 负责人姓名如果用户没有指定则为null } }, required: [title] } } }注意上面这段schema的写法每个参数都给出语义说明枚举值写全还特别标注了“用户没说时该怎么办”。这比单纯写priority: string有效得多。原因也很简单——LLM在填充参数时会尽力利用description里的信息来决定这个字段填什么。你把约束写清楚模型就不会乱来。还有一点非常重要required数组要保守。尽量少于真实所需。因为LLM在缺参时倾向于“猜”而不是“问”。与其让它在required参数上强行编造不如把参数设计成可选然后在代码层做校验和追问。比如上面的assignee设为可选如果用户没指定负责人后端再主动通过追问技能来获取比让模型凭空猜一个合法但错误的名字要稳妥得多。3. 技能注册与触达机制——不要让模型在30个技能里大海捞针3.1 为什么你的技能越多模型越容易出错一个容易被忽略的事实是LLM在候选技能特别多时选择的准确率并不会线性下降而是会“雪崩式”恶化。我做过一个对照组实验5个技能时准确率97%15个技能时92%到了30个技能时直接降低到76%。原因不复杂——模型在做工具选择时本质上是在计算“用户请求”和“技能描述”之间的语义相似度。当候选集膨胀时不同技能描述之间的差异性反而变小了模型就更容易发生混淆。解决这个问题的思路不是“让模型变得更强”而是“减少模型做选择的负担”。3.2 按需加载只在需要的时候把技能放上桌我的做法是给技能加上触发条件trigger condition。系统在每轮对话开始时先根据用户消息做一次轻量级的意图预判只会把可能与当前任务相关的技能加载到上下文里。简单说我维护了一个路由模块它会做两件事将用户请求映射到一个或多个技能组而不是具体技能。把命中的技能组内所有技能的描述、参数schema加载到上下文里。举个例子用户说“帮我看看这个任务”。路由模块判断这是“任务管理”领域的请求于是把task.get_detail、task.get_comment、task.update等5个任务相关技能加载进来用户管理、报表分析等25个无关技能一概不出现在模型视野里。这样做的收益非常明显上下文长度大幅缩短响应变快。无关技能彻底“隐身”模型不可能误选。技能清单可以无限扩展只要同一时刻的候选技能保持在小规模即可。3.3 路由规则怎么写才不容易误判路由模块本身也可以是一个小型LLM调用也可以用规则或embedding相似度来做。我的实践是三层策略配合使用硬规则优先用户消息中包含特定关键词时直接映射到对应技能组。比如消息里出现“创建/建立一个”时优先挂到task.create对应的技能组。Embedding召回把用户消息向量化和历史对话中各个技能组被调用的embedding做相似度匹配取Top2作为候选。LLM最终裁决如果前两层的候选不一致或置信度都不高才调用一次LLM来最终判断技能组归属。层级策略的目的可以理解为“默认不麻烦大模型只有小模型搞不定才找大模型”。大部分请求在硬规则或embedding阶段就能解决LLM裁决每天最多用到几次但每次都能兜底防止覆盖面不足尤其是在用户表达模糊的时候。3.4 技能预加载的边界不要加载无关参数还有一个容易忽略的细节——“按需加载”不仅在技能选择层面需要在参数schema层面同样需要。比如user.get_info这个技能在正常情况下只需要一个参数user_id。但如果你为了后端方便在schema里塞了include_permissions、include_department_tree、include_recent_activity等一堆可选参数模型反而会犯难它不确定该填哪个、填几个。结果就是它经常把这些可选参数填成true导致后端查询变慢、返回结果臃肿。我的建议是一个技能暴露给模型的参数最多不要超过5个。多于5个参数时想办法把参数拆成子对象或分成多个技能。模型处理5个以内的参数最稳定超过这个数参数幻觉概率显著上升。4. 调用链路的设计——模型不背锅的工程实现4.1 从用户输入到技能执行的完整闭环一个技能从被选中到最终执行成功中间经过的环节比大多数人想象得多。在完整闭环中每个环节出错的可能性都是独立的。我当时梳理出的主要链路如下用户输入 → 意图路由意图路由 → 候选技能集合锁定候选技能 → 参数抽取LLM根据用户输入填充参数参数抽取 → 参数校验 / 补全代码层完成参数校验通过 → 技能执行函数调用执行结果 → 格式化返回给模型 → 模型生成回复在这条链路上第4步是最多项目容易缺失的环节。很多人都以为把参数从用户输入里抽取出来直接传给执行函数就完事了。但LLM的输出天然带有不确定性抽取出来的参数可能有缺失、格式不对、甚至根本是凭空编造的。代码层必须有参数校验和补全环节。4.2 参数校验与主动追问不要装模作样地“猜”我在参数校验上定的规则比较明确必须参数缺失不调用技能生成一个“追问用户”的响应而不是编一个默认值塞进去。格式不对统一做一次轻量级修正比如日期格式修不了就追问。有枚举约束的参数如果LLM给的枚举值不在预置列表里优先查一下是不是同义词映射到正常枚举值映射不了就追问。医学界有个基本法则是“先治病别添乱”我在Agent这里也是这个态度——参数不齐时可以追问但绝不能让代码瞎编数据。比如用户说“帮我订明天下午的会议室”但没有说订哪个。模型如果把会议室ID猜成meeting_room_3后端如果刚好有这个会议室就会订错。这个结果的破坏力比“无法处理”要大得多。所以我后面专门做了一个“追问断言”机制技能执行前系统会检查是否所有标记为critical的参数都是真实存在的值不是的话就直接返回一个追问模板。模型只在拿到用户补充信息后才会真正执行技能。4.3 技能执行结果如何反馈给模型才算“高质量”技能执行完成后返回给模型的结果同样需要精心设计。直接返回原始的JSON dump会让模型在生成回复时“抓不住重点”。我后来养成了一个习惯技能执行函数返回给模型的内容不仅包含原始数据还要包含“数据摘要”和“建议表达”。举个例子任务详情技能执行完返回给模型的东西是{ raw: { ... }, summary: { task_title: 完成登录页改版, status: in_progress, assignee: 张三, due_date: 2025-03-20 } }前后对比来看这个设计就能让模型参考summary来组织回复不用在原始JSON里自己找重点。这样既降低了生成出错的风险也提升了回复的人性化程度。因为LLM直接参考摘要信息来组织回复原始JSON可以自由扩展到任意长度不会对回复质量产生影响。5. 技能执行的稳定性问题——你可能遇到的坑和解决思路5.1 问题是“技能没被调用”还是“技能调用后没按预期工作”Agent落地过程中稳定性问题最让人头疼。我发现排查链路走不通的根源往往在于初期的定位方向就错了——没有区分“模型没选中技能”和“技能被选中但执行出问题”是两种完全不同的bug。我自己的排查SOP是先做信息切分判断现象可能原因验证方式技能完全没被调用技能描述与用户请求语义不匹配、技能不在候选集中、路由模块误判查看模型决策日志确认候选技能ID列表技能被调用但参数错误参数schema与用户输入不匹配、description有歧义查看参数抽取结果与用户原始输入对比技能执行报错代码bug、外部依赖问题、超时直接调用技能函数做单元测试技能执行成功但回复不对返回结果格式问题、模型摘要逻辑问题检查返回给模型的原始数据和summary先把现象固定下来再往上追溯一般能在很短时间内找到问题源头。我最崩溃的那几次调试经历全都是因为一上来就在模型提示词上改来改去结果最后发现是技能描述有个中英文标点导致embedding完全错位。这种问题的成本其实都能通过日志前置阶段来规避。5.2 技能间的竞争干扰与处理思路二义性排除清单当技能数量增多两个技能描述天然会有部分重叠。比如“获取项目进度”和“获取任务进度”看起来是父子关系但在LLM看来就是两个高度相似的候选。处理思路是给技能描述添加排除性声明——明确写清楚它“不负责什么”。我称之为“负向描述法”。这两个技能如果都加了负向描述get_project_progress: 获取项目整体进度。返回项目里程碑完成情况和当前迭代状态。注意本技能不返回单个任务的进度查询任务进度请使用get_task_progress技能。 get_task_progress: 获取单个任务或子任务的进度。返回任务状态、完成百分比。注意本技能不返回项目级别的里程碑信息查询项目进度请使用get_project_progress技能。模型就能正确区分“项目”和“任务”这两个概念的交叉干扰会显著减少。当然负向描述也不能滥用——如果每个技能都写一大堆“这不是我干的”本身也会引入噪音。最好的时机是当你发现两个技能的混淆率超过了10%的时候才加负向排除不要在没有混淆问题的情况下提前加。5.3 技能依赖与顺序约束的表达实际项目里有一些技能之间存在依赖关系。比如“创建任务”之前必须先“获取项目ID”。但LLM本身不关心技能间的依赖它只会按语义匹配去选择。如果不加约束它可能会在用户说“在XX项目下创建新任务”时把项目名直接填到project_id参数里而不是先调用“获取项目ID”技能。解决这个问题的办法分两种场景参数缺失型依赖在参数校验阶段直接捕获。如果在task.create的参数里发现project_id为空或不是合法ID就自动插入“获取项目ID”的追问而不是让模型自己“猜”。这种方式不需要暴露给模型完全在代码层解决。流程强约束型依赖需要在技能描述里明确说明前置技能是什么。比如“发布上线”技能描述里就写“调用本技能前必须先调用‘获取待发布版本列表’技能”。实测下来这类强约束描述能有效减少LLM跳步骤的问题但也不是100%所以最稳妥的做法是在发布执行函数内部再做一次校验——如果发现前置条件不满足直接返回错误比让模型“意会”更安全。5.4 技能内部超时和失败重试的策略技能执行在真实场景下不可能一直不失败。外部接口可能超时数据库可能锁表内部服务可能临时不可用。这些失败如果不被处理Agent就会在生成回复时“硬编”一个天真的答案。我的策略分享是技能返回的结果中带上状态标记。{ status: error, error_type: timeout, retryable: true, message: 获取任务列表超时请稍后再试 }然后LLM看到retryable: true时会生成一个“当前服务暂时不可用是否需要我重试”的回复看到retryable: false时会生成“这个请求失败了原因是XXX”的回复。这个设计让模型区分“该不该重试”的决策由返回结果驱动而不是让模型自己去判断一个外部接口是不是临时故障。也经历过一个重试导致的重放问题。当时没有设计idempotency_key一个“创建任务”的技能在网络超时后重试了3次结果创建了4个一模一样的新任务。这是个非常严重的线上事故式bug后来所有带副作用的技能创建、更新、删除都强制要求支持幂等键重试请求必须带上同一个idempotency_key目标接口才能正确判断“这个请求我已经处理过直接返回上一次的结果”而不是再执行一次。6. 实测中比较有效的技能管理技巧6.1 让技能带“状态”和“版本”——可观测性的关键一步我见过很多Agent项目的技能都是无状态的函数集合没有统一的状态上报、版本管理、调用量统计。在初期或许能跑通等技能一多了就完全抓瞎。我给每个技能增加了一个薄薄的装饰层统一做三件事记录每次调用的输入输出脱敏处理后可存入本地日志。记录每次调用的耗时和结果状态。给技能函数挂版本号。这样每个技能就变得和一切可观测的后端服务一样能单独看成功率和P95耗时能比对不同版本技能的参数抽取差异。这听起来不算什么创新设计但在调模型行为时这个“可观测性层”远比反复试Prompt有效。6.2 技能“退路”设计——同一个能力有多套实现策略一个技能如果只有一种实现方式当它失败时这个技能就等于废了。但如果你给技能设计了多条实现路径系统的鲁棒性一下就上来了。举个例子“获取用户任务列表”这个技能第一实现方式是调用内部任务服务的API。如果这个API超时了第二实现方式是直接查询数据库归档表。如果两者都不可用第三实现方式是返回一个缓存过的快照。这样技能在外部依赖故障时仍然能提供降级结果而不是直接崩溃。关键是“退路”需要让模型知道吗不需要。这属于技能内部实现细节对模型不可见。模型只需要知道技能调用成功了或者技能明确返回失败。它的稳定性不会因为内部退路设计而改变接口约定只是内部的成功率提高了。6.3 新技能上线后的“灰度”策略新技能上线时我一般不会直接把它加入主候选集。原因很简单一个描述没调好的新技能不仅自己会犯错还会和其他老技能产生干扰导致老技能的准确率也跟着下降。我的策略是新技能先上线到“附加技能池”——它在被路由模块明确命中时才会加载不会出现在默认候选集里。运行一段时间后如果它在真实流量下的调用准确率达到95%以上就把它提升为主力候选。这个过程有点像“试用期转正”把新技能的试验成本控制在一个较小范围。这样做的另一个好处是新技能和老技能之间的混淆数据可以通过日志累积出来。如果新技能频繁在“用户请求明显是老技能场景”的情况下被误选说明你的描述边界还没写清楚还不适合转正。6.4 技能描述和路由模块的评估机制Agent技能体系上线后没有评估机制就无法迭代。很多人凭感觉改描述、改路由最后越改越差还不知道改了哪里导致变差。我们后来搭了一套轻量评估集机制固定了100条典型用户输入每条都标注了期望调用的技能ID和期望参数。每次调整技能描述或路由逻辑就跑一次这100条输入把技能选择的准确率和参数抽取的准确率都记下来。这套评估集成了后续技术选型和方案对比的决定性判据——比如有一次同事提议把所有技能描述改成更简短的英文版声称“token更少、语言更通用”。跑了评估集之后发现虽然token少了200但技能选择的准确率从94%掉到了89%。我们果断放弃了那版修改。评估集的设计也比较有意思——不要只放“标准问法”还要放模糊表达、省略表达、跨技能场景的表达。因为真实用户的输入永远不会像你写评测用例那么规范。模糊表达的覆盖比例至少占30%评估结果才比较可信。7. 从agent-skills到更长远的Agent能力演进思路技能体系的演进方式本身也是一个值得长期思考的话题。我目前的观察是技能的定义不是一成不变的它会随着业务场景的变化而生老病死。有些技能用了一阵子后发现问题太多不如直接废弃有些技能被拆得更细有些技能之间会慢慢合并成一个更大的领域能力。技能归档对不再使用的技能不要直接删除。保存到归档池里标注废弃原因和替代技能ID。这个操作在未来做技能复用或复盘时非常有用。技能模板化同类型的技能比如所有“列表查询”类技能往往有相似的描述结构。把这些模板沉淀下来新技能上线时照着模板写描述可以大幅减少因为描述风格差异带来的选择波动。跨项目迁移如果你的多个项目都跑在agent-skills体系上技能是有机会跨项目复用的。前提是你在设计之初就把技能描述得尽量与业务领域解耦让“获取任务列表”这类技能不绑定某个特定产品的内部术语。这样当新项目启动时很多技能可以直接从技能库导入不用推倒重来。回到开头那个问题——Agent的智能不完全来自模型本身更多来自你怎么组织它和世界交互的方式。agent-skills这条路我走下来最大的体会是把能力模块化了之后系统的行为才能被预测才谈得上优化和迭代。如果你的Agent还在为一堆不可解释的调用行为发愁不妨从技能化的重构开始至少能快速定位出问题的边界。最后说点实际的。做技能拆分的第一个月你的工作速度可能会变慢——每个技能都要写描述、定义schema、做验证、挂日志。但第二个月起这个积累就会开始回报你新需求的接入速度会变得非常快大部分场景都能从已有技能库里组合出来而不是每次都要重新调试模型行为。技能库这个东西越早建越香。
系统设计与实现)
