写agent-skills之前先想明白一个问题大模型本身只会生成“文本”它做不了任何现实世界的事。查不了数据库、调不了接口、改不了文件、发不了通知。所谓智能体本质上就是让模型去“调用”各种能力而能力从哪来就是技能。一个稳定可靠的agent系统核心资产不在于模型选得多强而在于技能体系设计得好不好。我见过不少团队模型用得很新但技能写得很随意最终跑出来的效果跟玩具差不多。这篇文章我就围绕agent-skills这个话题从技能设计、描述注册、运行时编排、排障迭代这几个层面把我实际做过、踩过、验证过的经验完整梳理一遍。1. 为什么说技能是agent系统的核心资产1.1 技能到底解决的是什么问题先看一个最常见的场景。让大模型“帮忙整理本周的销售数据”。如果直接把这句话丢给模型模型能做的只有回复一段文字告诉你“你可以去查销售系统”然后就没有然后了。它不是不能执行而是缺少“执行入口”。而agent系统里我们通常会给模型暴露一批工具比如查询销售订单的接口、计算汇总的脚本、生成报表的函数。模型根据用户意图自主决定调用哪些工具、按什么顺序调用。听起来很顺但实际做起来问题立刻就暴露了接口一多模型根本不知道在什么场景下该用什么接口参数怎么填返回结果怎么处理。就算模型硬着头皮选了也经常选错。技能这个概念就是为解决这个问题出现的。技能不是一个个孤立的函数而是把“一个完整的操作意图”打包成一个可被模型理解、调用、验证的能力单元。它里面包含了对场景的描述、输入输出的约束、执行逻辑、异常处理。模型不需要理解系统内部到底怎么实现的它只需要读懂技能描述就知道我现在的任务对应哪个技能。1.2 技能、工具、工作流之间的边界很多人在设计技能体系的时候会把工具和技能混为一谈。工具是原子化的操作比如“发送HTTP请求”“读取文件”“执行SQL”。技能则是面向任务目标的封装比如“查询订单状态”“生成周报”“分析竞品价格”。举个例子查询订单状态这个技能内部实现里可能要调用两三个工具先查订单表再查物流接口最后把状态格式化。模型看到的是技能层的“查询订单状态”而不是三个裸接口。这就是分层的好处模型思考的负担小了判断准确性上去了。至于工作流它又比技能高一层。技能是单次能力调用工作流是多个技能按既定逻辑串联成一条流程。成熟的做法是三层结构工具层做基础能力技能层做任务封装工作流层做流程编排。每一层只关注自己的事情。1.3 真正影响系统成败的是技能设计的稳定性和复用性一个agent项目初期跑通demo很容易。难点在于当技能数量从10个增长到200个时系统还能不能稳定地选对技能、正确地执行。我见过不少系统在技能少的时候表现惊艳技能一多模型就开始晕头转向。问题大多出在同一个地方——技能之间的描述互相干扰、边界重叠、命名模糊。所以说技能体系不是写几个函数那么简单它是在给模型构建一套“操作系统”设计和治理能力决定了系统的天花板。2. 技能怎么拆从业务场景到能力单元2.1 拆解的顺序是从场景倒推不是凭空发挥我第一次设计技能体系的时候犯过一个典型错误觉得某个功能“可能用得上”于是提前把技能写出来。结果上线之后真正被模型高频调用的不到三分之一剩下的技能不仅浪费反而给模型的决策增加了干扰。后来我调整了策略一切从线上真实场景出发。先把手上的用户诉求列出来比如用户需要查询余额用户需要对比上个月和这个月的数据用户需要把导出结果发到指定邮箱用户需要根据库存阈值生成补货建议然后开始归纳。第一条是查询类技能第二条本质上是数据对比能力第三条涉及跨系统操作第四条是计算加规则判断。归纳完再去看哪些场景有公共底层能力可以复用。比如“查询余额”和“查询库存”底层都是查数据库但技能层应该分开因为语义不同、参数不同、返回值不同。2.2 技能粒度的判断标准技能粒度是个非常影响效果的设计决策。技能粒度太细模型需要多次调用才能完成目标推理链路变长出错概率指数上升。技能粒度太粗一个技能内部塞了过多逻辑灵活性又没了稍微变个场景就得新写技能。我常用三个标准判断粒度是否合适第一这个技能是否对应一个“用户可感知的任务目标”。比如“发送邮件”是一个目标“将分析结果发送邮件给指定收件人”也说得通但后者其实是两个技能的组合。优先保证技能和任务之间有清晰的映射。第二这个技能是否需要复用。如果一段逻辑在多个场景中都会用到应该拆出来当独立技能。比如“获取当前登录用户的信息”几乎所有业务技能都需要那就得独立。第三这个技能的控制流是否简单。如果一个技能内部需要复杂的分支逻辑、动态判断说明它承担了编排职责应该再往下拆。技能内部尽量保持“直线式”的执行路径分支放编排层处理。2.3 一个实际拆分案例我做过一个内容生产辅助agent技能拆分大概是这样素材采集负责从指定站点抓取相关素材素材清洗去重、格式统一、提取核心信息大纲生成根据素材生成结构化大纲内容撰写按大纲和素材生成初稿内容润色对初稿做风格统一、错别字修正审核流转提交给指定审核接口获取审批状态每个技能都对应内容生产链路中的一个明确阶段。更重要的是这套技能可以复用到不同的生产流程里有的流程省略润色直接审核有的流程需要多轮采集。因为技能边界清晰编排层可以灵活组合不需要改动技能内部实现。3. 技能描述与注册让模型准确“看到”并“选对”技能3.1 技能描述的重要性被严重低估模型选技能靠的不是代码逻辑而是技能清单里的文字描述。描述写得好不好直接决定了选型准确率。很多团队在技能实现上花了很多功夫描述却写得像注释最后模型自然选不对。技能描述的关键组成我总结为四块第一块是触发场景说明。要明确“这个技能在什么情况下应该被调用”。如果业务方反馈“XX场景经常答非所问”一半以上的情况是触达场景没写清楚。第二块是参数说明。模型需要知道要填哪些参数、参数格式是什么、哪些必填、哪些可选。参数描述务必写清枚举值和取值范围否则模型会在边界值上疯狂发挥。第三块是输出说明。输出结构什么样、可能有哪些状态最好给出示例这会显著降低模型对接结果的难度。第四块是约束限制。比如“仅限内部用户查询”“当余额不足时返回错误码4001”这些特殊规则必须写明否则模型会自创规则。3.2 命名规范少一点自由度多一点一致性技能命名是另一个容易踩坑的地方。很多开发者的命名偏向自然语言风格比如“用Python脚本获取某某平台数据”这种命名在早期可用但技能多了就会出问题。模型在理解上容易出现混淆。我建议技能命名遵循统一模式动词业务对象功能范围。例如query_order_detailsend_email_notificationgenerate_daily_reportcheck_stock_alert统一用英文小写加下划线的命名方式有利于模型识别和排序。中文也可以但必须全系统统一混用会很糟。技能名相当于给模型的“锚点”稳定、一致、可预测模型才能形成稳定的决策模式。3.3 注册中心把技能变成系统可执行的资产技能注册中心是整个技能体系的中枢。它负责管理技能清单、参数schema、版本信息、运行状态。实现思路不复杂核心就是一张结构化的技能注册表。每个技能注册项至少包含技能ID、技能名称、描述、版本号、入口函数、参数定义、返回定义、超时设置、可用状态。注册表可以做得很轻量甚至可以是一个规范化的目录结构加读取器。我实际更倾向于用配置文件集中注册再通过启动时加载的方式构建运行时技能列表。这样方便做离线校验也能在技能变更时通过配置中心动态生效。值得一提的是技能注册表不建议直接让模型去“读”原始配置。模型需要消费的是一份经过格式化的技能清单比如把技能ID、名称、描述、参数提取成模型友好的JSON拼接到系统提示词里。原始配置里可能有内部路径、鉴权细节这些信息不应该暴露给模型。4. 技能运行时从注册到真正执行的关键一跳4.1 技能调用的基础链路技能真正被调用走的链路是模型决策 → 解析出技能ID和参数 → 查注册中心确认技能存在 → 校验参数 → 执行技能 → 返回结果给模型。这条链路上每一步都可能出问题。我最常遇到的瓶颈不在技能实现本身而在模型的参数生成阶段。比如某个技能需要一个下拉框里的枚举值模型的参数解析结果里却传了一个不存在的值。这时系统不能直接把错误抛给模型而应该在参数校验层做一次“容错修正”。具体做法是注册中心会记录每个参数的取值范围。当模型传出的参数不在合法范围内时系统介入处理比如返回默认值、对参数做归一化映射或者留出交互澄清。不要指望模型永远一次生成正确参数系统的纠错能力才是稳定性的关键。4.2 技能执行中的上下文传递在编排过程中技能的输入输出很少是孤立的。前一个技能的输出很可能作为后一个技能的输入。这就涉及上下文传递的设计。我建议不要在技能之间直接传递复杂对象而是通过一个标准化的中间存储区来做流转。比如一段抽取好的结构化JSON就放在上下文里后续技能按需读取。每个技能执行完只把它对目标的增量补充回上下文避免把无关信息全部堆上去。上下文如果太臃肿模型的注意力会被干扰尤其是技能链比较长的时候表现特别明显。4.3 超时、重试与降级技能跑挂了怎么办这是所有agent系统都绕不开的问题。我第一次上线技能系统的时候技能超时直接导致整个任务失败用户体验非常糟糕。后来我做了三层保护超时保护。每个技能根据实际耗时设置独立的超时阈值。外部接口类的技能给长一点比如15到30秒本地计算类的技能给短一点比如3到5秒。重试策略。网络抖动或临时服务异常导致的失败值得重试。重试次数通常控制在2到3次且必须做指数退避不然外部系统会被重试流量打崩。降级方案。重试还是失败就得考虑降级。最轻量的降级是返回一个明确的错误信息让模型把“技能执行失败”作为已知信息继续推理。更高级的降级是切换到替代技能。比如主用A技能查询库存失败可以切到备用的B技能直接读取库存表。4.4 编排多个技能如何协同技能多了之后不可避免地要做编排。早期我倾向于让模型自由选择技能、自动规划流程。但在真实业务中这种完全自由的编排方式结果不太可控。后来我调整成“约束优先”的路线固定流程部分写成工作流配置比如第一步必须执行A第二步在B和C之间选一个第三步执行D。模型能选择的只有工作流内部的“可选节点”而不能随意改流程主体。这种方式牺牲了一些灵活性但换来了稳定性和可预期性。对于面向真实业务交付的场景可控比灵活更重要。5. 常见问题与排查技能系统能跑和能稳定跑是两回事5.1 模型老是选不对技能到底哪里出了问题这类问题排查优先级最高。一旦模型频繁选错技能整个系统就失去了价值。我的排查路径是有固定顺序的先看技能清单里有没有语义重叠的技能。比如一个技能叫“查库存”另一个叫“查商品信息”而商品信息描述里包含“库存数量”模型自然就会混淆。修复方式是把重复描述彻底删掉技能边界划清楚。再看描述里的“触发场景”是否覆盖了线上真实出现的用户问法。很多选错问题根源在于真实场景的表述没有出现在技能描述里。把线上日志里模型误判的样本拉出来反哺到描述里去是最有效的手段。最后看参数示例是不是足够直观。模型对参数的判断能力高度依赖于示例。描述里给出“参数格式: YYYY-MM-DD”和给出一两个完整示例表现差距非常明显。5.2 技能间互相干扰的问题技能数量上到50个之后一个很隐蔽的问题开始出现技能A的描述里出现了技能B的术语导致模型在调用A的时候调用成了B或者在调B的时候被A干扰。这类问题靠“看描述”极难发现。我的做法是建立技能冲突检测机制用关键词重叠分析来识别。每隔一段时间把技能描述里的关键词提取出来做一次相似度对比相似度超过阈值的一律人工介入调整。同时在技能注册的评审流程里把“新技能描述与现有技能描述的相关性”作为一个必检项能在大规模扩张时减少隐患。5.3 模型参数幻觉的治理模型在生成参数时偶尔会产生幻觉值比如把用户的的自然语言表述直接当作参数值传进来或者生成了跟上下文中完全不同的人物名字、ID。这类问题很难根除但可以有效治理。常规手段是参数校验与二次确认。校验规则除了类型和格式还需要加“关联校验”。比如某个技能要求传入用户ID系统就去判断这个用户ID是否在当前会话上下文中出现过没有则提示模型缺失。进阶手段是做“参数改写”即把模型生成的参数映射到已知合法值上。比如模型传出“A客户”系统就把它映射到A客户的标准引用ID上。5.4 技能链路中的日志与追踪技能系统的排障依赖的永远是日志质量和链路追踪能力。技能调用链中的每一次决策和执行记录都应该被完整记录下来。我常用的记录字段包括会话ID、用户输入、模型选中的技能、参数快照、技能执行状态、耗时、返回结果摘要、异常信息。链路追踪要能做到“按会话查全部记录”这样才能在做问题复盘时快速定位到具体环节。很多实际效果问题比如回答质量差最终都定位到了某个中间技能返回了错误数据。没有日志这类问题排查成本极高。6. 持续迭代技能库良性运转的日常维护6.1 版本管理与灰度发布技能一旦被线上调用就进入了“生产资产”的状态改动不能随心所欲。我强烈建议技能做版本管理。每个技能有一个当前生产版本可以同时保留多个测试版本新版本在隔离环境中验证通过后再切流量。版本切换时要有可回滚方案万一线上效果变差能立刻切回旧版本。6.2 回归集技能级测试的护城河技能系统特别怕“改一处坏一片”。一个技能内部逻辑调整了可能会导致依赖它的多个流程同时出错。自动化回归集是最有效的防线。回归集不需要覆盖所有业务场景集中覆盖高频核心链路就够了。每次技能改动跑一遍回归集能拦截大部分低级错误。回归集的具体形式我倾向于用“输入—期望输出—关键约束”三元组来定义。比如一个场景输入“查询本周销售数据”期望输出中包含汇总金额和环比关键约束是必须调用query_sales_stats技能且参数时间范围为本周。只要模型生成的技能调用链路和最终结果满足这些约束就视为通过。6.3 从单agent到多agent的技能治理当系统从单个agent扩展到多个agent时技能治理的复杂度又会上升一层。多个agent之间可能存在技能共享、权限隔离、命名冲突的问题。这时候建议引入“技能域”的概念。每个agent绑定一个技能域域内技能对该agent可见。跨域的技能调用走明确的授权通道不允许无差别可见。技能中心负责统一管理所有域的技能每个技能注册时需要声明所属域和可见范围。这套机制在实战里能省掉很多安全问题。6.4 技能库的演进节奏技能库不是一次性建设出来的它是跟着业务场景逐步长出来的。初期少而精中期广而全后期需要做收敛治理。我见过一些激进的做法什么场景都往技能库里塞最终变成“技能垃圾场”模型决策准确率直线下降。我个人的经验是每增加一个新技能都要同时评估是否可以合并或下线一个旧技能。技能库的总量控制在合理范围内保持“每新增一个场景技能库变化幅度可控”的节奏整个系统的稳定性就会明显优于无节制扩张的状态。7. 几个我花了很长时间才想明白的要点7.1 技能是给模型写的不是给自己写的写技能的时候开发者最大的思维惯性是“面向代码逻辑表达”。但技能真正的用户是模型它不看你的实现只看描述。所有内部逻辑的黑话、路径、常量都不应该出现在模型可见的描述里。把技能描述当成“面向智能助理的说明书”来写效果会好很多。7.2 模型能力会变但技能资产不会浪费模型从V1换到V2底层能力在提升但技能体系几乎可以全部复用。这说明技能体系是比模型更长期、更稳定的资产。投入精力做技能架构是在做“复利投资”值得长期坚持。7.3 大部分“模型不行”的问题其实是技能设计不行我经常遇到有人反馈这个模型不够聪明、那个模型不够好用。深挖下去一半以上都是技能描述不清、参数约束不严、场景覆盖不足的问题。先把技能体系打磨到位再判断模型的能力边界这个顺序不能颠倒。
