Skillgrade

面向 AI 代理技能的自动化评估测试框架，支持多代理交叉验证与 CI 集成。

项目概述#

Skillgrade 是一个专为 AI 代理技能（Agent Skills）设计的自动化评估框架，核心理念是"为技能写单元测试"。它以 SKILL.md 作为技能描述契约，通过 eval.yaml 定义任务指令、工作空间映射和评分策略，在 Docker 容器或本地沙箱中实际启动代理执行任务，再由确定性脚本或 LLM 按权重组合评分。

核心能力#

评估核心#

Agent Skill 端到端测试：从代理启动、技能发现、任务执行到结果评分的完整闭环。
双评分模式：
- Deterministic Grader：执行命令解析 stdout JSON，返回 0.0–1.0 分数。
- LLM Rubric Grader：基于会话记录按定性标准评分（使用 Gemini 或 Anthropic 模型）。
- 两者可组合加权：Final reward = Σ(grader_score × weight) / Σ weight。

多代理支持#

Gemini（Google Gemini CLI）
Claude（Anthropic Claude Code）
Codex（OpenAI Codex CLI）
ACP（Agent Client Protocol 兼容代理，JSON-RPC 2.0 over stdio）

智能辅助#

skillgrade init 可借助 LLM 自动生成 eval.yaml 中的任务与评分器；无 API Key 时生成带注释的模板。

运行与 CI#

预设模式：--smoke（5 次）、--reliable（15 次）、--regression（30 次高置信度回归检测）。
--ci 模式在通过率低于阈值（默认 0.8）时以非零退出码退出；--provider=local 支持 CI 环境免 Docker 运行。
--parallel=N 指定并发试验数。

安全与隔离#

每个 task 可指定 workspace 文件映射，在 Docker 容器或本地沙箱中隔离执行。
支持 .env 文件自动加载，Shell 值覆盖 .env，所有值在持久化日志中自动脱敏。

结果可视化#

CLI 报告：skillgrade preview
Web UI：skillgrade preview browser（默认 http://localhost:3847）

架构与实现#

目录结构#

src/          — 核心源码
bin/          — CLI 入口
examples/     — 示例（superlint、angular-modern TypeScript grader）
fixtures/     — 测试固定文件
graders/      — 评分器脚本
skills/       — 内置技能
templates/    — 模板
tests/        — 测试

执行模型#

读取 eval.yaml 配置。
对每个 task，准备 workspace 文件映射。
在 Docker 容器（默认）或本地沙箱中启动目标代理。
代理执行 instruction 描述的任务。
执行 graders 链：先 deterministic 评分器，再 LLM rubric 评分器。
按权重计算加权得分，汇总所有 trials 结果。
输出报告或触发 CI 退出码。

ACP 通信机制#

通过子进程启动 ACP 兼容代理，使用 JSON-RPC 2.0 over stdio 通信，代理自行处理认证，无需直接管理 API Key。

TypeScript 项目，使用 vitest 作为测试框架。主要语言构成：TypeScript 86.5%、HTML 10.1%、JavaScript 3.4%。运行需 Node.js 20+ 和 Docker。

安装与使用#

npm i -g skillgrade

cd my-skill/
GEMINI_API_KEY=your-key skillgrade init
GEMINI_API_KEY=your-key skillgrade --smoke
skillgrade preview
skillgrade preview browser

eval.yaml 示例#

version: "1"
defaults:
  agent: gemini
  provider: docker
  trials: 5
  timeout: 300
  threshold: 0.8
  grader_model: gemini-3-flash-preview
tasks:
  - name: fix-linting-errors
    instruction: |
      Use the superlint tool to fix coding standard violations in app.js.
    workspace:
      - src: fixtures/broken-app.js
        dest: app.js
    graders:
      - type: deterministic
        run: bash graders/check.sh
        weight: 0.7
      - type: llm_rubric
        rubric: "Did the agent follow the check → fix → verify workflow?"
        weight: 0.3

关键 CLI 选项#

标志	说明
`--smoke` / `--reliable` / `--regression`	预设试验次数（5/15/30）
`--agent=gemini\|claude\|codex\|acp`	指定代理
`--provider=docker\|local`	执行环境
`--ci`	CI 模式，失败时退出码非零
`--threshold=0.8`	CI 通过率阈值
`--eval=NAME[,NAME]`	按名称运行特定评估
`--grader=TYPE`	仅运行指定类型评分器
`--parallel=N`	并发试验数
`--validate`	用参考方案验证评分器

适用场景#

技能质量保证：为自定义 AI 代理技能编写可重复、可量化的评估测试。
回归检测：技能更新后自动运行评估，检测功能退化。
多代理一致性验证：同一技能在 Gemini、Claude、Codex 等不同代理上交叉测试。
CI/CD 流水线集成：将技能评估纳入持续集成流程，确保发布质量达标。
技能开发辅助：skillgrade init 自动生成评估配置，降低编写门槛。

生态关联#

关联项目：skills-best-practices — 同一作者维护的技能编写最佳实践指南。
灵感来源：SkillsBench 及论文 "Demystifying Evals for AI Agents"。

待确认事项#

npm 包发布状态：README 提及 npm i -g skillgrade，但 GitHub Packages 显示 "No packages published"，可能发布在 npmjs.com 公共注册表。
版本号/Release：仓库无 Tags 和 Releases，仅 main 分支。
博客文章：链接指向 2026 年 3 月日期，未验证文章是否真实存在且可访问。
grader_model 默认值 gemini-3-flash-preview 可能为预览/实验性模型，需确认当前可用性。
ACP 协议具体版本与兼容代理列表未明确。
LLM Rubric Grader 是否支持 OpenAI 模型作为评分器未说明。