darkrishabh/agent-skills-eval

agent‑skills‑eval – 一个用于 Agent Skills 的测试运行器

它是什么

• 一个 TypeScript/Node.js 库（CLI + SDK），让您评估 Agent Skill 是否真正改善了基于语言模型的代理。
• 它遵循开放的 agentskills.io 规范：技能是一个包含 SKILL.md 和可选的 evals/evals.json（描述测试用例）的文件夹。

工作原理

1. 运行技能 – 运行器将 SKILL.md 注入发送给 目标 模型（您希望技能帮助的模型）的提示中。
2. 运行基线 – 相同的提示在没有技能上下文的情况下发送。
3. 评审 – 第二个模型（评审）根据评估文件中定义的断言对两个输出进行评分。
4. 报告 – 结果写入工作区文件夹（iteration‑N/…），并生成静态 HTML 报告。

主要功能

功能	重要性
有技能 / 无技能比较	显示技能提供的实际提升（或缺乏提升）。
评审评分通过/失败	使用独立的 LLM 应用评估的 assertions/expected_output，提供可重现的分数。
CLI 快速运行和 CI	一行命令 npx agent-skills-eval … 开箱即用；标志直接映射到 YAML 配置以确保可重现性。
TypeScript SDK	让您将评估器嵌入管道、仪表板或自定义工具中。
OpenAI 兼容提供者	适用于 OpenAI、Anthropic（通过兼容层）、Together、Groq、本地 Llama 服务器，或任何支持 OpenAI 聊天 API 的服务。
自定义提供者	实现小型 Provider 接口以连接到本地服务器（Ollama、vLLM 等）或专有 API。
工具调用断言	不仅是原始文本 – 您可以断言模型是否进行了正确的函数调用。
可移植工件	所有输出、时间、token 使用量和评分数据都以 JSON/JSONL 存储，方便差异比较和下游分析。
静态 HTML 报告	一个自包含的网站（index.html），可视化通过率、每个断言的推理、提示/响应对和资源使用情况。
完整的 agentskills.io 规范合规性	自动验证 SKILL.md front‑matter、评估架构和工件布局。

典型工作流程

# 1️⃣ 安装（或直接使用 npx）
npm i agent-skills-eval

# 2️⃣ 针对技能文件夹运行
npx agent-skills-eval ./skills \
  --target gpt-4o-mini \
  --judge  gpt-4o-mini \
  --baseline \
  --strict

• 命令创建 agent-skills-workspace/iteration-1/…，包含 JSON 结果和 report/index.html。
• 在浏览器中打开 HTML 文件，查看每个技能是否帮助了目标模型。

配置

• YAML 文件（agent-skills-eval.yaml）可以存储所有选项（根文件夹、工作区路径、模型名称、API 基础 URL、并发等）。
• CLI 标志始终覆盖 YAML 值，这对 CI 管道很方便。

SDK 示例

import { OpenAICompatibleProvider, evaluateSkills, consoleReporter } from "agent-skills-eval";

const provider = new OpenAICompatibleProvider({
  baseUrl: "https://api.openai.com/v1",
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-4o-mini",
  providerName: "openai",
});

await evaluateSkills({
  root: "./skills",
  workspace: "./agent-skills-workspace",
  baseline: true,
  target: { model: provider.model, provider },
  judge:  { model: provider.model, provider },
  onEvent: consoleReporter(),
});

• SDK 流式传输事件（进度、评分、错误），可以记录为 JSONL 以供进一步分析。

何时使用

• 技能开发者想要实证证据，证明他们的 SKILL.md 确实改善了模型性能。
• CI/CD 管道需要对技能库进行自动化回归测试。
• 产品团队评估多个技能并排，以决定要发布哪些。
• 研究人员在受控基线条件下比较不同的提示或工具调用策略。

安装与快速开始

npm install agent-skills-eval   # 或直接使用 npx
npx agent-skills-eval --help    # 显示所有标志

一个最小的技能文件夹看起来像：

my-skill/
├─ SKILL.md          # 描述 + 可选元数据
└─ evals/
   └─ evals.json    # 一个或多个测试用例，包含 prompt、expected_output、assertions

运行器将验证 SKILL.md（如果设置了 --strict），然后执行每个评估。

扩展性

• 实现您自己的 Provider（只需要 name、model 和异步 complete(prompt)，返回 {output, latencyMs, inputTokens, outputTokens, costUsd}）以插入任何后端。
• 工件契约（docs/artifact-contract.md）让下游工具可以消费 JSON 结果，而无需引入整个库。

文档与社区

• 完整文档：https://darkrishabh.github.io/agent-skills-eval/
• 源代码、问题跟踪器和贡献指南在 GitHub 上。
• 项目采用 MIT 许可，并鼓励通过 PR 进行扩展。

---

agent‑skills‑eval 填补了 Agent Skills 生态系统中缺失的一环：一个可重现、并排的评估框架，将简单的 SKILL.md 转化为可衡量的性能提升。