AI Agent这两年从“能聊几句”进化到“真能干活”瓶颈早就不是模型本身的推理能力而是它手头有没有顺手的家伙事儿。我今年把好几个内部工具链统一重构了一遍核心就干了一件事把散落在各个Prompt里的临时功能收敛成一套可注册、可复用、可评估的“技能系统”。这套东西跑起来之后同样的任务Agent的完成率从七成左右提到了九成以上返工率降了一大截。今天把agent-skills这套设计和踩坑记录整理出来给正在折腾Agent落地的朋友做个参考。这个内容适合已经在用LangChain、OpenAI Function Calling或者其他Agent框架但感觉“模型老是听不懂人话、工具老是调不对”的开发者。也适合准备从零搭一个内部Agent平台、想一开始就把技能层设计清楚的架构师。如果你还停留在“写个Prompt试试看”的阶段这篇文章能帮你少走三个月的弯路。1. agent-skills到底在解决什么问题1.1 从Prompt到技能是一次组织方式的转变早期做Agent大家习惯把功能直接写进系统Prompt比如“当你需要查天气时调用weather_api”。这种做法的最大问题是你没法管理。Prompt越来越长模型越来越迷糊一会儿调这个工具一会儿调那个工具参数填错你都不知道是什么时候引入的。我把这层东西拆出来抽象成一个独立的技能层Skill Layer核心思路是不要教模型“如何调用工具”让模型只负责“判断该用哪个技能”调用的细节全部由技能定义来保证。类似工作里工具函数和模型之间多了个稳定的中间层模型只需要知道“有什么可用、什么情况下用”不用关心函数签名怎么传、异常怎么处理。实际改造完系统的可维护性直接提升了一个量级。新增一个能力不再需要改Prompt只需要注册一份新的技能定义几行JSON就能上线一个新功能。这和以前“改Prompt就像踩地雷”的体验完全不一样。1.2 做技能化之前先想清楚三件事动手改造之前我建议你先回答三个问题答不上来就先别动工。你的场景里有哪些高频、重复、确定性高的操作这些才值得做成技能。一次性、探索性的任务不应该被固化做进去反而是负担。你用什么指标判断一个技能“好用”推荐直接看任务完成率、平均执行轮数、工具调用成功率、用户返工率这几项后面详细讲怎么设计评估。你的工具调用链路里有哪些环节依赖模型“临场发挥”比如参数抽取、格式判断、超时处理。这些恰恰是技能层要消灭的不确定性。这三个问题想清楚了再决定技能怎么切分、怎么设计接口后面才不容易推倒重来。2. 核心技能的统一抽象设计2.1 技能定义的关键元素与规范一个技能至少要包含name、description、params、returns、version五个核心字段。description尤其重要它是模型决定“该不该用这个技能”的唯一依据一定要写清楚“这个技能能做什么、什么时候适合用、什么时候不要用”。我见过太多人把description写成一堆营销文案“本技能用于高效地完成”这种废话模型根本抓不住重点。提供一份经过实战验证的字段示例可直接参考{ name: fetch_webpage_text, description: 抓取指定URL的正文文本内容去掉导航、页脚、广告等噪声。适用于需要分析网页正文的场景不适用于需要登录、动态渲染严重的页面。, params: { url: {type: string, description: 目标网页的完整URL, required: true} }, returns: { type: object, fields: { title: {type: string}, content: {type: string, description: 清洗后的正文Markdown文本}, fetch_time_ms: {type: integer} } }, version: 1.2.0, tags: [web, extract] }注意看description的写法后半句明确写了“不适用于需要登录、动态渲染严重的页面”这就是在主动告诉模型“别瞎用”能大幅降低乱调用导致的任务失败率。这种负向约束比堆砌功能描述管用得多。2.2 技能注册表与依赖机制技能多了之后管理就成问题。我将所有技能定义集中放在一个技能注册表里支持按标签检索和版本管理。Agent每次启动时根据任务描述做一次技能检索只把最相关的几份定义注入上下文而不是把所有技能一股脑塞给模型。这一步对控制Token开销和减少模型混淆都很有帮助。再一个容易忽略的设计是技能依赖。我实际遇到过这种情况抓取网页的技能依赖“URL规范化”组件翻译技能依赖“语言检测”组件。组件不拆技能之间就互相耦合没法单独演进。所以我在技能定义里增加了depends_on字段注册的时候自动检测依赖项是否可用缺失就直接标记为不可用而不是让模型调用后才发现报错。这种前置校验特别重要等于把错误扼杀在入口处。2.3 技能数量与粒度怎么取舍技能切得太粗一个技能干十件事description怎么写都写不清模型选择困难。技能切得太细光检索就浪费时间每次光匹配就快赶上实际执行了。我实践下来的建议是每个技能只解决一个原子任务比如“抓网页”是技能“抓网页并总结要点”就是两个技能加一段编排。一个Agent上线的首批技能控制在8~12个跑通后再慢慢扩充。技能池超过20个必须上检索筛选否则模型的选择准确率会明显下滑。相近技能做合并比如“查A系统库存”和“查B系统库存”抽象成“查库存指定系统”一个技能通过参数区分。合并之后同样规模的场景技能数量能减少四成。3. 规划、工具调用与记忆的协同实战3.1 任务规划怎么与技能配合技能层建立之后Agent的推理流程我一般拆成三步和LangChain这类框架结合得很顺。第一步是任务理解模型把用户的一句话目标翻译成结构化的任务清单第二步是技能匹配针对任务清单里的每个子任务从技能注册表里检索最匹配的技能第三步是执行编排按依赖顺序执行每个技能的输出可能成为下一个技能的输入。一个完整的电商售后场景举个例子用户说“我上周买的手机壳还没到帮我查物流如果明天不到就申请退款”。技能库里就有查订单、查物流、提交退款、发通知四个技能。模型会在第一步把用户这句话拆成两个子任务分别匹配到查物流和提交退款。这看似简单但如果没有技能层模型往往会凭借印象乱调工具尤其是查订单和查物流的顺序经常会搞反。我建议在规划阶段就把“最大执行轮数”设好比如每轮最多允许3个技能串联。超过就中止并让用户确认避免模型自嗨型地连续调用好几个技能最后把一个简单问题绕成一场事故。3.2 工具选择的判定逻辑与参数注入工具选择的核心是让模型在“什么时候用什么技能”上做判断而不是在“这个工具内部怎么做”上做判断。所以我在技能定义里增加了一个usage_hints字段说明典型的触发场景和反例。这个字段不需要很复杂但一定要具体。参数注入方面有一个醒脑的教训别太信任模型自己生成的参数。我的做法是技能内部对参数做严格校验URL必须符合http/https格式日期必须是ISO格式ID必须存在。校验不过就返回结构化错误码而不是让模型重试。这看着增加了定义的成本实际省掉了大量无效重试和Token浪费。举一个真实踩坑最初让模型自己填日期范围它经常填错导致查询结果为空。后来改成技能内强制默认“近30天”除非显式传入起止日期成功率立刻上去了。所谓“把智能留给判断把笨活留给代码”就是这个意思。3.3 记忆与上下文窗口的管理技巧技能执行过程中的中间结果如果全部塞回对话上下文窗口很快就被塞满。我走的是双轨记忆方案。短期记忆用来存当前任务的执行轨迹和中间结果任务结束就清理长期记忆用来存技能执行的关键结果摘要和用户的偏好存进向量库后续任务先做相似度召回。比如用户经常要求“汇总结果要按价格排序”这个偏好会被记入长期记忆后续凡是触发汇总类技能就会自动加上排序偏好。这个功能单独看不大但累积起来对体验的提升非常明显因为用户减少了重复描述需求的次数。要注意给长期记忆设定TTL时间太长的旧偏好反而会干扰新任务我有一次就因为半年前的偏好没清理导致新的查询逻辑一直被带偏。3.4 技能测试与效果评估怎么做我为每个技能配置了一套独立测试集包含正常输入、边界输入、异常输入三类用例。正常输入验证主流程边界输入验证空字符串、超长文本、非法格式异常输入验证应该返回错误码而不是报崩溃。技能代码有改动时直接跑测试集只要通过率低于95%就算回归失败。系统层面关注四个指标任务完成率用户发起的任务中Agent自主完成的比例。平均执行轮数完成一个任务平均需要调用多少个技能。越低说明规划越准、技能越匹配。工具调用成功率技能执行成功次数除以总调用次数。低于85%就要警惕技能定义或内部逻辑出了问题。用户返工率用户发出纠正指令的比例。返工率高大概率是description写得不清楚或者技能粒度过粗。我把这些指标做成看板之后每次改动技能定义都能看到数值变化很快就能定位是哪个环节退化。没做评估之前全靠用户抱怨才知道出问题效率差太多了。4. 常见问题与实战排查实录4.1 模型就是不选正确的技能怎么办排查顺序我建议这样走先看技能的description是不是太泛再看技能的name是不是有歧义最后看技能是否真的被注册同步了别改了半天根本没生效。Description太泛是最常见的原因。想一下你现在这个技能如果让一个不熟悉你代码的人读description他能准确判断什么时候用吗如果不能就重写。我做过一次描述重构把“处理文档”改成“提取PDF中的表格内容返回二维数组适用于扫描版或电子版PDF”匹配准确率提高了将近两成。挑技能就是挑工具“名字清楚、用法清楚、边界清楚”三条缺一不可。4.2 工具调用返回结果不稳定这种问题早期的原因基本都在技能内部逻辑不在模型。我当时排查过一个“网页抓取偶尔超时又偶尔正常”的问题一开始怀疑是模型没传对URL后来发现是技能内部对慢响应站点没有超时控制。在技能层加上超时参数并规定超时后返回明确错误信息问题就解决了。不要看到一个失败就急着让模型重试。合理的做法是技能内部先做一层重试和降级比如抓取Detail页失败时自动抓取摘要页真的失败了就返回清楚的错误码模型基于错误码做下一步决策。这套机制上线后整体重试次数减少了四成。4.3 评估指标上去了但用户体验变差这种情况一般是指标设计有偏差。我遇过一次任务完成率明明在涨用户却反馈“你们这个Agent越来越自作主张”。后来查下来完成率上涨是因为模型倾向于“用一个错误但差不多完成的任务替代用户真实需求”于是任务被标记为完成实际上并没有满足用户。针对这个问题我在评估体系里增加了用户反馈验证环节即任务完成后主动询问“这个结果符合你的预期吗”把负向反馈率纳入核心指标。从那以后研发方向不再盲目追完成率而是真正去看用户满意度。不管你指标怎么做一定要把“伪完成”的漏洞堵上不然数据好看实际问题一点没解决。4.4 技能设计好后如何持续迭代技能不是一次写完就完了它是跟着业务一起演进的生命体。我建议每两周做一次技能利用率分析把调用频次最低、成功率最低、返工率最高的几个技能拉出来逐个判断该改进还是该下线。频次低但成功率高的技能要注意是不是使用门槛太高模型不会主动用频次高但成功率低的技能说明内部逻辑或描述有问题优先级最高。版本管理上技能定义一样要走Git流程每次改动必须留changelog。我见过有同事直接改了线上技能没记录改动一周后整个Agent行为变化了排查三天才发现是技能逻辑改了。版本记录这种东西平时觉得麻烦出问题的时候就是救命稻草。5. 团队协作与规范沉淀5.1 技能的评审机制技能数量多了以后质量问题就不只是代码问题更是协作问题。我在团队里定了一套技能评审清单提交新技能时逐项检查description是否有负向约束、参数是否做校验、是否有测试集、是否写明错误码含义、是否记录版本变更。这套清单看起来琐碎实际执行下来能拦住大量低质量技能流入线上。另一个很容易被忽略的问题是技能命名规范。我根据实际教训规定技能名必须体现行为动词加对象禁止使用相对词和模糊词比如process_data、handle_thing这类谁提交谁重写。命名混乱的直接后果是模型和人都不知道该选哪个技能一地鸡毛。宁可多花十分钟取名也不要上线后天天为混淆买单。5.2 从单Agent到多Agent的技能复用做完单Agent的技能化之后自然就会遇到多Agent协作的需求。我的经验是技能层和Agent层分开管理技能注册表是全局的Agent根据自身职责声明自己“启用”哪些技能。这样同一个技能比如查库存可以被销售Agent用也可以被客服Agent用逻辑只有一份不会出现两边各写一套、还经常不一致的窘境。多Agent场景下还要注意技能互斥问题比如两个Agent同时调用写权限技能容易产生数据冲突。我加了一层简单的技能级别锁写操作技能同时只能被一个Agent实例调用读操作技能不加锁。这个机制加上去之后数据不一致的问题被大幅消除。我自己在实际推进这套体系过程中有很深的体会技术的核心难点不是模型而是怎么设计一套边界清楚、可维护、能复用的技能系统。就像给一个能干但粗心的助手制定工作手册手册写明白了他才能发挥真实力。agent-skills这套方法我已跑了大半年从最初乱成一团的工具调用到现在技能注册、评估、迭代都有章可循省下的维护精力非常可观。如果你也在做Agent建议先挑自己场景里最痛的那两个功能按上面这套规范改成技能用两周时间测一测看看指标变化。就我个人经验来说这个投入的回报比几乎是我今年做的所有优化里最高的。