Agent技能体系搭建实战：从工具调用到稳定技能输出

1. agent-skills到底在解决什么问题如果你过去半年一直在折腾各种Agent项目一定见过这个标题agent-skills。仓库里躺着一堆技能描述文件页面打开是密密麻麻的YAML或JSON配置乍一看像是给大模型写使用说明书。但真正动手试过之后你会发现多数人把精力放在了让Agent能调用工具上却忽略了让Agent形成稳定技能这件事本身才是瓶颈。先厘清一个概念技能不是工具。工具是原子能力比如搜索网页读取文件发送邮件技能是基于工具、经过编排封装之后形成的一种可复用的完成特定任务的能力单元。举个例子搜索网页是工具而调研一家公司的创始人背景就是技能——它可能要搜索、要打开链接、要抽取正文、还要把结果汇总成一段带出处的文字。前者调用一次就结束了后者需要多轮动作、判断中间结果、决定下一步最终产出一个稳定的输出。一个Agent如果没有技能体系只有一堆工具会发生什么每次执行任务时大模型都要现场决定先调什么、再调什么、怎么判断结果。任务简单还好一复杂就乱套模型可能反复调用同一个失败的接口可能在某个分支里忘了回退可能把中间结果攒在上下文里导致Token爆炸。而有了技能体系这些怎么干活的逻辑被沉淀下来Agent拿到任务后首先是匹配技能而不是临场发挥。这个标题之所以值得单独拿出来拆解是因为它背后是一整套工程方法技能的原子设计、技能库的积累和治理、技能的动态编排、失败后的降级和重试。这篇文章不会教你某个具体框架的API怎么调而是把我自己从零搭技能体系踩过的坑、验证过的模式以及我认为最容易被忽略的判断标准完整过一遍。2. 技能的最小单元从野路子到有契约开始动工之前你先要回答一个问题一个技能文件里到底该写什么很多人上手就写技能描述写得像广告词结果模型根本没按预期触发。我自己连踩三次之后才定下一套结构化写法。2.1 技能定义的核心字段名字、描述、参数、返回拿调研公司创始人背景这个技能来说最小契约至少包含四块字段要求我的写法示例name全局唯一动词开头research_founder_backgrounddescription说明触发条件、能力边界、适用场景当用户需要了解某公司创始人/核心团队的履历、教育背景、过往经历时使用。如果是上市公司高管优先调结构化数据接口parameters声明必填/可选约束格式company_name必填字符串、founder_name可选不填则自动识别return_schema定义返回内容的格式和保证字段{ founder: str, summary: str, sources: list[str] }缺少summary时视为失败这类字段本身不新奇但很多人栽在description上。给模型看的description不是给人看的说明文档它要起到路由关键词的作用——告诉模型什么情况下该想到我。如果你写负责研究创始人背景模型在帮我看看这家公司的老板是谁时根本不会命中。我的经验是把可能触发的高频说法全塞进去老板、创始人、CEO、谁在管这家公司、实际控制人这些口语化的触发词比一句正规描述有用得多。再提一个容易被忽略的细节参数的示例值。与其在schema里写一堆minLength、pattern不如给一两个真实的示例参数。模型在function calling模式下对示例的遵循度通常比对正则约束的理解更高。我在参数里加过examples: [字节跳动]之后参数漏传的概率明显下降。2.2 完成度判定到底凭什么说技能成功了这是我认为agent-skills整个体系里最被低估的一环。很多项目的技能定义只有执行逻辑没有验收逻辑造成一个实际场景模型把流程跑完了但产出的结果根本不能用系统却报技能执行成功。一个技能的返回必须包含两层信息执行状态和结果可信度。执行状态是指进程有没有走完比如有没有报错、有没有超时结果可信度是指产出物是否满足业务要求比如搜索到的创始人信息是不是同名的人。我的做法是给关键技能加一个confidence字段模型判断并写明理由比如{ status: completed, confidence: 0.87, confidence_reason: 已从三个独立来源交叉验证创始人姓名与任期其中两个来源一致 }不要小看这个字段它会直接影响你之后做技能纠偏和自动降级。如果连自己产出的结果质量都不知道技能的组合编排就更无从谈起。还有一点要提醒技能不要设计得太粗也不要切得太碎。太粗的技能完成一次完整的商业尽调内部逻辑黑盒模型不清楚中间状态出了问题无法定位太碎的技能读取页面标题提取第一个段落又让模型频繁做路由决策每多一次决策就多一次出错机会。我自己的尺度是一个技能内部包含3到8个工具调用步骤产出一个可交付的结果——比如一段总结、一份校验过的数据而不是一个中间状态。2.3 一次错误技能设计的复盘有段时间我做一个资讯聚合Agent最初的技能设计是分类抓取新闻——一个技能里塞了抓取科技新闻抓取财经新闻抓取体育新闻三套逻辑参数只有时间范围。结果模型调用时经常传错分类返回的结果五花八门。后来把逻辑拆成两个技能crawl_news_source只管抓取和清洗按来源区分域名classify_news_topic只管分类打标。两段逻辑各自可测模型的路由也清晰先按来源抓再按主题分类。改完之后分类准率从72%提到了91%。这个案例里有个通用教训当技能内部出现按不同参数执行完全不同逻辑分支的情况就该考虑拆技能了当技能出现刚执行完又要被另一个技能查询中间结果的情况说明切得太细。技能的拆分边界应该沿着结果的可复用性走而不是沿着代码抽象走的。3. 技能库的构建第一批技能是长出来的不是写出来的很多团队搭技能体系第一步就开大会脑暴列表把能想到的技能全写上去一口气做三十个。这种自上而下的做法基本都会烂尾。我自己从零搭过的技能库现在稳定在线的就十几个但每一个都是从真实使用日志里长出来的。3.1 日志驱动从哪里收集技能需求最有效的技能需求来源是Agent在无技能状态下的失误记录。你先让Agent裸奔——只挂工具、不做技能封装跑一段时间的真实任务然后翻执行日志同一个工具序列反复出现说明有模板价值可沉淀为技能某一步特定失败比如频繁解析HTML失败说明需要独立的清洗技能或纠错逻辑模型在两条路径之间反复横跳先搜A再搜B最后又回A说明该把循环判断收敛到技能内部。我第一版创始人背景调研技能就是这么来的。日志显示Agent平均要花9次工具调用才能完成调研其中出现了至少2次内容重复抓取、1次打开无关页面。把它封装成技能后工具调用压到4到5次Token消耗降了一半输出稳定性也明显提升。提示每次从日志里提炼技能时顺手记录这个技能是因哪个失败场景被创建的备注。别觉得这是形式主义三个月后技能库膨胀时你会感谢这些备注帮你做清理判断。3.2 版本管理与命中率追踪技能不是写完就固定了。我自己用两套指标管理技能的健康度命中率和修正率。命中率指的是在用户的新任务里模型是否主动选择了这个技能。如果某个技能上线两周命中率不足10%不是模型不会用就是脚本本身定位错了需要重写description或直接下架。修正率指的是技能执行完成后最终结果被模型修正的比例。这个指标很直观地反映了技能内部逻辑是否可靠。比如某个技能返回的confidence常常低于0.5、或者用户总要追加追问说明它的产出质量不行不要只顾着调prompt要审技能内部的流程设计。每次更新技能我都像改代码一样留变更记录字段包括updated_at、change_reason、prompt_version。原因很现实有时候模型能力升级比如换更强的底座模型同一个技能的命中率和效果会整体漂移没有记录就只能全量排查。3.3 沙盒验证不拿生产环境试错技能在进生产库之前我会先在沙盒里做一轮回归。最笨但有效的方法是准备一组固定的验收任务集每个技能对应3到5个典型请求。比如research_founder_background的验收集调研一下某家电商公司的CEO背景这家公司的实际控制人是谁帮我查一下某个联合创始人的教育经历他在某大学读过书吗每次都记录命中、参数抽取、执行成功率、结果格式四个维度。跑三到五轮之后再决定是否放量。这套方法和后端开发的测试用例是同一个道理只是被测对象从函数变成了模型加技能的复合体周期的波动性更大所以判断阈值可以放低但流程必须存在。4. 技能的组合编排多技能协作才是Agent走向实用的分水岭单技能好用只是起点。真实业务里几乎都是复合任务用户一句帮我对标一下这两家公司的创始人团队再做个小结涉及技能调用、结果比较、合并汇总。技能之间的关系怎么编排决定了Agent复杂任务的上限。4.1 两种编排模式线性管线与动态路由我在项目里基本只用两种模式复杂程度再往上走就会陷入失控。线性管线适合流程确定的场景技能A的产出直接作为技能B的输入比如抓取原始页面的技能 → 正文抽取技能 → 摘要生成技能。这种模式的好处是可预测、可重试、每段可单独观测。问题在于一旦中间某个技能产出偏离预期后面会连锁跑偏所以每一步都要带校验。动态路由适合开放场景Agent根据用户请求自己串技能。比如用户要求分析这家公司的人才结构模型可能先调公司基本信息技能再判断要不要调招聘信息抓取技能还要结合岗位描述解析技能。动态路由的优势是灵活风险是模型选错路。我的实践是给这个自由度加护栏把所有可用技能按域分组比如调研域写作域数据处理域模型只能在一个域内自由路由跨域需要明确的推理理由这一步能挡住大部分瞎串联。4.2 上下文隔离与传递最常见的坑技能间协作最容易踩的坑是上下文传递。新手做法是把上一个技能返回的所有信息一股脑塞进下一个技能结果没两轮就把上下文窗口撑爆模型也开始抓不住重点。我现在的规则是按契约传递拒绝超集每个技能只接收前序技能返回契约里声明过的那几个字段其余一律丢弃。比如抓取技能返回的是content和metadata两个字段那么摘要技能只接收content至于metadata里的编码、来源URL如果摘要技能用不到就别传。另外技能内部如果产生过中间状态比如抓取了15个页面并且滤掉了5个这些过程数据也不会传给下游只把过滤逻辑的结论7个页面覆盖3个来源作为上下文片段简要记录。这样做有两个好处一是省Token二是让模型对全局信息的信噪比保持在一个健康的水平。实际感受是上下文里噪声一多模型就倾向于看起来有用但实际乱编的输出。4.3 组合技能的自检与回退编排场景里终局技能应该有一个自检动作。我通常加一步输出前自检让Agent基于最终输出往回确认一遍主要回答三个问题——结果是否覆盖了用户原始问题的所有子问题关键数字或结论是否有来源支撑有没有明显矛盾的信息自检不过的不是硬改结果而是触发回退回到最近一个可回退的分支节点换参数或换技能重跑。所以技能在设计阶段就要注意设置好分支节点和中间快照。回退也要设上限最多重试一轮第二轮开始前暂停一下确认整体方案是否从根本上就不对——很多时候问题出在技能选型错了不是参数问题。5. 从项目实践中提炼的几件麻烦事与对应的解决思路技能体系跑久了真正让你头疼的往往不是模型能力而是一些工程和治理层面的细节。我把踩过的几类麻烦事和解决思路放在一起说希望能帮你少走点弯路。5.1 技能失效模型的迭代会让技能整体漂移你的底座模型升级一个版本可能会改变description的命中行为、参数抽取的准确度和自检的严格程度。上个月还能稳定触发的技能换模型后可能命中率骤降。所以技能体系一定要和模型版本有联动机制每次模型变更跑一遍沙盒验收集重点关注命中率漂移。我在生产环境一直是技能版本模型版本双锁定的配置要么一起升要么一起降绝不让新旧版本混跑。5.2 结果看起来对但实际不对这是Agent应用里最隐蔽的风险。模型生成的自信总结、看似完整的表格可能在事实上经不起推敲。技能体系能做的是尽量把输出里的关键事实锚定到工具返回的原始数据上。比如调研类技能要求它在summary里的每个结论后面挂来源索引数据提取类技能要求它保留原始片段作为佐证。Agent方案如果要落地到严肃的业务场景宁可多花一点Token做可验证性也不要为了省Token让结果变成空口无凭。5.3 部分任务链断掉时的降级策略长链路由一旦中途出错直接放弃整个任务对用户体验非常糟糕。我现在会为多技能复合任务写部分完成降级的路径如果调研公司背景时创始人信息抓取失败但公司基本信息已经拿到那就先返回已有结果明确告知用户哪部分缺失并提供两个选项——重试缺失部分或换一种方式补齐。死撑到底的Agent会反复消耗资源一开始就允许部分成功反而更可靠。5.4 技能库治理定期删除比持续新增更重要技能库会像代码库一样腐化不是所有的技能都值得无限期保存。我每季度做一次技能审视筛掉两类一是连续一个月命中率低于阈值的二是和其它技能功能重叠的。删技能这件事比加技能更需要勇气但它是维持体系可控的核心手段。技能数量和Agent的整体准确率并不是正相关技能太多模型反而会因路由空间过大而频繁犯错。6. 现阶段对agent-skills的判断与一点体会agent-skills不是一个一次性的配置工程它更像一个需要持续经营的内部平台。好技能的标准不是实现了功能而是在合适的场景被合适地触发并交出可信赖的结果。我个人在实际操作里的体会是技能体系搭建的初期80%的精力要花在观察Agent怎么失败上。你不需要闭门造车地设计完美技能你需要做的是让它犯错、记下错误、把规避错误的方法封装成技能。迭代几轮之后技能库自然会形成一个贴合业务逻辑的骨架而不是一堆好听却用不上的空壳。最后分享一个小技巧每当你往技能库里加一个新技能时先在真实日志里找三个如果没有这个技能会失败的案例记进技能的README里。这个简单的动作能帮你拦住很多我觉得这个功能有用的伪需求也会让整个Agent的技能设计有据可依。