darkrishabh/agent-skills-eval

agent‑skills‑eval – Agent Skills のためのテストランナー

これは何か

TypeScript/Node.js ライブラリ（CLI + SDK）で、Agent Skill が言語モデルベースのエージェントを実際に改善するかどうかを評価できます。
オープンな agentskills.io 仕様に従います。スキルは、SKILL.md と、テストケースを記述したオプションの evals/evals.json を含むフォルダです。

仕組み

スキルを実行 – ランナーは SKILL.md を ターゲット モデル（スキルに支援させたいモデル）に送信するプロンプトに注入します。
ベースラインを実行 – 同じプロンプトをスキルコンテキストなしで送信します。
判定 – 2番目のモデル（判定者）が、評価ファイルで定義されたアサーションに基づいて両方の出力を採点します。
レポート – 結果はワークスペースフォルダ（iteration‑N/…）に書き込まれ、静的 HTML レポートが生成されます。

主な機能

機能	重要性
スキルあり/なしの比較	スキルが提供する実際の向上（またはその欠如）を示します。
判定者による合格/不合格	別の LLM を使用して評価の `assertions`/`expected_output` を適用し、再現可能なスコアを提供します。
クイック実行と CI のための CLI	ワンライナー `npx agent-skills-eval …` がそのまま動作します。フラグは再現性のために YAML 設定に直接マッピングされます。
TypeScript SDK	評価器をパイプライン、ダッシュボード、またはカスタムツールに埋め込むことができます。
OpenAI 互換プロバイダー	OpenAI、Anthropic（互換レイヤー経由）、Together、Groq、ローカル Llama サーバー、または OpenAI チャット API を話す任意のサービスで動作します。
カスタムプロバイダー	小さな `Provider` インターフェースを実装して、ローカルサーバー（Ollama、vLLM など）や独自 API に接続します。
ツール呼び出しアサーション	生のテキストだけでなく、モデルが正しい関数呼び出しを行ったことをアサートできます。
ポータブルアーティファクト	すべての出力、タイミング、トークン使用量、採点データは JSON/JSONL で保存され、差分比較やダウンストリーム分析が容易です。
静的 HTML レポート	合格率、アサーションごとの推論、プロンプト/応答ペア、リソース使用量を視覚化する自己完結型サイト（`index.html`）。
完全な agentskills.io 仕様準拠	`SKILL.md` のフロントマター、評価スキーマ、アーティファクトレイアウトを自動的に検証します。

典型的なワークフロー

# 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 を含む1つ以上のテストケース

ランナーは SKILL.md を検証し（--strict が設定されている場合）、各評価を実行します。

拡張性

独自の Provider を実装します（name、model、および {output, latencyMs, inputTokens, outputTokens, costUsd} を返す非同期 complete(prompt) のみ）任意のバックエンドを接続できます。
アーティファクト契約（docs/artifact-contract.md）により、ダウンストリームツールはライブラリ全体を引き込むことなく JSON 結果を消費できます。

ドキュメントとコミュニティ

完全なドキュメント：https://darkrishabh.github.io/agent-skills-eval/
ソースコード、問題トラッカー、貢献ガイドラインは GitHub にあります。
プロジェクトは MIT ライセンスであり、PR による拡張を奨励しています。

agent‑skills‑eval は、Agent Skills エコシステムに欠けていた部分を埋めます。単純な SKILL.md を測定可能なパフォーマンス向上に変える、再現可能なサイドバイサイド評価ハーネスです。

darkrishabh/agent-skills-eval

agent‑skills‑eval – Agent Skills のためのテストランナー

関連