做Agent开发这两年，我踩过最大的坑不是模型选型，也不是框架折腾，而是"感觉这个Agent能用"和"确认这个Agent真的好用"之间的巨大落差。尤其是Skills这种模块化的能力单元，表面上看装个包、调个接口就行，实际上一进真实环境就各种翻车。后来我花了不少时间专门做了一个Agent/Skills专项能力评估的小系统，今天就把这套评估思路和落地经验完整分享出来。它不是什么高大上的平台，就是一个能围绕Agent本体和Skills技能做量化评估、可复现、能找问题的脚手架。如果你正在研究AI Agent、开发Skills，或者被"这工具到底行不行"折磨过，那这篇内容应该能给你省下大量试错时间。
1. 为什么要专门给Agent和Skills做评估
1.1 Agent开发热了，但"能不能用"没人说得清
现在的Agent生态有多热闹，不用我多说。pi agent、codex、opencode、claude code、hermes agent，各种框架和终端工具层出不穷，GitHub上的skills仓库、superpower skills这类资源也越来越多的。但是你会发现一个现象：大家都在秀demo、秀跑通的截图，却很少有人能拿出一套完整的数据说明"我这个agent在100个任务里能成功多少、失败原因分布是什么、token开销大概多少"。
原因很简单，做评估这件事本身很麻烦。Agent不是普通函数，输入输出不是固定的，它里面有一层LLM决策，同样的任务跑两次结果可能不一样。再加上工具调用、上下文管理、多轮交互这些环节，想用一个简单的准确率指标来衡量，根本不现实。
我自己之前就吃过亏。有个项目里用了一个前端开发的skills，本地跑demo的时候看着挺顺畅，结果放到实际业务流程里，连最基本的选择器都定位错。后来我去翻日志才发现，这个skill对上下文格式要求极其严格，只要前置信息缺失一点，它就开始瞎猜。这种事情不去做专项评估，光靠肉眼观察根本发现不了。
1.2 Skill和Agent是两种评估对象，不能混着来
搜索热词里大家经常把skill和agent放一起讨论，但做评估之前，先得把这两个概念分开。Agent是一个完整的决策和执行实体，它接收任务、规划步骤、调用工具、处理反馈、输出结果，是一个完整的闭环。Skill则更像是Agent手底下的一个专项能力包，比如"图片生成skills""LaTeX排版skills""前端组件生成skills"，它通常解决的是一个相对聚焦的子问题。
这两者的评估逻辑差异很大。评估Agent，看的是整体决策链路的稳定性，比如长任务的规划能力、多工具协作时的调度能力、中途出错后能不能自己纠正。评估Skill，看的则是单个能力单元的质量，比如给它一个规范的输入，它能否稳定输出符合预期的结果，边界情况处理得怎么样。
很多人在给Agent做优化时，上来就换模型、调prompt，回头发现效果还是不稳定，就是因为没有区分到底是Agent的编排逻辑出了问题，还是某个Skills本身不行。所以我设计这套评估系统，第一原则就是：Agent评估和Skill评估分层进行，互相独立又交叉印证。
1.3 能做评估，才有资格谈优化
我之前写过agent开发学习路线相关的内容，一直强调一个观点：没有评估体系的agent开发就是盲人摸象。你改了一个prompt，体验了一下觉得"哦，好像聪明了一点"，但你说不清到底哪里变了、变好了多少、有没有让别的地方变坏。这种开发方式放到个人项目里没问题，一旦涉及到工程化、团队协作，那就是灾难。
一个可量化的评估体系能帮你回答几个核心问题：当前Agent的真实成功率是多少，失败集中在哪些任务类型上，Skill升级后是变好了还是变坏了，某次优化动摇了哪些原本稳定的能力。有了这些数据支撑，每次迭代都是一次有方向的调整，而不是凭感觉试。
2. 评估体系整体架构怎么设计
2.1 评估流程的三个核心环节
我做的这套评估系统，在流程上拆成了三个环节：用例准备、任务执行、结果判定。
用例准备阶段的目标是构建一个覆盖不同难度、不同类型的测试任务集。任务执行阶段负责把这些用例喂给被测Agent或者Skill，记录全程的决策轨迹、工具调用、token消耗和运行时间。结果判定阶段则是根据预设的评分规则，把执行结果转化成可供比较的分数。
这三个环节必须完全解耦。用例集不能和执行器绑死，否则换一个被测对象就要重写用例；执行器也不能和评分逻辑耦合，否则你没法切换不同的评估维度。我见过有些评估脚本把用例、执行、评分全糊在一个大文件里，看起来简单，后面想扩展维度就痛苦得想删库重来。
2.2 执行层分两边：Agent级和Skill级
评估的执行层我分成了两个入口。评估Agent时，整个被测对象在沙箱环境里以"接收任务--自主规划--调用工具--完成任务"的完整链路运行，我会记录它在整个过程中做了哪些决策、每一步调用了什么工具、工具返回什么结果、遇到错误后如何反应。
评估Skill时，执行方式就简单很多。我直接把精心构造的输入喂给Skill，然后收集输出。重点观察它能不能正确解析输入结构、能不能处理输入中的边界情况、输出结果的质量是否稳定。
这两个入口共用同一个沙箱环境。沙箱里需要提前装好被测Skill运行必需的依赖，比如node环境、python库、浏览器工具等。对于涉及外部的API调用，我一般会用mock服务替代，避免评估过程中因为外部服务不稳定导致结果失真。
2.3 观测层要记录什么数据
观测层是整个评估系统的数据基础，记录什么直接决定你能分析什么。我的做法是分五类采集：
- 决策轨迹：Agent每一步的思考摘要、选用的工具、输入输出的大小。
- 操作记录：工具的调用顺序，每次调用的时间戳和返回状态。
- 错误信息：所有报错、异常退出、超时事件，带完整堆栈。
- 资源消耗：token消耗总数、分模型统计、整体耗时。
- 结果产物：Agent或Skill的最终返回结果，保存成结构化文件供后续分析。
这五类数据采集齐了，后面做问题定位时就顺畅很多。比如你想知道"为什么某类任务成功率低"，直接翻决策轨迹就能看到Agent在哪一步走了岔路。
3. 评估维度拆解：看一个Agent好不好用，到底看什么
3.1 功能质量维度：任务成功率、工具调用准确率、边界处理能力
功能质量是评估的核心面。任务成功率这事，看上去简单，实际上有个指标设计的问题。我早期直接算"跑通就算成功"，后来发现很多任务是"跑通了但结果完全不对"，比如Agent给出了一段代码，能编译能运行，但根本没有实现用户要的功能。所以后来我改用加权成功率，把任务结果分成完全正确、部分正确、完全错误三档，权重分别按1.0、0.5、0计算。
工具调用准确率是针对Agent的专项指标。因为现在的Agent基本都靠工具吃饭，能不能在正确的时机选择正确的工具，比模型本身的对话能力强弱更重要。我会记录Agent调用工具的总次数、其中选择正确并成功执行的次数、误差比例，再单独统计"该调用工具但没调"和"不该调用却调了"两类错误。
边界处理能力针对Skill评估特别重要。我给Skill准备输入时，会刻意混入缺字段、多字段、字段类型不对、极长文本、空值这五类边界情况，看它能不能给出合理的兜底行为。一个能把正常情况下做到95分、边界情况直接崩溃的Skill，我会给它打很低的综合分。
3.2 资源效率维度：token消耗、延迟、成本
做Agent开发的朋友聚在一起，少不了吐槽的一个话题就是token烧钱太快。所以我专门把资源效率也拉成一个维度，否则一个任务成功率虽然高，但每跑一次消耗10万token，这笔账怎么算都不划算。
资源效率我主要看三个数据：单次任务平均token消耗、单次任务平均耗时、以及按模型单价折算出的单次任务成本。这三个指标在Agent评估和Skill评估里都要采集，但解读方式不太一样。Skill的token消耗理应是稳定的，如果同一个Skill在不同上下文中token波动特别大，说明它对输入的解析逻辑不够稳定。Agent的token消耗则需要结合任务复杂度来看，简单任务用得多就是效率问题，复杂任务用得多倒还算合理。
3.3 稳定性与扩展性维度：重复运行、长任务、对比基准
稳定性是Agent评估最容易被忽略的维度。LLM的随机性导致同一个任务跑十遍，八遍走同一条路径，两遍走了别的路，甚至有时候跑十遍没有一遍是完全一致的。我不反对这种多样性，但如果一个Agent的成功与否严重依赖随机性，那它就不是一个可靠的工程方案。
我在评估里引入了重复运行机制。每个测试用例至少重复运行3次，关键用例重复5次，统计成功率的方差。方差太大的用例会单独拉出来分析，看是模型采样温度的问题，还是Agent规划逻辑里存在概率性分支。
长任务能力也要单独测。我会构造一些需要多轮迭代、逐步累积信息的复杂任务，比如"读取三个文件中的内容并交叉对比生成一份完整报表"。这种任务最能暴露上下文管理的问题。很多Agent短任务表现良好，一进入长对话就掉链子，要么忘了前面的关键信息，要么被中间产物干扰了判断。
最后是基准对比。我会在评估集里固定一批标准用例，每次Agent版本升级或者换了新Skill都要跑一遍，叫回归基准。这个基准集不需要很大，30个左右能覆盖主要能力点就行，关键是固定不变。我见过有人每次评估都顺手加新用例，导致新旧数据没法横向对比，这是评估的大忌。
4. 评估用例库的构建思路
4.1 用例来源：从哪找测试任务
用例库是一个评估系统的灵魂。我在构建用例库时使用了三个来源，按比例分配大概是：历史真实任务占50%，公开基准集占20%，人工构造占30%。
历史真实任务是最有价值的，直接从日常使用Agent/Skills时的日志里筛选有代表性的场景，比如"用前端开发skills生成一个响应式导航栏""用LaTeX排版skills输出一份学术论文模板"。这类用例的优点是真实度最高，能直接反映生产环境的问题。
公开基准集适合用来横向对比，比如HumanEval这类编程任务、GAIA这类通用agent任务。选择的标准是任务类型和你的使用场景要接近，否则参考价值有限。人工构造的用例则用来补齐前两者覆盖不到的角落，特别是那些边界情况和组合场景。
4.2 用例结构设计：怎么描述一个评估任务
我的每一个评估用例在结构上包含三块：任务描述、初始输入、期望结果。
任务描述是给被测Agent或Skill的目标说明，措辞要接近真实用户的需求表达方式。初始输入是任务执行前需要注入的数据或文件。期望结果则是用来判分的关键。对于编程类任务，期望结果会包括一组测试用例；对于生成类任务，期望结果是一组关键词和格式要求；对于分析类任务，期望结果则是一系列必须包含的要素点。
Skill相关用例的结构会严格一些，因为Skill的输入输出边界相对清晰。我会给每个Skill评估用例预先定义好输入schema和输出schema，然后生成一组正常输入和变异输入。正常输入用来测核心能力，变异输入用来测鲁棒性。
4.3 用例数据管理：版本化和分类标签
用例库不是建一次就完事了，需要像代码一样做版本管理和分类管理。我的做法是把每个用例写成JSON文件，里面带上id、标签、意图、难度等级、创建时间这些字段。标签按能力和场景两个维度打，能力维度比如代码生成、代码修复、文本总结、数据提取，场景维度比如前端场景、文档场景、数据分析场景。
分类标签的价值在做问题归集时特别明显。比如你发现这周Agent整体成功率下降了5个百分点，按照场景标签一筛，发现是前端相关用例掉得最厉害，再进一步看能力标签，发现是"根据截图生成代码"这一类问题，那基本就能锁定是视觉编码相关的Skill出了问题。如果用例不带标签，这种归因分析根本没法做。
5. 实际跑通：评估流程的完整实现
5.1 一个具体用例从"准备"到"评分"的完整流程
我用"图片生成skills安装包可用性评估"这个用例来演示整个流程。
首先在用例库里定义任务描述："调用图片生成skills，根据输入文本'一只戴着宇航员头盔的橘猫，坐在月球表面上看地球升起'生成一张1024x1024的图片。"初始输入就是这句prompt。期望结果则是文件存在、图片尺寸正确、文件可打开且内容非空白。
执行器把这个任务提交给被测Skill，开始记录运行情况。Skill会解析输入、调用底层的图片生成模型、等待模型返回、保存图片。如果模型返回超时，执行器会标记一次超时事件，然后按照预设策略最多重试一次。
评分阶段根据期望结果逐项判分。图片生成成功得0.6分，尺寸正确得0.2分，内容非空白得0.2分。如果图片生成失败，但错误信息明确（比如提示了API key无效或额度不足），那这算环境问题而不是Skill能力问题，会单独标注，不算入Skill的真实能力评分。
5.2 自动判分与人工复核怎么配合
自动判分能做很多事，但也不是万能的。对于程序类任务，判分相对简单，跑测试用例，过几个算几分。对于内容生成类任务，自动判分就比较难了。我的处理方式是分两层：机器先做硬性检查，格式、长度、结构、关键词覆盖；通过硬性检查的用例，再按比例抽20%进行人工复核评分。
人工复核不是推翻机器的判断，而是给机器判不了的内容打分，比如代码的可读性、文档的逻辑性、分析结论是否真正切中问题要害。这种主观质量的评估，暂时还是人力更靠谱。
最后的评分聚合，我会把每个用例的分项得分加权求和，再按能力和场景维度做汇总。输出格式是一个看板，包含总分、分维度得分、成功率趋势对比图、失败用例列表和错误类型分布。
5.3 评估报告的解读要点
评估报告做出来不是用来看个热闹的。我读报告时有几个固定动作：先看总分环比变化，确认这次迭代是整体变好还是变差；再看分维度得分，找出波动的具体位置；然后看失败用例列表，逐个点开错误信息做归因；最后把错误类型分布和用例标签做交叉分析，形成"哪类场景下的哪种能力最容易出问题"的结论。
如果我测试的是一个新引入的super power skills，比如web scraping类技能，我还会额外关注它和原有Agent的兼容性。有些Skill单独测试的时候一切正常，扔进Agent的上下文环境里反而破坏了Agent本身的工具选择逻辑，这种负优化效应，只能在回归基准集上通过对比测试才能发现。
6. 常见问题与排查技巧实录
6.1 环境不统一导致评估结果失真
我最初踩过的坑就是评估环境和实际使用环境不一致。有一次测试一个LaTeX排版Skills，在评估沙箱里跑成功率90%，拿到真实工作流里就是各种报错。排查到最后发现，沙箱里装的是最新版LaTeX内核，而真实环境因为系统依赖锁定的原因，还停留在旧版本。两边编译行为不同，Skills的表现自然不同。
现在我的做法是在沙箱里使用和线上环境完全一致的依赖锁定文件，包括系统级依赖、语言环境版本、Skills本身的版本号，全部通过配置来固定。每次评估开始前，会先跑一遍环境自检脚本，逐一核对关键依赖版本，不匹配直接中止评估，绝不在错误的环境上浪费时间。
6.2 网络波动污染了测试数据
评估过程中如果涉及API调用，网络波动就会变成一个很大的干扰源。有一次图片生成Skill评估，因为对应API服务商临时限流，成功率直接掉了三成。如果只看最终分数，很容易得出"这个Skill有严重缺陷"的错误结论。
这个问题现在用两层机制解决。一是接入API的响应状态码记录，如果某个外部服务大量出现429或5xx，就标记为"外部服务异常"而不是单纯判任务失败。二是在评估周期上做多次采样，这是一个典型的"单次快照不可信"的场景，同一批用例分三个时间段执行，取统计结果而不是单次结果。算下来平均成功率，比单次跑出来的数字可靠得多。
6.3 LLM随机性带来分数抖动
LLM的随机性是最考验评估体系设计的一个点。同一个Agent，同样的用例，温度参数设置不同，结果差别能大到无法接受。如果评估时不对随机性做约束，那些分数抖动就会被误判成"能力波动"。
我现在对随机性的策略是：工程评估场景下，把温度降到0或接近0，保证可复现性优先；创意评估场景下，保持较高温度，但增加重复运行次数，用统计分布替代单次点值。另外，每一个用例都会在结果详情里记录当时的模型参数配置，这样后面看到分数异常波动时，能快速判断是不是模型参数调整导致的。
6.4 Skill之间的上下文污染
多个Skills在同一个Agent里执行任务的时候，上下文污染是个很隐蔽的问题。每个Skill的调用都会往对话历史里注入大量中间内容，有些Skills的prompt模板里带了强指令性话语，会干扰Agent后续的工具选择。
我处理这类问题，第一道防线是在Agent层做上下文隔离，给不同技能模块划分独立的记忆区间。第二道防线是在评估中设计了"组合任务用例"，让Agent在同一个会话中连续完成两个不同能力的任务，实测看看第二个任务会不会被第一个任务的残留信息干扰。如果你发现单个Skill都表现良好、组合使用就掉链子，那八成就是上下文污染的问题。
6.5 查不出问题时的排查策略
如果某个Agent评估失败了，但错误信息不明确、日志也看不出原因，我会用二分定位法来找问题。先把Agent的规划能力关掉，只保留单个Skill，喂入直接用编排好的中间输入，看Skip逻辑本身是否正常。如果Skill正常，再把问题聚焦到工具调用层，逐个排查工具描述是否准确、Schema是否和实际实现一致。
还有一个反向位置的方法，比较实用：把失败用例根据"执行到第几步出现异常"做聚类。比如发现大量失败用例都是在第三步、调用数据库查询工具的时候挂掉的，那就去重点检查这个工具的参数schema和错误返回。这种聚类分析在评估集的配合下效率特别高，比一个一个看日志快得多。
7. 我这套评估体系实测下来的一些心得
7.1 一个"看起来很好"的Frontend Skills，实测却翻车了
我在本地做了一个前端开发Skills的专项评估，效果非常有代表性。这个Skills从GitHub的demo看，效果很好，生成出来的按钮、卡片、布局效果都像模像样。但我在评估用例里加入了"输入中偶尔混入多余的描述语句"这种情况后，完整通过率只剩下42%。
进一步分析决策轨迹发现，这个Skills的分词逻辑在有无关信息干扰时，会把一些正常的前端属性误删掉，或者重复生成某些样式块。这种问题不通过专项评估，只靠看几个正常demo，根本不可能暴露。测试完反馈给作者后，对方也很意外，因为在ta自己准备的测试集里，用例都是干净规范的单指令。这个案例让我更坚定了评估用例不能只准备"好球"。
7.2 评估体系本身也要持续迭代
很多人在搭完评估系统之后就把它当成了一个固定基础。我的建议是，评估系统本身的迭代频率不应该低于被评估的Agent。原因很简单：Agent的能力在变化，Skills在增多，评估用例如果一成不变，它测量的东西会和实际需求逐渐脱节。
我的迭代节奏是每两周做一次用例库检查。看看历史会话日志里有没有出现新类型的高频任务，把那些已经变得太简单、区分度太低的用例降级，补充一些当前痛点对应的新用例。评估维度也会根据阶段性的关注点做加减，比如早期我很关注token消耗，后来发现某个新框架在成本控制上做得很好，我就把成本维度的权重调低，把更长链条任务的能力权重调高。
7.3 评估分数不是终点，定位问题和推动改进才是
最后想说一个心态上的体会。做评估最容易陷入的误区，是把分数当成一个评判工具，"这个Agent得了75分，还行"然后就没有下文了。我在实际使用中的感受是，评估的价值不在于给Agent一个排名或者定个好坏，而在于它能逼迫你面对那些"你原本以为没问题的地方"，并且帮你找到优化问题的切口。
每次跑完评估，最重要的产出是一份问题清单，上面明确写着：当前最薄弱的三个环节是什么，薄弱的原因是什么，对应的修复建议是什么。下一轮迭代就是围绕这份清单去推动改变，然后重新评估，看问题有没有真正解决，有没有引入新的问题。评估--定位--改进--再评估，形成这个循环之后，Agent和Skills的开发会从"靠感觉"彻底转成"靠数据"，这种转变带来的效率提升是很明显的。
所以我的建议是，无论你是在做Agent项目、开发Skills，还是准备从零开始入门Agent方向，都可以尽早给自己搭一套哪怕非常简单的能力评估体系。不需要一次性做得很完整，先把最核心的三五个用例固定下来，跑通一个最小可用的评估闭环，后面再慢慢补充维度和用例集。这套东西投入的时间，大概率会以"少踩坑、少返工"的方式三倍五倍地返还回来。
