1. Agent技能体系不只是工具调用先理解它解决的核心问题1.1 为什么说技能是Agent的手感来源过去我在搭建Agent应用时最常踩的坑就是把所有能力都塞进一个巨大的Prompt里。最开始产品还能用但随着场景变多Prompt越来越长效果越来越飘。今天能答对的问题明天换个说法就答偏了。后来我把工作重心从调Prompt转向搭技能库情况才真正稳定下来。Agent的技能Skills并不是一个新概念但如果把它简单理解成给模型加几个函数那大概率体会不到它的威力。我更愿意把技能理解成Agent的手感来源它决定了Agent在特定场景下知道该按什么顺序、用什么方式、调用哪些能力去完成任务。好比一个老厨师切菜手上的功夫不是靠背菜谱而是反反复复练出来的肌肉记忆。Agent的肌肉记忆就藏在那一组组被精心设计过的技能里。所以agent-skills这个方向本质上回答的是一个问题如何让Agent不再是一个会说话的搜索引擎而是一个能稳定办事的协作体。它适合正在搭建AI应用的产品经理、正在做RAG或Function Calling的开发者、以及所有希望让AI从能聊走向能干活的实践者。1.2 技能体系的三个层次动作、流程与边界我习惯把Agent技能拆成三个层次来理解。最底层是动作技能对应一个具体的操作比如搜索网页读取文件发送邮件中间层是流程技能它把多个动作组合成一个稳定的工作流比如写一篇竞品分析报告需要经历搜索资料—整理大纲—逐段生成—格式排版最上层是边界技能它定义Agent什么时候该做什么、什么时候必须停下问人比如遇到不确定的信息时主动标注而不是编造。这三个层次缺一不可。很多人的技能库看起来功能齐全但Agent跑起来依然不听话原因多半是只做了动作层忽略了流程层和边界层。动作层解决能做什么流程层解决怎么做才顺边界层解决什么不能做。三者的关系有点像导航软件路网是动作路线规划是流程而限速和禁行规则就是边界。在具体实践中我刚建立技能体系时也走过弯路。一开始我把十几个技能平铺在库里面结果模型经常选错。后来我调整了策略把高频场景拆成独立的场景技能包每个技能包内部再按动作—流程—边界组织效果立刻不一样了。这也引出真正的重点技能要成体系而不是堆数量。一个优质的技能库应该像一支分工明确的团队而不是一群各自为战的散兵游勇。2. 技能库的目录规范命名、描述与参数设计的细节账2.1 技能文件的组织方式先让开发者看懂再让模型用对技能库的目录设计很多人不重视觉得反正是给模型看的文件名随便起。但我的经验是目录首先是给人看的其次才是给模型看的。因为技能库一定会迭代如果组织混乱维护成本会迅速超过开发成本。我推荐的做法是按照业务域划分一级目录比如research调研、content内容生产、data数据处理、communication对外沟通每个业务域下面再按具体场景放技能文件。每个技能用独立文件夹承载里面至少包含一个描述文件和一个执行脚本复杂技能还要配示例数据。这样做的好处有两个一是人找起来方便二是模型在调用时系统可以根据业务域前缀快速缩小候选范围减少误选。文件名本身也得讲究。不要用skill1test2这类无意义命名推荐采用动词对象的格式比如search_web、extract_pdf、generate_report。动词让模型知道这个技能是干什么的对象让它知道作用在什么数据上。还有一个小技巧在技能描述文件的开头加一行固定格式的标签例如[action]、[workflow]、[guardrail]这样可以帮模型在扫描技能列表时快速判断当前应该选哪一类。2.2 描述文本怎么写才不会被模型忽略这是我在实际测试中反复验证过的一点技能描述的好坏直接影响模型选择技能的准确率。描述写得太长模型容易被无关信息带偏写得太短模型又get不到适用场景。我摸索出一个黄金结构大概分四段第一段一句话说清楚这个技能做什么。第二段列出两到三个典型的适用场景用当用户需要……时使用此技能的句式。第三段明确说清楚不适用的情况比如当用户只需要闲聊时不要使用此技能。第四段补充输入参数的说明每个参数要写明类型和含义。举个例子一个生成周报的技能描述可以这样写按模板生成结构化的周报内容。 适用场景 - 用户需要把本周工作整理成周报 - 用户提供了零散的工作日志需要归纳汇总 - 用户需要按固定格式输出周报给团队 不适用场景 - 用户只是想聊一聊本周做了什么不需要成文 - 用户需要的是项目计划而不是工作总结 参数说明 - raw_materials: 用户提供的原始素材字符串格式 - report_period: 周报所属时间段字符串格式如2025-03-01至2025-03-07 - style: 风格偏好可选值为简洁、详细、数据导向有一个很微妙的点不适用场景比适用场景更重要。模型在开放场景下容易多做以为多调用技能就是多干活结果把不该处理的请求也处理了。把不要用写清楚等于给模型圈了一道围栏能明显降低误调用率。我做过一次对比加上不适用场景描述后周报技能的误调用率从22%降到了6%。2.3 参数设计最小可行原则字段越多模型越容易出错技能参数的多少和模型调用的稳定性是成反比的。参数越多模型在从用户对话中抽取参数值的时候就越容易出错。尤其是那些含义相近的字段比如日期和时间、话题和主题模型经常会填反。我的建议是每个技能的入参控制在五个以内能合并的字段坚决合并。比如生成周报的时间段在早期设计里拆分了start_date和end_date两个字段看起来挺合理但模型经常只填一个。后来我合并成一个report_period字符串让模型用自然语言描述比如上周一到周五再由脚本内部解析准确率一下子提升了不少。参数处理还有两个经验值得分享。第一要为每个参数设置默认值避免必填字段过多导致调用中断。第二脚本内部要对参数做清洗和兜底不要依赖模型完全填对。以搜索技能为例用户如果说搜一下最近的AI新闻模型中抽取的time_range可能很模糊这时候脚本可以默认回退到最近7天而不是直接报错。3. 一个技能从无到有的全流程从需求破译到行为验证3.1 第一步把用户意图拆成可执行的任务单元很多Agent产品经理有个误区觉得技能越多越好。但真正的起点不是我们要加技能而是用户这句话背后到底需要什么。我在接手技能库改造时第一步不是动代码而是把过去三个月的高频用户问题全部拉出来做了一遍意图归类。举一个实际案例。做内部知识库问答的Agent用户问得最多的几类问题包括报销标准是什么查政策、帮我找下去年某月的合同检索文档、这个月大家提交了哪些报销查数据。这三类问题看起来都要检索但底层逻辑完全不同查政策需要提升答案的来源权威性找合同需要精确匹配文件名查数据则需要连上结构化数据库。如果共用一个技能Agent要不就答得太泛要不就检索不到。所以拆任务单元的核心原则是按任务结果来拆不按输入形式来拆。凡是结果产出逻辑不同的哪怕输入看起来一样也应该拆成两个技能。相反的方向也一样如果两个问题最终要的是同一个东西即使问法完全不同也可以共用一个技能只是通过描述里的不同场景别名来触发。拆完之后还有一个动作就是给每个任务单元定义验收标准。这一步很多人忽略但我认为它是整个技能建设里性价比最高的一环。没有验收标准的技能就像没有考纲的考试Agent发挥得好不好全凭运气。我通常会为每个技能写三到五条输入—输出对比如问去年合同应该返回标题含2023和合同两个关键词的文档列表而不只是返回最相似的段落。有了这些用例后面做回归测试就有了锚点。3.2 第二步编排技能链路并设计异常出口单个技能做好之后下一步是考虑多个技能怎么衔接。Agent真实处理的任务很少是单个技能就能解决的更多时候是一条链路。比如用户说帮我分析一下最近竞品的动态整个链路可能是搜索行业新闻→抓取竞品公司公告→抽取关键事件→生成分析摘要。链路编排的经验是让模型走主干让脚本走支线。翻译成人话就是主干链路上每个节点之间的跳转逻辑由模型判断但每个节点内部的具体处理全部交给脚本。举个例子在抽取关键事件这个节点上模型只需要判断当前搜索结果里哪些页面值得深挖至于怎么抓取正文、怎么抽取时间地点全部由脚本干。这样模型承担的任务少出错率就低。异常出口是我特别想强调的。链路越长中间某个节点失败的概率就越大。很多Agent到了某个节点卡住了会反复重试最后直接报错体验非常差。我在设计每个技能时都会额外包一层异常处理搜索没结果时是降低关键词门槛重搜一次还是直接告知用户信息不足需要脚本里明确判断逻辑。把异常出口想清楚Agent表现会沉稳很多。3.3 第三步用场景化测试校验技能的稳定性新技能写完直接上线是非常危险的。我的流程是先离线测一批用例再扔到真实的Agent环境里跑一周灰度观察两个指标调用准确率和任务完成率。调用准确率指的是模型在恰当的时候选择了恰当的技能任务完成率指的是技能被调用后最终产出的结果是否满足用户预期。这两个指标经常出现背离。比如技能被选对了但因为参数抽取不全导致结果不对这时候问题就出在参数设计而非技能描述上。有一次我发现新技能的任务完成率只有50%但调用准确率96%排查半天发现问题出在参数清洗的边界当用户只提供一个文件名时脚本默认只搜标题字段不搜正文。后来我改掉了默认搜索策略完成率直接到了85%。4. 技能协作时的上下文管理与边界控制4.1 上下文窗口像一张饭桌得有人负责翻台技能调用必然涉及上下文管理这是很多Agent实践的隐性瓶颈。模型的上下文窗口再大也是有限的技能的输入输出、中间结果、历史对话全挤在里面很快就满了。我的打法是给上下文空间设置一个翻台机制对话历史只保留摘要技能返回的大段原文直接落盘不进上下文。落盘这个词听起来有点重但实际操作不复杂。比如搜索技能返回了十篇网页的全文这些内容不会全部塞给模型而是先把每个网页的一段摘要放进上下文全文保存为临时文件。后续Agent需要某个网页细节的时候再通过一个read_web_content技能按文件名去读取。这样既保证了模型决策时需要的信息量又避免了上下文被一次性撑爆。这个机制有个关键点上下文里放的一定是决策所需信息不是结果信息。模型要做的判断是哪篇网页值得读和哪些信息应该进报告至于网页具体讲了什么那是脚本该管的事。把这两类信息混在一起模型既做不好决策也做不好总结。4.2 技能间的动态依赖解析当技能库超过三十个的时候技能之间会出现依赖关系。比如generate_report技能内部可能依赖search_web和read_file两个技能。早期我把这些依赖写死在Python代码里结果每次调整技能都要改代码非常痛苦。后来我改成在技能描述文件中声明依赖项由调度层动态解析灵活性高了很多。动态依赖的核心思路是技能不直接调用另一个技能而是发出一个内部请求。举个例子generate_report在生成过程中发现自己缺少某个数据它不是自己去乱翻而是抛出一个结构化的事件比如{need: search_web, query: 2024年新能源汽车销量, top_k: 5}调度层收到这个事件后再决定调什么技能来处理。这样做的好处是技能之间保持着松耦合调度策略可以独立调整。4.3 权限收敛技能能做的事必须能被审计Agent一旦开始真正执行任务权限管理就躲不过去了。我给Agent里每个技能都配置了最小权限原则搜索只能调用搜索接口发邮件只能走发邮件的通道读取文件也只能在限定目录里读。一开始开发阶段为了方便所有技能用的都是同一个管理员凭据结果有一次Agent在测试时误删除了一份重要文档从那以后我彻底改掉了这个习惯。除了权限审计日志也很重要。每个技能被调用时我会记录完整的入参和出参摘要包含调用时间、技能名称、关键参数、结果状态。这些日志主要有两个作用一是排查问题时有据可查二是做模型行为分析时可以回溯典型路径。没有审计的Agent黑盒感太强出了问题根本无从下手。5. 我反复踩过的那些坑从版本杂草到模型理解偏差5.1 技能描述的长度不是越长越好但也不是越短越稳技能描述长度这个度非常难掌握。踩过几次坑之后我的体会是描述的长度要和技能的复杂度成正比。一个简单的搜索技能描述写得长反而是负担模型会被绕晕而一个复杂的多步骤技能描述太短则无法覆盖边界情况。在调优时我会做一个简单测试把技能描述里的每一句话删掉看模型的调用准确率会不会变化。如果删掉一句话之后准确率反而上升说明这句话是噪音果断删除。反之如果删掉以后模型开始误选说明这句话不可或缺保留并考虑是否要加粗处理。这个方法听起来笨但非常有效几次迭代下来描述文本基本能做到字字有用。5.2 同名技能的版本地狱一旦技能库开始多人协作版本管理就成了一个大问题。有一次我们团队里两个同事分别开发了fetch_data技能的不同版本一个加了超时重试一个改进了参数抽取但文件名都叫fetch_data.py。结果在合并分支的时候冲突了半天不说Agent行为也跟着时好时坏。后来我们采用了严格的技能命名规范文件夹名带上场景前缀比如billing_fetch_data和risk_fetch_data。版本号也写进了技能描述文件里并专门建了一张技能版本对照表。这张表记录了每个技能从v1到当前版本的全部变更点每次发版后还要跑一遍全量回归测试确保没有引入行为漂移。版本问题还催生了一个好习惯技能变更必须有配套的变更说明。哪怕只是改了一个参数默认值也要写清楚为什么改、改了什么、对哪些调用方有影响。这个习惯刚开始觉得繁琐但坚持下来后技能库的可维护性提升了一个量级。5.3 模型偏科带来的技能失效同一套技能库换一个模型读效果可能天差地别。有些模型对结构化描述特别敏感参数列表归纳得清清楚楚有些模型擅长从自然语言描述里揣摩意图但对严格的JSON schema反而不太感冒。我吃过最大的亏是在一款推理能力较强的模型上把所有的技能都设计成了极其格式化的描述结果它的调用准确率还不如原来那款模型。现在我的做法是技能库要保持模型中立的描述风格不要针对某一款模型做过度优化。同时在实际部署时针对目标模型跑一遍技能选择的分类测试看看有没有明显的模型偏科现象。如果有要针对性地在描述里补充示例而不是去改模型或换框架。毕竟技能库沉淀的核心资产是逻辑和边界不是特定模型的偏好。5.4 技能的回归测试必须进流水线技能库跟代码库一样必须要有自动化测试来守护。之前我犯过一个低级错误因为改动了一个公共解析函数的默认参数导致三个上层技能的输入全部错位但当时只测了其中一个另外两个悄无声息地坏了三天。从那以后我建立了一套路子每个技能至少配一个最小测试和一到两个边界测试最小测试保底主路径边界测试覆盖参数异常和空输入。所有测试接入CI流水线每次技能变更自动触发全量用例。建立这套机制之后技能回归问题基本被消灭了剩下的问题多数是新加技能的场景覆盖不足这就属于迭代过程中正常的补全需求了。在实践了半年多技能体系建设之后我最深的感受是agent-skills真正的难点不在技术选型而在于你愿不愿意细致地打磨每一个技能的边界和描述。模型的能力水涨船高但技能库的逻辑和沉淀才是真正属于自己的壁垒。如果你正打算搭建技能体系我的建议是从一个高频小场景入手把链路跑通把验收标准和回归测试立起来再慢慢扩大覆盖面。这个过程急不来但每一步走扎实了Agent的可靠性会给你非常实在的正反馈。