SkillEvaluator:分层评估 AI Agent Skill 的质量与效果
给 Agent Skill 开发者做质量、安全和实测评估,区别是能比较有无 Skill 的 Agent 结果。
GitHub NVIDIA/SkillEvaluator 更新 2026-11-16 分支 main 星标 1.7K 分叉 229
Python AI Agent Skill 评估 SkillSpector Docker

🧭 决策指南

适合,如果你

  • 你维护符合 Agent Skills specification 的技能,并需要 Tier 1 静态质量检查。
    README 的“Three-tier overview”称 Tier 1 检查安全性、格式和 harness 兼容性。
  • 你要在 GitHub Pull Request 中自动检查变更后的 Skill。
    README 的“Get started”提供原生命令 `skillevaluator ci init`,并说明它会打开 setup PR。
  • 你需要比较有无 Skill 时 Agent 的任务结果,并能提供 Provider、Agent 和 Docker 沙箱。
    README 开头说明项目比较有无 Skill 的运行结果;“Three-tier overview”列出 Tier 3 的额外要求。

不适合,如果你

  • 你需要有 SLA 或 NVIDIA 企业支持的生产级评估服务。
    README 的“Support”明确写明支持级别为 Experimental,没有 SLA 或 NVIDIA enterprise support entitlement。
  • 你的环境不能运行 Docker,且目标是 Tier 3 Live Evaluation。
    README 的“Three-tier overview”写明 Tier 3 默认使用运行中的 Docker sandbox。
  • 你只需要基础安全扫描,不需要 Agent Skill 的 Tier 1–3 流水线。
    README 将 SkillSpector 描述为专用 skill security scanning 工具,说明它是 SkillEvaluator 的 Tier 1 组件。

前置条件

  • 独立安装使用 `pip install skillevaluator`;源码路径使用 Git、uv,并由 uv 配置 Python 3.13。
  • Tier 1 的完整静态覆盖需要外部 scanners;Tier 2 需要 embeddings 和 chat;Tier 3 需要 Provider、受支持 Agent 与运行中的 Docker sandbox。
  • 使用 NVIDIA Build 的 `rubric-eval` 需要 NVIDIA Developer Program 资格与 `NVIDIA_API_KEY`。
  • Tier 1 会获取固定版本的 SkillSpector 和 Gitleaks;Semgrep 为可选扫描器。

第一步命令(README 原文)

pip install skillevaluator

要注意

  • `--no-llm` 不会移除扫描器要求,扫描器无法运行时会得到 INCOMPLETE。
    README“Three-tier overview”
  • `doctor` 只检查环境就绪,不代表推理成功。
    README“Run the combined pipeline”
  • Tier 3 自动驾驶只会复用来源或创建一个覆盖有限的案例。
    README“Three-tier overview”
  • 自动生成模板不包含未撰写的负例,需关注 `evals/EVAL.md` 与 `--prompt` 输入。
    README“Run the combined pipeline”

替代方案

  • SkillSpector:只需要专用 Skill 安全扫描,而不需要 SkillEvaluator 的 Tier 2 去重或 Tier 3 Agent 评估时。
    README“Three-tier overview”
  • Harbor:需要直接使用开源 Agent 评估框架和沙箱运行能力,而不是 SkillEvaluator 的整合 CLI 时。
    README“Three-tier overview”

材料未说明

  • README 未说明 Tier 3 具体支持哪些 Agent 运行时及其版本。
  • README 未给出 NVIDIA Build、模型调用或托管沙箱的具体价格与限额。
  • README 未提供不同 Skill 规模下的运行时、资源消耗或并发能力数据。
  • README 未说明 Tier 2 使用的具体 embedding 模型和 chat 模型。

💡 深度解析

6
适合 我只有 Git 和 uv,没有 API key、GPU 或 Docker,当前只想获得一个确定性的 Skill 质量分数;SkillEvaluator 能否直接使用?
适合读者: 没有 GPU、希望先验证 Skill 文档质量的个人开发者,使用 Python 3.13、uv 和 Git

适合,README 明确支持无 LLM、无 API key、无 GPU 和无 Docker 的 Tier 1 质量检查,但这不等于完成安全或 Agent 效果评估。

  • Quickstart 要求 Git 和 uv,uv 会配置 Python 3.13 及依赖。
  • quality-check 可以输出确定性的质量分数和 findings;示例得到 86.2/100、退出码 0,并保存 JSON 报告。
  • 无 LLM 模式仍可能需要 SkillSpector 和 Gitleaks;扫描器无法运行会标记为 INCOMPLETE,所以“无 API key”不代表“无外部工具要求”。
  • README 明确指出无 LLM 结果只覆盖静态质量,安全需要扫描器,Agent 影响需要实时评估。
  • Quickstart:`Run without an LLM`;“No API key, scanner, GPU or Docker is needed”
  • Quickstart:`uv run --python 3.13 skillevaluator quality-check ...`
  • Quickstart:示例分数“86.2/100 (B)”并保存 `skillevaluator-quality.json`
  • Three-tier overview:`--no-llm` 不会移除 scanner requirements
