1. 为什么“先拆能力”比“先改 skill”更重要做 Agent 开发的人几乎都经历过这样一个循环发现 Agent 在某类任务上表现不行第一反应是去改 prompt、加工具、换模型或者干脆把整个 skill 重写一遍。改完之后跑几个 case感觉好像好了但换一批输入又崩了。问题出在哪出在跳过了最关键的一步——能力拆解。SkillFocus 这篇论文的核心主张其实就一句话在决定怎么改 skill 之前先把 Agent 到底缺哪种能力拆清楚。这个思路听起来朴素但真正落地的时候大部分人是没有做的。我见过太多团队skill 文件改了几十版每一版都在“调措辞”但从来没有人问过这个任务失败的根因到底是模型不具备某类推理能力还是 skill 没有把工具调用时机说清楚还是 harness 层面的上下文管理出了问题这三个问题的修复方向完全不同。如果是模型能力问题你改 skill 措辞改到天荒地老也没用如果是 skill 描述问题你换模型就是浪费钱如果是 harness 问题那跟 skill 本身根本没关系。SkillFocus 的价值就在于它提供了一套把“失败”拆解到具体能力维度的方法论让你在动手改之前就知道该往哪个方向使劲。这篇文章我会从论文的核心思路出发结合我自己在 Agent 项目里踩过的坑把“能力拆解”这件事讲透。适合正在做 Agent skill 开发、调优、评测的朋友也适合刚接触 agent skill 教程但还没搞清楚“为什么我的 skill 时灵时不灵”的新手。全文会围绕一个核心问题展开当你面对一个表现不佳的 Agent skill 时怎么系统性地定位问题而不是靠直觉瞎改。2. SkillFocus 的核心框架拆解2.1 能力维度的划分逻辑SkillFocus 最核心的贡献是提出了一套面向 skill 的能力分类框架。它不是简单地把能力分成“理解”“推理”“生成”这种粗颗粒的维度而是针对 Agent 执行任务的实际流程把能力拆成了几个可观测、可干预的层面。我理解这套框架的划分依据是这样的Agent 完成一个任务本质上要经过“感知输入 → 理解意图 → 规划步骤 → 调用工具 → 整合结果 → 输出响应”这条链路。每一个环节都有对应的能力要求而 skill 作为承载体它的描述质量直接影响的是其中某几个环节。SkillFocus 做的事情就是把这几个环节的能力要求显式化让你能对照着去检查我的 skill 到底在哪个环节掉了链子。具体来说论文把能力拆成了几个关键维度。第一个是任务理解能力指的是 Agent 能不能从用户输入里准确提取出任务目标、约束条件和期望输出格式。第二个是工具选择能力指的是在多个可用工具的情况下Agent 能不能选对工具、选对调用顺序。第三个是参数构造能力指的是 Agent 能不能根据任务上下文正确填充工具调用所需的参数。第四个是结果整合能力指的是工具返回结果后Agent 能不能正确解读并整合到最终输出里。这四个维度不是孤立的它们之间有依赖关系。任务理解错了后面全错工具选对了但参数填错结果也是废的。SkillFocus 的聪明之处在于它不要求你一次性把所有维度都做到完美而是让你先定位到最薄弱的那个环节集中火力去改。2.2 为什么不能直接改 skill这里要展开讲一个很多人容易犯的错误把 skill 当成 prompt 来改。Skill 和 prompt 有本质区别。Prompt 是给模型的一段指令模型读完就完了。Skill 是一个结构化的能力封装它通常包含元信息、触发条件、执行步骤、工具声明、示例等多个部分。你改 prompt 的时候改的是“说法”你改 skill 的时候改的应该是“能力边界和调用契约”。我举个例子。假设你有一个 skill 是“根据用户描述生成 SQL 查询”。如果 Agent 经常生成错误的 JOIN 条件你的第一反应可能是去 skill 里加一句“注意 JOIN 条件要正确”。但这句废话对模型没有任何帮助因为模型不是“不想”写对 JOIN而是它可能根本没理解表之间的关系。按照 SkillFocus 的思路你应该先拆这个失败案例里Agent 是没理解用户意图任务理解维度还是没选对表工具选择维度还是没搞清楚外键关系参数构造维度如果是参数构造维度的问题那正确的改法是在 skill 里补充表结构说明和外键关系示例而不是加一句“注意正确”。这就是“先拆能力再改 skill”的实际含义。拆解的目的是定位定位的目的是精准干预。2.3 能力拆解与 skill 迭代的关系SkillFocus 还有一个很重要的观点skill 的迭代应该是有向的而不是随机的。什么叫有向迭代就是每一次修改 skill都应该对应一个明确的能力提升目标。你这次改是为了提升工具选择准确率下次改是为了降低参数构造错误率。每次改完你都能通过评测集验证这个维度是否真的提升了。随机迭代是什么样就是今天觉得 skill 写得太短加一堆说明明天觉得太长删掉一些后天换个模型发现效果变了又把删掉的加回来。这种迭代方式本质上是在碰运气。我在实际项目里吃过这个亏。早期做的一个客服 Agent skill前后改了二十多版每次都是“感觉这次应该行了”但从来没有系统地记录过每次改动的目标和效果。结果就是改到后面连自己都不知道哪版最好只能凭记忆回滚。后来引入能力拆解的方法把每次失败案例都归类到具体维度改动的针对性一下子就上来了迭代效率至少提升了一倍。3. 能力拆解的实操方法3.1 构建失败案例的分类体系能力拆解的第一步不是去改 skill而是去收集和分类失败案例。这一步听起来简单但实际操作中有很多细节要注意。首先失败案例的来源要多样。你不能只拿自己手写的几个测试用例来跑因为你的测试用例往往覆盖不到真实用户的奇葩输入。理想情况下失败案例应该来自三个渠道线上真实 badcase、评测集里的失败样本、以及你自己构造的边界用例。线上 badcase 最有价值因为它反映的是真实分布评测集失败样本帮你发现系统性问题边界用例帮你提前暴露潜在风险。其次分类的时候要“一例一标”不要一个案例打多个标签。我见过有人把同一个失败案例同时标成“理解问题”和“工具问题”结果分析的时候根本不知道优先改哪个。正确的做法是先判断这个案例失败的第一因是什么。如果 Agent 是因为没理解任务才选错工具那第一因就是任务理解工具选择只是表象。分类体系可以直接复用 SkillFocus 的维度框架但要根据你的具体场景做调整。比如你做的是代码生成 Agent那可能需要在“参数构造”维度下再细分“语法正确性”和“逻辑正确性”你做的是数据分析 Agent那可能要把“结果整合”拆成“数值计算”和“可视化表达”。3.2 从失败案例反推能力缺口分类做完之后下一步是从分类结果里反推能力缺口。这里的关键是看分布不看单点。单个失败案例说明不了太多问题可能是偶发可能是输入太偏。但如果你发现 60% 的失败案例都集中在“参数构造”维度那这就是系统性的能力缺口值得优先投入资源去补。反推的时候还要注意区分“能力缺口”和“知识缺口”。能力缺口是模型本身不具备某种推理或执行能力比如它无法理解多跳逻辑知识缺口是模型缺少特定领域的信息比如它不知道你们公司的内部 API 参数格式。这两种缺口的修复方式完全不同能力缺口可能需要换模型或加 few-shot 示例知识缺口只需要在 skill 里补充说明文档。我自己的经验是大部分所谓的“能力问题”其实都是知识缺口。模型不笨它只是不知道。你把该给的信息给到位它的表现往往会有明显提升。所以反推的时候先假设是知识缺口补完信息再看效果如果还是不行再考虑能力缺口。3.3 建立可量化的能力评测基线反推出能力缺口之后你需要一个量化的基线来衡量改进效果。没有基线你就无法判断改动是有效还是无效。基线的建立要注意几点。第一评测集要固定。你不能这次用 A 集合测下次用 B 集合测那样结果没有可比性。第二评测指标要跟能力维度对应。如果你要改进的是工具选择能力那指标就应该是“工具选择准确率”而不是笼统的“任务完成率”。第三基线要跑多次取平均。Agent 的输出有随机性单次结果波动可能很大跑三次取平均能减少噪声。提示评测集不要太大初期 50 到 100 条就够了。关键是覆盖要全每个能力维度至少要有 10 条以上的样本否则统计意义不够。有了基线之后每次改 skill 都跑一遍评测看目标维度的指标有没有提升同时看其他维度的指标有没有下降。如果目标维度提升了但其他维度降了说明你的改动可能引入了副作用需要进一步分析。4. 基于能力拆解的 skill 修改策略4.1 任务理解维度的修复方法任务理解维度的失败通常表现为 Agent 答非所问、遗漏约束条件、或者输出格式不符合要求。修复这类问题核心思路是降低歧义。具体做法有几个。第一在 skill 的触发条件里写清楚“什么情况下用这个 skill什么情况下不用”。很多任务理解失败是因为 Agent 在不该用这个 skill 的时候用了或者该用的时候没用。第二在 skill 的执行步骤里把用户可能隐含的约束条件显式列出来。比如用户说“帮我查一下最近的订单”你要在 skill 里说明“最近”默认指最近 7 天除非用户指定其他时间范围。第三在输出格式部分给出明确的模板或示例不要让模型自由发挥。我做过一个实验同一个 skill一版只写“根据用户输入生成报告”另一版写“根据用户输入生成报告报告必须包含标题、摘要、正文三个部分正文不少于 300 字语气正式”。第二版的任务理解准确率比第一版高了将近 40%。这说明很多所谓的“理解问题”其实是 skill 没把要求说清楚。4.2 工具选择维度的修复方法工具选择维度的失败表现为选错工具、漏调工具、或者调用顺序错误。修复这类问题核心思路是明确工具的适用边界和依赖关系。在 skill 里每个工具都应该有清晰的描述说明它“做什么”“什么时候用”“输入输出是什么”。如果多个工具功能有重叠要明确说明优先级和选择依据。比如你有两个搜索工具一个查内部文档一个查公开资料那就要在 skill 里写清楚优先查内部文档内部文档没有结果时再查公开资料。对于有依赖关系的工具要在 skill 里把调用顺序写死。比如“先调用 A 工具获取用户 ID再用用户 ID 调用 B 工具查询订单”。不要让模型自己去推理顺序因为它可能推理错。把顺序写死虽然灵活性降低了但稳定性提高了。在大多数生产场景里稳定性比灵活性更重要。4.3 参数构造维度的修复方法参数构造维度的失败表现为参数缺失、参数格式错误、参数值不合理。修复这类问题核心思路是提供充足的上下文和示例。参数构造错误的根本原因通常是模型缺少构造参数所需的信息。比如你要调用一个天气查询工具需要城市名和日期但用户只说“明天天气怎么样”没提城市。这时候模型要么猜一个城市要么报错。正确的做法是在 skill 里说明如果用户没提城市默认使用用户注册时填写的城市或者追问用户。另一个常见问题是参数格式。比如日期格式有的工具要 “2024-01-01”有的要 “2024/01/01”。这种细节必须在 skill 里写清楚并且给出示例。不要指望模型能猜对它猜不对的。注意参数构造部分最容易犯的错误是“假设模型知道”。你觉得理所当然的信息模型可能完全不知道。写 skill 的时候要假设模型是一个刚入职的新人什么都要教。4.4 结果整合维度的修复方法结果整合维度的失败表现为工具返回了正确结果但 Agent 解读错了或者多个工具的结果整合逻辑不对。修复这类问题核心思路是明确结果的解读规则和整合逻辑。工具返回的结果往往不是最终答案需要进一步处理。比如搜索工具返回了 10 条结果Agent 需要判断哪条最相关计算工具返回了数值Agent 需要判断这个数值是否合理。这些判断规则如果 skill 里没写模型就会自由发挥发挥结果不可控。整合逻辑也要写清楚。比如你有三个工具分别返回了用户的基本信息、订单信息、物流信息最终输出需要把这些信息合并成一个完整的回答。合并的格式、顺序、优先级都应该在 skill 里定义好。5. 实操流程与关键环节5.1 从零搭建能力拆解工作流下面是我在实际项目中总结的一套工作流可以直接参考。第一步收集失败案例。从线上日志、评测集、人工测试三个渠道收集至少 50 条起步。每条案例记录输入、期望输出、实际输出、失败表现。第二步分类标注。按照任务理解、工具选择、参数构造、结果整合四个维度给每条案例打上第一因标签。如果某个案例确实涉及多个维度标注主因和次因。第三步统计分析。统计每个维度的失败占比找出 Top 2 的问题维度。如果某个维度占比超过 40%那就是当前最需要解决的问题。第四步反推缺口。针对 Top 2 维度逐条分析失败案例判断是知识缺口还是能力缺口。知识缺口补信息能力缺口考虑换模型或加示例。第五步修改 skill。根据缺口类型有针对性地修改 skill 的对应部分。每次只改一个维度改完跑评测。第六步验证效果。对比修改前后的评测指标确认目标维度是否提升其他维度是否受影响。如果效果不达预期回到第四步重新分析。这套流程看起来有点繁琐但跑顺了之后一轮迭代大概只需要半天时间。相比之前盲目改 skill 改一周还没效果效率提升非常明显。5.2 评测集的设计与维护评测集是能力拆解工作流的基础设施值得单独拿出来讲。设计评测集的时候要遵循几个原则。第一每个能力维度都要有覆盖不能只测任务完成率。第二样本要分层简单、中等、困难各占一定比例。第三要有明确的期望输出不能模棱两可。第四要定期更新把线上新出现的 badcase 补充进去。维护评测集的时候要注意版本管理。每次修改评测集都要记录改了什么、为什么改。否则时间长了你都不知道当前评测集和三个月前的有什么区别历史结果也没法对比。我自己的做法是评测集用 JSON 文件管理每条样本包含 id、输入、期望输出、能力维度标签、难度等级。每次跑评测输出一个结果文件记录每条样本的实际输出和通过情况。这样既能看整体指标也能下钻到具体样本。5.3 修改前后的对比验证方法对比验证是确认改动有效的关键步骤。很多人改完 skill 之后随便跑几个 case 觉得“好像好了”就上线了。这种做法风险很大因为你的几个 case 可能恰好是改动能覆盖的但其他 case 可能反而变差了。正确的对比验证方法是跑完整的评测集对比修改前后的指标。具体来说要看三个数目标维度指标的提升幅度、整体任务完成率的变化、以及非目标维度指标的变化。如果目标维度提升了整体完成率也提升了非目标维度没降那这次改动就是成功的。如果目标维度提升了但整体完成率没变说明这个维度的提升被其他维度的下降抵消了需要进一步分析。提示对比验证的时候要控制变量。每次只改一个地方不要同时改多个地方。否则你无法判断是哪个改动起了作用。6. 常见问题与排查技巧6.1 能力拆解中的典型误区第一个误区是过度拆解。有人把能力维度拆得特别细拆了二十几个维度结果每个维度的样本都不够统计意义不足。我的建议是初期就按四个维度来跑顺了之后再根据实际需要细分。第二个误区是混淆现象和原因。比如“Agent 输出了错误的 SQL”这是现象不是原因。原因可能是它没理解表关系也可能是它选错了表也可能是它参数填错了。拆解的时候要往下挖一层找到第一因。第三个误区是忽略 harness 的影响。有时候 skill 没问题是 harness 的上下文管理、工具调用编排出了问题。比如 harness 把工具返回结果截断了导致 Agent 拿不到完整信息。这种情况下改 skill 是没用的要改 harness。6.2 skill 改了但效果不升反降怎么办这种情况我遇到过好几次通常有几个原因。第一个原因是改动引入了新的歧义。比如你为了修复参数构造问题在 skill 里加了一大段说明结果这段说明让模型对任务理解产生了偏差。解决办法是改动尽量精简不要加无关信息。第二个原因是评测集不具代表性。你的评测集可能恰好偏向某种输入分布改动在这个分布上有效但在真实分布上无效。解决办法是定期用线上真实数据更新评测集。第三个原因是模型能力上限到了。有些问题确实是模型本身的能力瓶颈改 skill 解决不了。这时候要考虑换模型或者把任务拆解成多个子任务用多个 skill 协作完成。6.3 多 skill 协作时的能力拆解当你的 Agent 有多个 skill 的时候能力拆解会变得更复杂。因为一个任务的失败可能涉及多个 skill 的协作问题。这时候拆解的重点要从“单个 skill 的能力维度”转向“skill 之间的接口和编排”。具体来说要检查几个点skill 之间的输入输出是否匹配、调用顺序是否合理、错误处理是否完善、上下文传递是否完整。我做过一个多 skill 项目三个 skill 分别负责信息提取、数据分析、报告生成。单独测每个 skill 都没问题但串起来跑就经常失败。后来拆解发现问题出在信息提取 skill 的输出格式和数据分析 skill 的输入格式不匹配导致数据传递时丢失了关键字段。这种问题单看任何一个 skill 都发现不了必须从协作层面去拆。6.4 常见问题速查表问题现象可能的能力维度排查方向修复建议答非所问任务理解检查 skill 触发条件和任务描述明确触发边界补充约束条件选错工具工具选择检查工具描述和优先级说明明确工具适用场景写死调用顺序参数缺失或格式错误参数构造检查参数说明和示例补充参数来源和格式示例结果解读错误结果整合检查结果处理规则明确解读规则和整合逻辑多 skill 协作失败接口与编排检查 skill 间输入输出匹配度统一数据格式完善错误处理改动后效果波动评测方法检查评测集代表性和样本量扩大评测集多次取平均7. 我在实际项目中的几点体会做 Agent skill 调优这件事最怕的就是“凭感觉”。感觉这个 skill 写得不好感觉那个参数不对感觉换个模型会更好。感觉多了时间就浪费了。SkillFocus 给我的最大启发不是它的具体框架有多精妙而是它把“拆解”这个动作变成了一个必须前置的步骤。你不动手拆就不准动手改。这个约束看起来简单但执行起来能省掉大量无效劳动。我现在的习惯是每次发现 skill 表现不佳先花 20 分钟做一轮快速拆解收集 10 条失败案例快速分类看主要问题集中在哪个维度。这 20 分钟的投入往往能省掉后面几个小时的盲目试错。还有一个体会是skill 不是越详细越好。我早期写 skill恨不得把每个细节都写进去结果 skill 文件越来越长模型反而抓不住重点。后来学会了“分层写”核心约束写在最前面详细说明放在后面示例单独成块。这样模型能快速抓住关键信息不会被冗余内容干扰。最后分享一个小技巧给 skill 写一个“变更日志”。每次修改记录改了什么、为什么改、预期效果是什么、实际效果如何。这个日志不用很正式几行字就行。但坚持记下来几个月后回头看你会对自己的 skill 演进路径非常清晰也能避免重复踩坑。
1. 为什么“先拆能力”比“先改 skill”更重要做 Agent 开发的人几乎都经历过这样一个循环发现 Agent 在某类任务上表现不行第一反应是去改 prompt、加工具、换模型或者干脆把整个 skill 重写一遍。改完之后跑几个 case感觉好像好了但换一批输入又崩了。问题出在哪出在跳过了最关键的一步——能力拆解。SkillFocus 这篇论文的核心主张其实就一句话在决定怎么改 skill 之前先把 Agent 到底缺哪种能力拆清楚。这个思路听起来朴素但真正落地的时候大部分人是没有做的。我见过太多团队skill 文件改了几十版每一版都在“调措辞”但从来没有人问过这个任务失败的根因到底是模型不具备某类推理能力还是 skill 没有把工具调用时机说清楚还是 harness 层面的上下文管理出了问题这三个问题的修复方向完全不同。如果是模型能力问题你改 skill 措辞改到天荒地老也没用如果是 skill 描述问题你换模型就是浪费钱如果是 harness 问题那跟 skill 本身根本没关系。SkillFocus 的价值就在于它提供了一套把“失败”拆解到具体能力维度的方法论让你在动手改之前就知道该往哪个方向使劲。这篇文章我会从论文的核心思路出发结合我自己在 Agent 项目里踩过的坑把“能力拆解”这件事讲透。适合正在做 Agent skill 开发、调优、评测的朋友也适合刚接触 agent skill 教程但还没搞清楚“为什么我的 skill 时灵时不灵”的新手。全文会围绕一个核心问题展开当你面对一个表现不佳的 Agent skill 时怎么系统性地定位问题而不是靠直觉瞎改。2. SkillFocus 的核心框架拆解2.1 能力维度的划分逻辑SkillFocus 最核心的贡献是提出了一套面向 skill 的能力分类框架。它不是简单地把能力分成“理解”“推理”“生成”这种粗颗粒的维度而是针对 Agent 执行任务的实际流程把能力拆成了几个可观测、可干预的层面。我理解这套框架的划分依据是这样的Agent 完成一个任务本质上要经过“感知输入 → 理解意图 → 规划步骤 → 调用工具 → 整合结果 → 输出响应”这条链路。每一个环节都有对应的能力要求而 skill 作为承载体它的描述质量直接影响的是其中某几个环节。SkillFocus 做的事情就是把这几个环节的能力要求显式化让你能对照着去检查我的 skill 到底在哪个环节掉了链子。具体来说论文把能力拆成了几个关键维度。第一个是任务理解能力指的是 Agent 能不能从用户输入里准确提取出任务目标、约束条件和期望输出格式。第二个是工具选择能力指的是在多个可用工具的情况下Agent 能不能选对工具、选对调用顺序。第三个是参数构造能力指的是 Agent 能不能根据任务上下文正确填充工具调用所需的参数。第四个是结果整合能力指的是工具返回结果后Agent 能不能正确解读并整合到最终输出里。这四个维度不是孤立的它们之间有依赖关系。任务理解错了后面全错工具选对了但参数填错结果也是废的。SkillFocus 的聪明之处在于它不要求你一次性把所有维度都做到完美而是让你先定位到最薄弱的那个环节集中火力去改。2.2 为什么不能直接改 skill这里要展开讲一个很多人容易犯的错误把 skill 当成 prompt 来改。Skill 和 prompt 有本质区别。Prompt 是给模型的一段指令模型读完就完了。Skill 是一个结构化的能力封装它通常包含元信息、触发条件、执行步骤、工具声明、示例等多个部分。你改 prompt 的时候改的是“说法”你改 skill 的时候改的应该是“能力边界和调用契约”。我举个例子。假设你有一个 skill 是“根据用户描述生成 SQL 查询”。如果 Agent 经常生成错误的 JOIN 条件你的第一反应可能是去 skill 里加一句“注意 JOIN 条件要正确”。但这句废话对模型没有任何帮助因为模型不是“不想”写对 JOIN而是它可能根本没理解表之间的关系。按照 SkillFocus 的思路你应该先拆这个失败案例里Agent 是没理解用户意图任务理解维度还是没选对表工具选择维度还是没搞清楚外键关系参数构造维度如果是参数构造维度的问题那正确的改法是在 skill 里补充表结构说明和外键关系示例而不是加一句“注意正确”。这就是“先拆能力再改 skill”的实际含义。拆解的目的是定位定位的目的是精准干预。2.3 能力拆解与 skill 迭代的关系SkillFocus 还有一个很重要的观点skill 的迭代应该是有向的而不是随机的。什么叫有向迭代就是每一次修改 skill都应该对应一个明确的能力提升目标。你这次改是为了提升工具选择准确率下次改是为了降低参数构造错误率。每次改完你都能通过评测集验证这个维度是否真的提升了。随机迭代是什么样就是今天觉得 skill 写得太短加一堆说明明天觉得太长删掉一些后天换个模型发现效果变了又把删掉的加回来。这种迭代方式本质上是在碰运气。我在实际项目里吃过这个亏。早期做的一个客服 Agent skill前后改了二十多版每次都是“感觉这次应该行了”但从来没有系统地记录过每次改动的目标和效果。结果就是改到后面连自己都不知道哪版最好只能凭记忆回滚。后来引入能力拆解的方法把每次失败案例都归类到具体维度改动的针对性一下子就上来了迭代效率至少提升了一倍。3. 能力拆解的实操方法3.1 构建失败案例的分类体系能力拆解的第一步不是去改 skill而是去收集和分类失败案例。这一步听起来简单但实际操作中有很多细节要注意。首先失败案例的来源要多样。你不能只拿自己手写的几个测试用例来跑因为你的测试用例往往覆盖不到真实用户的奇葩输入。理想情况下失败案例应该来自三个渠道线上真实 badcase、评测集里的失败样本、以及你自己构造的边界用例。线上 badcase 最有价值因为它反映的是真实分布评测集失败样本帮你发现系统性问题边界用例帮你提前暴露潜在风险。其次分类的时候要“一例一标”不要一个案例打多个标签。我见过有人把同一个失败案例同时标成“理解问题”和“工具问题”结果分析的时候根本不知道优先改哪个。正确的做法是先判断这个案例失败的第一因是什么。如果 Agent 是因为没理解任务才选错工具那第一因就是任务理解工具选择只是表象。分类体系可以直接复用 SkillFocus 的维度框架但要根据你的具体场景做调整。比如你做的是代码生成 Agent那可能需要在“参数构造”维度下再细分“语法正确性”和“逻辑正确性”你做的是数据分析 Agent那可能要把“结果整合”拆成“数值计算”和“可视化表达”。3.2 从失败案例反推能力缺口分类做完之后下一步是从分类结果里反推能力缺口。这里的关键是看分布不看单点。单个失败案例说明不了太多问题可能是偶发可能是输入太偏。但如果你发现 60% 的失败案例都集中在“参数构造”维度那这就是系统性的能力缺口值得优先投入资源去补。反推的时候还要注意区分“能力缺口”和“知识缺口”。能力缺口是模型本身不具备某种推理或执行能力比如它无法理解多跳逻辑知识缺口是模型缺少特定领域的信息比如它不知道你们公司的内部 API 参数格式。这两种缺口的修复方式完全不同能力缺口可能需要换模型或加 few-shot 示例知识缺口只需要在 skill 里补充说明文档。我自己的经验是大部分所谓的“能力问题”其实都是知识缺口。模型不笨它只是不知道。你把该给的信息给到位它的表现往往会有明显提升。所以反推的时候先假设是知识缺口补完信息再看效果如果还是不行再考虑能力缺口。3.3 建立可量化的能力评测基线反推出能力缺口之后你需要一个量化的基线来衡量改进效果。没有基线你就无法判断改动是有效还是无效。基线的建立要注意几点。第一评测集要固定。你不能这次用 A 集合测下次用 B 集合测那样结果没有可比性。第二评测指标要跟能力维度对应。如果你要改进的是工具选择能力那指标就应该是“工具选择准确率”而不是笼统的“任务完成率”。第三基线要跑多次取平均。Agent 的输出有随机性单次结果波动可能很大跑三次取平均能减少噪声。提示评测集不要太大初期 50 到 100 条就够了。关键是覆盖要全每个能力维度至少要有 10 条以上的样本否则统计意义不够。有了基线之后每次改 skill 都跑一遍评测看目标维度的指标有没有提升同时看其他维度的指标有没有下降。如果目标维度提升了但其他维度降了说明你的改动可能引入了副作用需要进一步分析。4. 基于能力拆解的 skill 修改策略4.1 任务理解维度的修复方法任务理解维度的失败通常表现为 Agent 答非所问、遗漏约束条件、或者输出格式不符合要求。修复这类问题核心思路是降低歧义。具体做法有几个。第一在 skill 的触发条件里写清楚“什么情况下用这个 skill什么情况下不用”。很多任务理解失败是因为 Agent 在不该用这个 skill 的时候用了或者该用的时候没用。第二在 skill 的执行步骤里把用户可能隐含的约束条件显式列出来。比如用户说“帮我查一下最近的订单”你要在 skill 里说明“最近”默认指最近 7 天除非用户指定其他时间范围。第三在输出格式部分给出明确的模板或示例不要让模型自由发挥。我做过一个实验同一个 skill一版只写“根据用户输入生成报告”另一版写“根据用户输入生成报告报告必须包含标题、摘要、正文三个部分正文不少于 300 字语气正式”。第二版的任务理解准确率比第一版高了将近 40%。这说明很多所谓的“理解问题”其实是 skill 没把要求说清楚。4.2 工具选择维度的修复方法工具选择维度的失败表现为选错工具、漏调工具、或者调用顺序错误。修复这类问题核心思路是明确工具的适用边界和依赖关系。在 skill 里每个工具都应该有清晰的描述说明它“做什么”“什么时候用”“输入输出是什么”。如果多个工具功能有重叠要明确说明优先级和选择依据。比如你有两个搜索工具一个查内部文档一个查公开资料那就要在 skill 里写清楚优先查内部文档内部文档没有结果时再查公开资料。对于有依赖关系的工具要在 skill 里把调用顺序写死。比如“先调用 A 工具获取用户 ID再用用户 ID 调用 B 工具查询订单”。不要让模型自己去推理顺序因为它可能推理错。把顺序写死虽然灵活性降低了但稳定性提高了。在大多数生产场景里稳定性比灵活性更重要。4.3 参数构造维度的修复方法参数构造维度的失败表现为参数缺失、参数格式错误、参数值不合理。修复这类问题核心思路是提供充足的上下文和示例。参数构造错误的根本原因通常是模型缺少构造参数所需的信息。比如你要调用一个天气查询工具需要城市名和日期但用户只说“明天天气怎么样”没提城市。这时候模型要么猜一个城市要么报错。正确的做法是在 skill 里说明如果用户没提城市默认使用用户注册时填写的城市或者追问用户。另一个常见问题是参数格式。比如日期格式有的工具要 “2024-01-01”有的要 “2024/01/01”。这种细节必须在 skill 里写清楚并且给出示例。不要指望模型能猜对它猜不对的。注意参数构造部分最容易犯的错误是“假设模型知道”。你觉得理所当然的信息模型可能完全不知道。写 skill 的时候要假设模型是一个刚入职的新人什么都要教。4.4 结果整合维度的修复方法结果整合维度的失败表现为工具返回了正确结果但 Agent 解读错了或者多个工具的结果整合逻辑不对。修复这类问题核心思路是明确结果的解读规则和整合逻辑。工具返回的结果往往不是最终答案需要进一步处理。比如搜索工具返回了 10 条结果Agent 需要判断哪条最相关计算工具返回了数值Agent 需要判断这个数值是否合理。这些判断规则如果 skill 里没写模型就会自由发挥发挥结果不可控。整合逻辑也要写清楚。比如你有三个工具分别返回了用户的基本信息、订单信息、物流信息最终输出需要把这些信息合并成一个完整的回答。合并的格式、顺序、优先级都应该在 skill 里定义好。5. 实操流程与关键环节5.1 从零搭建能力拆解工作流下面是我在实际项目中总结的一套工作流可以直接参考。第一步收集失败案例。从线上日志、评测集、人工测试三个渠道收集至少 50 条起步。每条案例记录输入、期望输出、实际输出、失败表现。第二步分类标注。按照任务理解、工具选择、参数构造、结果整合四个维度给每条案例打上第一因标签。如果某个案例确实涉及多个维度标注主因和次因。第三步统计分析。统计每个维度的失败占比找出 Top 2 的问题维度。如果某个维度占比超过 40%那就是当前最需要解决的问题。第四步反推缺口。针对 Top 2 维度逐条分析失败案例判断是知识缺口还是能力缺口。知识缺口补信息能力缺口考虑换模型或加示例。第五步修改 skill。根据缺口类型有针对性地修改 skill 的对应部分。每次只改一个维度改完跑评测。第六步验证效果。对比修改前后的评测指标确认目标维度是否提升其他维度是否受影响。如果效果不达预期回到第四步重新分析。这套流程看起来有点繁琐但跑顺了之后一轮迭代大概只需要半天时间。相比之前盲目改 skill 改一周还没效果效率提升非常明显。5.2 评测集的设计与维护评测集是能力拆解工作流的基础设施值得单独拿出来讲。设计评测集的时候要遵循几个原则。第一每个能力维度都要有覆盖不能只测任务完成率。第二样本要分层简单、中等、困难各占一定比例。第三要有明确的期望输出不能模棱两可。第四要定期更新把线上新出现的 badcase 补充进去。维护评测集的时候要注意版本管理。每次修改评测集都要记录改了什么、为什么改。否则时间长了你都不知道当前评测集和三个月前的有什么区别历史结果也没法对比。我自己的做法是评测集用 JSON 文件管理每条样本包含 id、输入、期望输出、能力维度标签、难度等级。每次跑评测输出一个结果文件记录每条样本的实际输出和通过情况。这样既能看整体指标也能下钻到具体样本。5.3 修改前后的对比验证方法对比验证是确认改动有效的关键步骤。很多人改完 skill 之后随便跑几个 case 觉得“好像好了”就上线了。这种做法风险很大因为你的几个 case 可能恰好是改动能覆盖的但其他 case 可能反而变差了。正确的对比验证方法是跑完整的评测集对比修改前后的指标。具体来说要看三个数目标维度指标的提升幅度、整体任务完成率的变化、以及非目标维度指标的变化。如果目标维度提升了整体完成率也提升了非目标维度没降那这次改动就是成功的。如果目标维度提升了但整体完成率没变说明这个维度的提升被其他维度的下降抵消了需要进一步分析。提示对比验证的时候要控制变量。每次只改一个地方不要同时改多个地方。否则你无法判断是哪个改动起了作用。6. 常见问题与排查技巧6.1 能力拆解中的典型误区第一个误区是过度拆解。有人把能力维度拆得特别细拆了二十几个维度结果每个维度的样本都不够统计意义不足。我的建议是初期就按四个维度来跑顺了之后再根据实际需要细分。第二个误区是混淆现象和原因。比如“Agent 输出了错误的 SQL”这是现象不是原因。原因可能是它没理解表关系也可能是它选错了表也可能是它参数填错了。拆解的时候要往下挖一层找到第一因。第三个误区是忽略 harness 的影响。有时候 skill 没问题是 harness 的上下文管理、工具调用编排出了问题。比如 harness 把工具返回结果截断了导致 Agent 拿不到完整信息。这种情况下改 skill 是没用的要改 harness。6.2 skill 改了但效果不升反降怎么办这种情况我遇到过好几次通常有几个原因。第一个原因是改动引入了新的歧义。比如你为了修复参数构造问题在 skill 里加了一大段说明结果这段说明让模型对任务理解产生了偏差。解决办法是改动尽量精简不要加无关信息。第二个原因是评测集不具代表性。你的评测集可能恰好偏向某种输入分布改动在这个分布上有效但在真实分布上无效。解决办法是定期用线上真实数据更新评测集。第三个原因是模型能力上限到了。有些问题确实是模型本身的能力瓶颈改 skill 解决不了。这时候要考虑换模型或者把任务拆解成多个子任务用多个 skill 协作完成。6.3 多 skill 协作时的能力拆解当你的 Agent 有多个 skill 的时候能力拆解会变得更复杂。因为一个任务的失败可能涉及多个 skill 的协作问题。这时候拆解的重点要从“单个 skill 的能力维度”转向“skill 之间的接口和编排”。具体来说要检查几个点skill 之间的输入输出是否匹配、调用顺序是否合理、错误处理是否完善、上下文传递是否完整。我做过一个多 skill 项目三个 skill 分别负责信息提取、数据分析、报告生成。单独测每个 skill 都没问题但串起来跑就经常失败。后来拆解发现问题出在信息提取 skill 的输出格式和数据分析 skill 的输入格式不匹配导致数据传递时丢失了关键字段。这种问题单看任何一个 skill 都发现不了必须从协作层面去拆。6.4 常见问题速查表问题现象可能的能力维度排查方向修复建议答非所问任务理解检查 skill 触发条件和任务描述明确触发边界补充约束条件选错工具工具选择检查工具描述和优先级说明明确工具适用场景写死调用顺序参数缺失或格式错误参数构造检查参数说明和示例补充参数来源和格式示例结果解读错误结果整合检查结果处理规则明确解读规则和整合逻辑多 skill 协作失败接口与编排检查 skill 间输入输出匹配度统一数据格式完善错误处理改动后效果波动评测方法检查评测集代表性和样本量扩大评测集多次取平均7. 我在实际项目中的几点体会做 Agent skill 调优这件事最怕的就是“凭感觉”。感觉这个 skill 写得不好感觉那个参数不对感觉换个模型会更好。感觉多了时间就浪费了。SkillFocus 给我的最大启发不是它的具体框架有多精妙而是它把“拆解”这个动作变成了一个必须前置的步骤。你不动手拆就不准动手改。这个约束看起来简单但执行起来能省掉大量无效劳动。我现在的习惯是每次发现 skill 表现不佳先花 20 分钟做一轮快速拆解收集 10 条失败案例快速分类看主要问题集中在哪个维度。这 20 分钟的投入往往能省掉后面几个小时的盲目试错。还有一个体会是skill 不是越详细越好。我早期写 skill恨不得把每个细节都写进去结果 skill 文件越来越长模型反而抓不住重点。后来学会了“分层写”核心约束写在最前面详细说明放在后面示例单独成块。这样模型能快速抓住关键信息不会被冗余内容干扰。最后分享一个小技巧给 skill 写一个“变更日志”。每次修改记录改了什么、为什么改、预期效果是什么、实际效果如何。这个日志不用很正式几行字就行。但坚持记下来几个月后回头看你会对自己的 skill 演进路径非常清晰也能避免重复踩坑。
