锦
锦思新知编辑组
发布时间:2026/11/16 22:32:53
来源:锦思新知
阅读:知识向官网定制

“agent-skills”这个名字是我从一次彻底失败的多智能体项目里捞出来的。当时我花了将近三周时间做了一个看起来什么都能干的自动化流程系统结果上线第二天就翻车了大部分请求都被模型自己“自由发挥”成了五花八门的调用方式真正沉淀下来的东西几乎没有。后来我复盘才发现问题根本不是模型不够聪明而是我压根没有给智能体一个明确、稳定、可复用的“技能体系”。说得直白一点每个任务都像临时工干完就走而不是像公司里的岗位说明书一样有边界、有流程、能交接。这篇文章想聊的就是我从这个坑里爬出来之后围绕“agent-skills”做的一整套技能库设计思路、踩坑经历和迭代方法适合正在做多智能体应用、又觉得系统越来越不受控制的开发者参考。1. 先说清楚agent-skills到底在解决什么问题很多人第一次听到“agent-skills”会以为它跟工具函数是一回事给模型一个函数模型按参数调用不就行了吗我一开始也是这么干的。但实际用下来你会发现工具函数解决的是“怎么调用”的问题而技能解决的是“什么场景下能干什么、干到什么程度、干了会有什么副作用”的问题。两者差别非常大。举一个具体例子。我曾经给系统注册过一个很简单的工具叫“查询订单”。函数本身逻辑很简单拉取订单数据格式化返回。但是当模型在对话中真正用到它的时候问题就来了有的请求是想查订单状态有的请求是想算退货截止日还有的请求是用户误以为“查询订单”能修改地址。工具层没有任何信息告诉模型它的能力边界模型只能靠函数名和参数名去猜。猜对了皆大欢喜猜错了就是一连串不可控的误操作。agent-skills要解决的正是这种“能力边界模糊”的问题。一个技能不能只是“能做的事”的集合它还应该包含四类信息触发条件什么场景下应该使用这个技能什么场景下明确不该用。输入输出契约每个参数的含义、格式、取值范围以及返回结果的稳定结构。约束与副作用比如“只读操作不修改任何数据”“调用后会产生一条日志”“需要人工审批才能执行”。失败模式什么情况会产生预期外的错误错误发生后应该怎么回退。你可能会觉得这些信息不完全可以写进模型的系统提示词里吗可以但提示词不是结构化数据模型对它的理解具有概率性。同一个边界描述改一下措辞模型的表现就能波动好几个百分点。技能的价值在于把不可靠的概率性理解变成相对可靠的契约式约束。这也是我把技能从“工具函数”升级为“一等公民”的核心原因。另外还有一层我认为很关键的理解技能的粒度。太粗的技能等于没拆解太细的技能会让调度成本爆炸。我后来形成的一个比较实用的标准是一个技能应该能被一句自然语言描述清楚且它的执行结果能被一个明确指标验证。比如“把英文文案翻译成中文并保持原有语气”就是一个合格的技能描述而“处理用户请求”就不是。1.1 技能与普通函数的分界线为了让自己不再陷入“技能就是函数”的误区我做了一个对照表每次往技能库里加东西之前都会先过一遍维度普通函数技能粒度偏向单点能力偏向完整的任务单元上下文通常不关心外部状态需要明确输入上下文和前置条件边界由调用方保证由技能自身声明复用单位代码级复用场景级复用失败处理抛异常需要定义可恢复的回退方案可测试性单测覆盖分支需要同时验证意图匹配与执行结果这个表帮我做了很多次决定。比如有些操作明明是个很小的函数但因为它经常被模型在多个场景中误用我就把它提升成技能加上约束和副作用说明反过来有些技能因为拆得太细调度器每次要串五六个才能完成一个任务我反而把它们合并成一个复合技能。分界线的判断没有绝对标准但有了这张表之后至少每次做决定都有依据而不是拍脑袋。2. 技能描述规范我踩过的最深的一个坑技能描述规范是整个体系里最不起眼、却最能决定成败的地方。我第一次做技能库的时候description字段写得非常随性基本是“这个技能能查天气”“这个技能能算价格”这种程度。上线后发现模型经常选错技能有时候甚至把两个功能相似的技能反复切换像人在两个款台之间犹豫不决。后来我才意识到模型的技能选择本质上是个阅读理解题。它读到的技能描述决定了它能不能把当前用户意图映射到正确的技能上。描述写得太短模型缺乏区分依据写得太长模型容易被无关细节干扰写得太抽象模型根本不知道这个技能实际能产出什么。我后来总结出一套相对稳定的描述模板每个技能注册时都按这个结构写技能名称建议用“动词宾语”看着知道在做什么。 应用场景什么样的问题进来时应该优先考虑这个技能。 能力边界这个技能明确不做什么。 输入参数每个参数的含义和合法值域。 输出说明返回什么结构的数据以及关键字段的含义。 副作用与约束是否会写数据是否需要审批是否消耗额外资源 典型调用示例一份简短的输入输出示例帮助模型建立直觉。 失败处理什么情况下算失败失败后建议做什么。这套模板看起来啰嗦但它解决了一个真实的问题不同的模型、不同的版本对技能描述的理解能力并不一样。模板化之后至少我可以批量审查所有技能而不是靠一条条读文本凭感觉判断写得好不好。2.1 一个因为边界描述模糊导致的翻车现场有一次我在技能库里加了一个“生成商品卖点文案”的技能。Description写的是根据商品信息生成5条卖点文案。看起来没毛病。结果有用户在对话里说“我上架了一批新商品帮我写点东西”模型立刻调用了这个技能但用户其实是想让模型写一段直播间口播稿。虽然技能名称里有“文案”两个字但没有明确排除“口播稿”这个场景。模型选对了大方向却选错了具体内容形态。这种问题的根因不是模型笨而是我的技能边界没有写清楚。后来我在描述里加了一句“本技能用于图文商品详情页文案不适用于直播口播稿、短视频脚本、社交媒体短句”误用率直接下降了一大截。这件事给我的启发是技能描述里真正起区分作用的往往不是“它是什么”而是“它不是什么”。边界写得越明确模型的判断空间越小行为就越稳定。2.2 参数校验别让技能自己扛脏活技能描述之外另一个容易被忽略的是参数校验。很多开发者会把参数校验直接丢给函数实现去抛异常但智能体场景里模型有概率填出离谱的参数。比如一个查天气的技能模型在参数里传了一个“今天下午”这种相对时间你要是直接把这个字符串交给天气接口大概率返回垃圾数据。我在技能注册层的做法是每个参数都要声明一个类型和校验规则集模型生成参数之后先过校验再执行枚举值限定取值范围超出就要求模型重新提供。时间格式统一为时间戳或ISO格式相对时间必须转成精确时间。数量限制比如最多返回5条结果模型传了10直接截断。必填与可选必填缺失时不自动补默认值而是进入澄清流程。这套校验层的设计本质上是把一部分“模型猜测”的工作变成了“系统兜底”。模型可以犯错但我不能让错误一路传到下游接口。校验失败后的处理也很重要我推荐走“澄清回滚”而不是“报错终止”系统先告诉模型哪个参数不合法让模型自己修正一次修正不了再降级到默认值或安全返回。3. 把零散任务改造成可复用技能我做的一次系统性重构我第一次尝试构建技能体系时并不是从零开始设计而是在一个已经运行了两个月的老系统上做改造。老系统里的逻辑全是散落在业务流程代码里的各种判断分支模型的调用路径五花八门改造过程可以说是拆炸弹。我把它拆成三个步骤这几个步骤后来也成为我维护技能库的标准打法。3.1 第一步从日志里反推高频行为我没有先画蓝图而是先翻系统日志。我把过去两个月的调用记录全部拉出来按用户请求类型聚类统计出哪些操作被反复执行。结果很有意思排名前二十的操作占了大概70%的调用量但当时这些操作在代码里都只是几段逻辑碎片根本没有被当作独立能力对待。我把这二十个操作挨个拎出来给它们起名字、写描述、定边界然后注册成第一批技能。这一步的关键是“让技能来源于真实需求”。你可以凭想象力设计出很漂亮的技能库但如果它跟用户实际问的问题对不上模型再聪明也调不动。反而是那些日志里高频出现、边界又清晰的调用模式一注册进去立刻开始起作用。3.2 第二步给高频链路做任务分解有了二十个基础技能之后我发现很多请求不是单技能能完成的而是需要多个技能按顺序协作。比如“帮我整理这周的销售周报”这个请求实际上要拆成“拉取销售明细”“按品类做聚合统计”“生成图表”“写周报摘要”四个子任务。如果让模型自由发挥它可能跳过某一步或者调换顺序导致结果不稳定。这一步我做的事是把高频链路录成任务模板。每个模板固定了技能调用顺序、关键参数映射关系和中间产物的传递方式。模型进场后不再自由规划整个链路而是按照模板的骨架来走遇到模板没覆盖的新情况才允许它临时扩展。我身边也有人批评这种“模板化”太过死板会让智能体失去灵活性。我理解这个担忧但我的实际体感是对成熟业务场景来说稳定大于灵活。让模型在十个技能里自由编排成功率可能只有百分之六七十给它一条经过验证的链路模板成功率可以稳定在九十以上。灵活性应该留在模板没有覆盖的边界场景里而不是让每个请求都变成一场不可预测的即兴演出。3.3 第三步把刚走通的链路改造成新技能链路模板跑稳定之后还有一步很关键把那些被反复使用的链路整体打包成一个新的复合技能。比如销售周报这条链路我跑了大概两周基本没出过岔子于是直接注册成一个“生成销售周报”技能。这样处理带给我的直接好处是系统后续再遇到类似请求就不需要一步步拆解了只要在技能库里匹配到“生成销售周报”整条链路一次执行。这个流程让我对技能库的演进有了比较清晰的心智模型基础技能从高频操作中来复合技能从稳定链路中来技能库本身是一个不断向上抽象的系统。每一轮抽象都会减少模型做决策的次数也就减少了出错的概率点。4. 技能调度与协作比技能本身更难搞的问题技能库建好之后下一个问题立刻浮出水面模型怎么知道该用哪个技能这里我试过几种不同的方案也踩过不少坑重点说说我觉得真正值得坚持的做法。4.1 别只靠语义相似度做技能选择第一种诱惑是向量检索。把所有技能描述转成向量用户进来之后做相似度检索选出最相关的技能。这个方案在Demo里看着特别优雅但实际用起来很坑。因为用户意图跟技能名称常常不是字面相似更像是一种“语义跳跃”。比如“我的订单怎么还没到”它本质上是要查物流状态技能库里叫“查询物流进度”字面相似度不算特别高但确实匹配。可有时候用户说“订单能退吗”它又可能被检索到“查询订单详情”而不是“发起退货申请”。我遇到过最离谱的一次用户问“你们的客服电话是多少”向量检索把“拨打电话”技能算出了极高的相关度模型差点真的调用外呼接口。后来我调了阈值和映射规则情况才好一些。但这件事让我明白相似度检索只能作为初筛不能作为最终决策依据。4.2 我最终采用的组合式调度策略我测试了很多种调度方式之后最终采用的是“先检索候选集再交给模型做小范围判断”的组合思路。整个流程是这样的1. 用户请求进入调度层。 2. 先用向量检索召回候选技能控制在五个以内。 3. 再把候选技能的“名称场景边界”拼到调度提示词里让模型从候选中选择。 4. 模型选择结果后先做参数抽取和校验再执行技能。 5. 执行结果需要二次确认的进入确认流程不需要的直接返回。这套流程能在一定程度上控制模型的自由度。它见过所有技能但真正能选的只有候选集里那五个。这个设计的好处是技能库即使涨到一百个每次真实参与决策的技能也只有几个模型的选择压力小很多准确性自然也上来了。我还遇到过一个调度层的隐藏问题叫“技能覆盖冲突”。两个技能能力边界有重叠比如“修改订单”和“关闭订单”某次用户的表达同时命中两者模型选哪个都说得通。我的解法是在技能描述里的“能力边界”部分加互斥声明修改订单的描述里写“仅调整商品或收货信息不提供订单取消能力”关闭订单的描述里写“订单一旦关闭不可恢复请在执行前确认用户意图”。这样模型在候选集里看到两条描述时更容易根据关键词做出正确选择。4.3 并发与状态污染低级但致命的坑再往下深入一层是技能执行时的状态管理。多智能体系统的技能经常是多个请求并发调用的。最开始我为了效率把技能实例做成共享的结果出现了串数据的情况。一个用户查了自己订单另一个用户紧接着查返回结果竟然带了上次的缓存。后来我把所有状态都改成了请求级别的上下文隔离每次调用技能都会生成独立的上下文对象参数、中间结果和日志都存在这个对象里绝不共享。这里有个小技巧值得留意技能的副作用要跟状态分开看。状态是用户上下文的一部分而副作用是系统层面的动作。如果一个技能会写数据库我必须给它设一个“副作用等级”。等级为写操作的技能在执行前需要确认或留痕只读技能则不需要。我的原则是任何不是幂等的操作都要被当成潜在危险操作处理。比如“发送邮件”“生成支付链接”“删除记录”绝对不能让模型在无人确认的情况下自动触发。5. 技能库的测试与持续迭代不养“一次性玩具”技能库跟普通代码不一样它不是一个写完就跑的模块是一个需要持续维护的资产。我在早期最大的失误就是把它当成一次性开发任务来做写完注册完就以为万事大吉。结果过了一个月新模型版本发布原来表现良好的技能选择开始抽风我才意识到技能库必须有自己的测试和维护体系。5.1 给每个技能建立回归样本集我后来为每个技能维护一套“意图样本集”至少包含三种类型标准样本能明确命中该技能的请求。边界样本部分相关但可能误用其他技能的请求。反例样本看起来相关但绝不应该调用该技能的请求。回归测试跑起来很简单把样本集里的请求依次走一遍调度层看技能选择是否正确。我每次调整技能描述、修改调度提示词或升级模型版本之后都会跑一遍全量回归。这个方法听起来简陋但效果惊人。它帮我抓到的第一个大问题就是某个技能加了一个新场景描述之后把原本属于另一个技能的流量抢走了将近15%。5.2 用两个真实指标而不是感觉来判断技能好坏除了回归测试我还给每个技能记录了两个关键的线上指标调用成功率和用户纠正率。调用成功率比较好理解就是技能执行过程中出现可恢复错误的比例。用户纠正率是指用户对技能执行结果不满意、又手动修改或重新表达的比率这个指标更隐蔽但更重要。如果一个技能调用成功率有95%但用户纠正率高达30%说明技能虽然“跑完了”但根本没跑在用户的心趴上。我有个技能叫“生成欢迎语”最开始调用成功率九成以上可用户纠正率一直居高不下。后来看了反馈日志才发现模型生成的欢迎语风格太正式用户想要的是轻松日常的语气。技能本身没有错但它的输出范式和用户预期不一致。于是我调整了技能描述里的语气约束纠正率才慢慢下来。这件事告诉我技能迭代不能只看跑没跑通更得看结果跟用户预期是否对齐。5.3 版本管理与技能下线技能也会过时。业务变了原来的技能可能不再适用。我维护技能库时采用了一套很简单的版本标记可用当前推荐调用的技能。候选刚开发完还在灰度验证的技能。废弃不再推荐调用但保留历史日志可回溯。下线完全移除相关调用自动报错并引导模型走新技能。每次修改技能不直接覆盖原技能而是新开一个版本号。调度层默认调用最新可用版本但如果新版本翻车率上升我可以一键回退到旧版本。这个能力在快速迭代期特别重要有一次我刚改了某个技能的边界描述第二天回归测试发现误用率涨了一键回退之后系统立刻恢复了稳定那种感觉真的踏实。这套版本机制让我在迭代技能库时不再提心吊胆。我可以大胆试错反正每次改动都留了后门出问题先退回去再慢慢查原因。对一个长期运行的多智能体系统来说这种“可回退”的自信比一次到位的设计更重要。6. 几个让你少掉头发的实战经验最后聊几个零散的、但实际价值极高的心得。这些经验没法写成一套大理论却是我每次从事故现场爬出来之后总结出来的。第一不要轻视“技能执行后的二次确认”。我在早期设计里为了追求响应速度所有技能执行完直接返回结果。结果有一次模型根据一个模糊请求自动发了一封邮件用户压根没确认。虽然内容没啥问题但这种“先斩后奏”的方式让用户对系统的信任度掉了一大截。后来我定了一条规矩凡是有副作用的技能执行前必须让用户确认只读技能才可以直接返回结果。用户体验上损失了半秒信任度上赚回了很多。第二技能的命名比想象中更重要。模型是字面意思的动物它看到“订单查询”和“订单详情查询”这种名字真的会纠结。我后来统一把所有技能命名为“动词明确宾语使用场景后缀”比如“查询订单_客服场景”“查询订单_订单列表页场景”虽然看起来有点啰嗦但模型的选择准确性明显提高。第三技能库要有“空白技能”兜底。无论技能库建得多全总会遇到没覆盖到的请求。如果模型找不到任何技能匹配它就会开始硬编或瞎答。我给调度层加了一个“兜底技能”它不做任何实际操作只是输出“无法自动处理该请求需要人工介入”的安全回复。这个设计牺牲了一点自动化率但保证了系统不会因为强行执行某个不匹配技能而产生事故。第四不要一次性把所有技能全开放给模型。刚建好技能库时我恨不得把所有技能都放进去展示成果。结果模型面对几十个技能时选择准确率明显下降。后来我改成按场景分组每次只开放一组技能给模型。比如客服场景只开放客服相关技能内容生产场景只开放文案相关技能。这本质上是一个“分而治之”的思路也是我所有经验里对准确率提升最明显的一条。回头看看整个“agent-skills”体系的构建过程我最深的体会是它不是模型能力的替代品而是模型能力的边界载体。你把技能定义得越清楚模型的自由度就越可控你把技能的测试做得越扎实系统的行为就越可信。这个项目走到今天技能库里的技能已经成了整个系统最核心的资产衍生出来的经验也被我复制到了很多新的项目里。
知识建站
内容驱动
阅读友好版式
SEO 精细化
线索转化
这篇内容对您有启发吗?
预约一次免费方案沟通,我们会根据您的行业给出可落地的站点架构建议。
立即预约沟通