uv run --python 3.13 skillevaluator quality-check \
  src/skillevaluator/tier3/reference_skills/text-analyzer \
  -r cli -r json -o reports/first-quality
材料未说明:README 未说明无 GPU 环境下扫描器的具体下载大小和运行时间。;未说明自定义 Skill 在没有扫描器时是否可以仅以静态规则得到完整可比的分数。
适合 我负责 Skill 安全门禁,要求至少运行 SkillSpector 和 Gitleaks,并希望在没有 LLM 的情况下先完成静态检查;Tier 1 是否能满足这个约束?
适合读者: 负责 Skill 安全门禁的测试与安全工程师,需要使用 SkillSpector、Gitleaks,并考虑可选的 Semgrep

适合,但前提是把 SkillSpector 和 Gitleaks 作为可运行的外部扫描器准备好;Tier 1 的无 LLM 模式不能绕过扫描器依赖。

  • README 将 Tier 1 定义为安全、格式和 harness compatibility 检查,适合放在静态质量门禁中。
  • 缺失时,SkillEvaluator 会获取固定且已验证版本的 SkillSpector 与 Gitleaks;Semgrep 是可选扫描器。
  • --no-llm 可以关闭模型检查,但 README 特别说明它不会移除 scanner requirements。
  • 扫描器无法运行会成为 INCOMPLETE 并导致非零退出,因此安全门禁应区分“扫描通过”和“扫描未完成”,不能只看质量分数。
  • Three-tier overview:Tier 1 检查 safety、well-formed 和 harness-compatible
  • Three-tier overview:Tier 1 fetches pinned, verified SkillSpector and Gitleaks releases;Semgrep optional
  • Three-tier overview:`--no-llm` does not remove scanner requirements
  • Three-tier overview:无法运行的 scanner 为 `INCOMPLETE` 并退出非零
uv run skillevaluator tier1 ./my-skill --no-llm
材料未说明:README 未列出 SkillSpector、Gitleaks 和 Semgrep 的具体版本兼容矩阵。;未说明扫描器是否支持企业代理、离线缓存或自定义规则。;未说明扫描结果如何区分误报、严重性和可接受的风险等级。
适合 我维护一个使用 GitHub Pull Request 的 Skill 仓库,团队希望把 Tier 1 质量检查加入 CI,并让不通过的 Skill 阻止合并;SkillEvaluator 是否适合?
适合读者: 维护 GitHub Pull Request 流程、需要在每次变更时检查 Agent Skill 的 DevOps 工程师

适合,因为 README 直接提供了 GitHub CI 初始化入口,并且 Tier 1 默认是 validate 的门禁。

  • 执行 skillevaluator ci init 会打开一个 setup PR,适合把检查接入现有 Pull Request 流程。
  • Tier 1 可以检查 Skill 是否安全、格式正确并兼容 harness;运行 validate --tiers 1 不需要 API key。
  • 报告支持 CLI 和 JSON,便于在 CI 中保存结果;不过扫描器缺失时会产生 INCOMPLETE 并以非零状态退出。
  • Tier 2 默认也可能阻断重复问题,Tier 3 只有显式启用 --block-on-agent-eval 才阻断,因此门禁范围可以分层控制。
  • Get started:`skillevaluator ci init`;“Check changed skills on every pull request”
  • Three-tier overview:Tier 1 “Is the skill safe, well-formed and harness-compatible?”
  • Run the combined pipeline:“Tier 1 gates validate”;“Tier 3 gates only with --block-on-agent-eval”
  • Three-tier overview:扫描器无法运行时为 `INCOMPLETE` 并退出非零
skillevaluator ci init
材料未说明:README 未说明 setup PR 生成后所需的具体 GitHub 权限和组织级分支保护配置。;未说明 CI 运行时间、扫描器下载失败时的重试策略。
适合 我需要证明一个 Skill 是否真的改善 Claude Code 或 Codex 的任务结果,并且可以运行 Docker 沙箱和受支持的 Agent;Tier 3 是否值得接入发布评估?
适合读者: 负责 Claude Code 或 Codex Skill 发布质量的测试工程师,拥有 Docker 沙箱和受支持的 Agent

适合,因为 Tier 3 专门比较启用和禁用 Skill 时的 Agent 任务结果,比静态文档评分更接近发布效果;但它依赖完整运行环境且具有成本和非确定性。

  • README 将 Tier 3 定义为“Does the skill help the agent?”,由 Harbor 驱动沙箱化 Agent 运行。
  • 默认沙箱是 Docker,额外要求 provider access、受支持的 Agent 和正在运行的 sandbox。
  • validate 默认不会用 Tier 3 阻断发布,只有配置 --block-on-agent-eval 才会把 Agent 评估纳入门禁。
  • 模型和 managed sandbox 可能产生费用;autopilot 还可能只复用来源或创建一个 skill-grounded case,覆盖范围有限。
  • Three-tier overview:Tier 3 “Does the skill help the agent?”;Harbor powers sandboxed agent runs
  • Three-tier overview:需要 provider、supported agent 和 running sandbox,Docker by default
  • Run the combined pipeline:Tier 3 仅在 `--block-on-agent-eval` 时阻断
  • Run the combined pipeline:model 和 managed-sandbox usage may incur charges;autopilot coverage limited
