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

1. agent-skills到底在解决什么问题

如果你过去半年一直在折腾各种Agent项目，一定见过这个标题：agent-skills。仓库里躺着一堆技能描述文件，页面打开是密密麻麻的YAML或JSON配置，乍一看像是给大模型写使用说明书。但真正动手试过之后你会发现，多数人把精力放在了"让Agent能调用工具"上，却忽略了"让Agent形成稳定技能"这件事本身才是瓶颈。

先厘清一个概念：技能不是工具。工具是原子能力，比如"搜索网页""读取文件""发送邮件"；技能是基于工具、经过编排封装之后形成的一种可复用的完成特定任务的能力单元。举个例子，"搜索网页"是工具，而"调研一家公司的创始人背景"就是技能——它可能要搜索、要打开链接、要抽取正文、还要把结果汇总成一段带出处的文字。前者调用一次就结束了，后者需要多轮动作、判断中间结果、决定下一步，最终产出一个稳定的输出。

一个Agent如果没有技能体系，只有一堆工具，会发生什么？每次执行任务时，大模型都要现场决定"先调什么、再调什么、怎么判断结果"。任务简单还好，一复杂就乱套：模型可能反复调用同一个失败的接口，可能在某个分支里忘了回退，可能把中间结果攒在上下文里导致Token爆炸。而有了技能体系，这些"怎么干活"的逻辑被沉淀下来，Agent拿到任务后，首先是匹配技能，而不是临场发挥。

这个标题之所以值得单独拿出来拆解，是因为它背后是一整套工程方法：技能的原子设计、技能库的积累和治理、技能的动态编排、失败后的降级和重试。这篇文章不会教你某个具体框架的API怎么调，而是把我自己从零搭技能体系踩过的坑、验证过的模式，以及我认为最容易被忽略的判断标准，完整过一遍。

2. 技能的最小单元：从野路子到有契约

开始动工之前，你先要回答一个问题：一个技能文件里到底该写什么？很多人上手就写"技能描述"，写得像广告词，结果模型根本没按预期触发。我自己连踩三次之后，才定下一套结构化写法。

2.1 技能定义的核心字段：名字、描述、参数、返回

拿"调研公司创始人背景"这个技能来说，最小契约至少包含四块：

这类字段本身不新奇，但很多人栽在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的技能设计有据可依。