uv run --python 3.13 --extra all skillevaluator doctor --env-mode docker
材料未说明:README 未列出 Claude Code、Codex 及其他 Agent 的完整兼容版本矩阵。;未说明一次 Tier 3 运行的平均耗时、模型调用次数和 Docker 资源需求。;未给出有 Skill 与无 Skill 对照实验的统计显著性或重复运行机制。
视情况 我维护一个组织级 Skill catalog,Skill 数量会持续增加,想用 embeddings 和 chat 模型发现跨 Skill 的重复指导;Tier 2 是否适合,应该注意什么?
适合读者: 维护组织级 Skill catalog、需要识别重复指导的插件平台工程师

视情况,Tier 2 适合发现语义重叠,但不能单独证明两个 Skill 功能冲突或业务上不可共存。

  • README 将 Tier 2 定义为“Does guidance repeat or overlap?”,并要求 embeddings 和 chat 模型。
  • 使用 --catalog ./skill-catalog.json 才能进行跨 Skill 比较;没有 catalog 时只能做较局部的重叠分析。
  • Tier 2 的结果会报告跨 Skill 比较是否执行,语义相似度本身仍需要组织规则解释。
  • 在 combined pipeline 中,Tier 2 默认可以阻断重复问题,但也可以用 --no-block-on-dedup 关闭阻断,因此它更适合作为目录治理信号,而非唯一发布结论。
  • Three-tier overview:Tier 2 “Does guidance repeat or overlap?”
  • Three-tier overview:需要 “Embeddings and chat”;`--catalog ./skill-catalog.json` 用于 inter-skill comparison
  • Three-tier overview:Tier 2 会报告 inter-skill comparison 是否运行
  • Run the combined pipeline:Tier 2 gates unless `--no-block-on-dedup`
uv run --extra tier2 skillevaluator tier2 ./my-skill
材料未说明:README 未给出 catalog 的规模上限、嵌入模型选择和相似度阈值。;未说明 Tier 2 对不同语言、长文档或结构化参考文件的准确率。
视情况 我们有 substantive 的 evals/EVAL.md 和一个包含任务请求与结果的 prompt 文件,但缺少大量人工保留轨迹;能否用 SkillEvaluator 生成 Tier 3 数据集?
适合读者: 负责生成 Skill 评估数据集的小型 AI Agent 团队,已有 EVAL.md 和 prompt 文件但没有大量人工轨迹

视情况,README 支持从 EVAL.md 或 prompt 文件生成 Tier 3 数据集,但生成结果的覆盖度取决于输入是否真正定义了任务、结果和成功标准。

  • standalone generation 要求 substantive 的 evals/EVAL.md、包含 task requests and outcomes 的 --prompt 文件,或 matching retained traces。
  • --force 会替换 autopilot starter,--refine 用于改进它;--grounding skill 允许仅基于 Skill 创建 starter。
  • README 明确要求 review cases,并指出模板会省略未经作者编写的 negative cases,因此不能把自动生成的案例集视为完整负例覆盖。
  • 如果没有真实任务依据,数据集可以生成,但其作为发布门禁的代表性仍不确定。
  • Run the combined pipeline:standalone generation 的输入要求为 `evals/EVAL.md`、`--prompt` 或 retained traces
  • Run the combined pipeline:`--force` replaces autopilot starter;`--refine` refines it;`--grounding skill`
  • Run the combined pipeline:“Review cases; templates omit unauthored negatives”
  • 项目洞察:自动生成评估数据集的质量受真实任务和明确结果定义限制
uv run --python 3.13 --extra tier3 skillevaluator tier3 create-eval-dataset ./my-skill --full --prompt eval-guidance.md --force
材料未说明:README 未定义“substantive EVAL.md”的最低内容或案例数量。;未说明数据集生成模型、每个案例的成本和生成失败后的恢复方式。;未说明如何量化生成数据集相对于真实生产任务的覆盖率。

✨ 核心亮点

  • Tier 1–3 覆盖校验、去重与 Agent 实测
  • Tier 1 无 API Key 可得 86.2/100 示例分
  • 支持 GitHub CI、GitLab CI 与 Claude Code
  • Tier 3 默认依赖 Docker 沙箱与受支持 Agent

🔧 工程化

  • 用 validate 串联 Tier 1、2、3 评估流水线
  • 用 SkillSpector、Gitleaks 与 Semgrep 做安全检查
  • 用 rubric-eval 和 NVIDIA Build 生成模型反馈

⚠️ 风险

  • 项目支持级别为 Experimental,没有 SLA 或企业支持
  • Tier 3 需要 Provider、Agent 与 Docker 沙箱
  • 模型与托管沙箱使用可能产生费用
  • 缺失扫描器会使结果为 INCOMPLETE 并非零退出

👥 适合谁?

  • 维护 Agent Skills specification 技能目录的团队
  • 需要在 GitHub Pull Request 检查 Skill 的开发者
  • 使用 Claude Code、Codex 或兼容 Agent 的团队