evaluation-methodology

評価方法論

PluginEval は、スキルまたはプラグインを最大 3 つのレイヤーを組み合わせて 0 から 100 のスコアで評価します。静的レイヤーはリントです。高速で決定論的であり、構造のチェックに役立ちます。LLM ジャッジレイヤーとモンテカルロレイヤーは実験的であり、人間のラベルに対して検証されていないため、その数値は大まかなシグナルとして扱ってください。トレースベースの評価プログラムについては、リポジトリルートの evals/README.md を参照してください。

ジャッジのルーブリックのアンカーは references/rubrics.md にあります。各アンチパターンの修正方法と各次元のヒントは references/improving-scores.md にあります。

評価の深さ

深さ	レイヤー	信頼度ラベル
quick	静的	Estimated
standard (score のデフォルト)	静的およびジャッジ	Assessed
deep (certify で使用)	静的、ジャッジ、および 50 回実行のモンテカルロ	Certified
thorough	静的、ジャッジ、および 100 回実行のモンテカルロ	Certified+

このラベルは実行された深さを示すものであり、人間の判断に対するチェックではありません。プラグインディレクトリは、どの深さを指定しても静的レイヤーのみが適用されます。

静的レイヤー (リント)

静的レイヤーは SKILL.md を読み取り、モデル呼び出しは行いません。7 つのサブスコアを計算し、最初の 6 つが複合次元に反映されます:

• frontmatter_quality (triggering_accuracy に反映)
• orchestration_wiring (orchestration_fitness に反映)
• progressive_disclosure、structural_completeness、token_efficiency、ecosystem_coherence
• harness_portability

harness_portability はどの次元にもマッピングされないため、スキルの複合スコアは変わりません。ただし、静的レイヤー自体のスコアの 6% を占めます。プラグインのスコアはそのレイヤースコアから構築されるため、ポータビリティの指摘によってプラグインのスコアが少し下がる可能性があります。その指摘はアンチパターンとしてカウントされません。

静的レイヤーは 6 つのアンチパターンを検出します: OVER_CONSTRAINED、EMPTY_DESCRIPTION、MISSING_TRIGGER、BLOATED_SKILL、ORPHAN_REFERENCE、DEAD_CROSS_REF。各フラグはスコアを 5% 削減し、下限は 50% です:

penalty = max(0.5, 1.0 - 0.05 * anti_pattern_count)

レポートは各フラグの重大度を出力しますが、ペナルティはフラグをカウントし、重大度は無視します。

LLM ジャッジレイヤー (実験的)

ジャッジレイヤーは 4 回のモデル呼び出しを行い、0 から 1 の 4 つの全体的なスコアを返します:

• triggering_accuracy: Haiku が説明を読み、10 個のテストプロンプトを作成します。5 個はトリガーされるべきもので、5 個はそうでないものです。各プロンプトの結果を予測し、自身の F1 を報告します。これらの予測が実際のトリガーと照合されることはありません。
• orchestration_fitness と scope_calibration: Sonnet が 5 段階のルーブリックでスキルを評価します。
• output_quality: Sonnet が 3 つのタスクを想定し、期待される出力を評価します。

3 つの Sonnet 呼び出しは SKILL.md の最初の 3,000 文字のみを参照します。judges 設定を読み取るものがないため、実行されるジャッジは 1 つだけです。

モンテカルロレイヤー (実験的)

Haiku がスキルをトリガーすべき 15 個のプロンプトを作成し、レイヤーはそれらを繰り返して 50 回の実行 ( thorough では 100 回) に到達します。各実行は SKILL.md のテキストと 1 つのプロンプトをモデルに送信し、レイヤーは 4 つの指標を記録します:

• アクティベーション率は、空でない返信があった実行の割合であるため、モデルが回答したかどうかを示すものであり、スキルが発火すべきだったかどうかを示すものではありません。
• 出力品質は、返信の長さを 500 で割った値で、上限は 1.0 です。
• 失敗率は、エラーが発生した実行の割合です。
• トークン効率は 1 - median_tokens / 8000 です。

すべてのプロンプトはトリガーすべきものなので、レイヤーはスキルが無関係なリクエストに対して発火しないことを決してチェックしません。レイヤーの JSON には、自身の指標に対する Wilson、ブートストラップ、Clopper-Pearson の区間が含まれます。複合の ci_lower フィールドと ci_upper フィールドは常に null です。

総合スコア

まず、各ディメンションについて、エンジンは存在するレイヤースコアをブレンドし、それらのレイヤーに対してブレンドの重みを再正規化します。次に、重み付けされたディメンションスコアを合計し、スコアを持つディメンションに対してディメンションの重みを再正規化します。3 番目に、その合計に 100 とアンチパターンペナルティを掛けます。

ディメンション	重み	Static	Judge	Monte Carlo
triggering_accuracy	0.25	0.15	0.25	0.60
orchestration_fitness	0.20	0.10	0.70	none
output_quality	0.15	none	0.40	0.60
scope_calibration	0.12	none	0.55	none
progressive_disclosure	0.10	0.80	none	none
token_efficiency	0.06	0.40	none	0.50
robustness	0.05	none	none	0.80
structural_completeness	0.03	0.90	none	none
code_template_quality	0.02	none	none	none
ecosystem_coherence	0.02	0.85	none	none

セルが「none」と表示されるのは、そのレイヤーがそのディメンションのスコアを生成しない場合で、LAYER_BLENDS に重みが記載されていても同様です。どのレイヤーも code_template_quality を生成しないため、これは常に未測定です。プラグインディレクトリの場合、総合スコアはプラグインのスキルとエージェント全体にわたる静的レイヤーの平均スコアに 100 を掛け、プラグインのアンチパターン数に対するペナルティを掛けたものです。

バッジとグレード

バッジは総合スコアのみから決まります。プラチナには 90 以上、ゴールドには 80 以上、シルバーには 70 以上、ブロンズには 60 以上が必要です。Badge.from_scores は Elo レーティングを受け付けますが、それを計算するコマンドはありません。週次の CI レポートに含まれるものを含め、プラグインレベルのバッジは静的レイヤーのみから決まります。standard 深度以上のスキルレベルのバッジには、実験的レイヤーも含まれます。

測定された各ディメンションには、0 から 100 のスケールでレターグレードが付き、97 の A+ から 60 の D- まで、そして 60 未満は F です。

使用方法

plugin-eval score ./path/to/skill --depth quick     # static lint only
plugin-eval score ./path/to/skill                   # static and judge
plugin-eval certify ./path/to/skill                 # deep depth
plugin-eval compare ./skill-a ./skill-b             # quick depth by default
plugin-eval score ./path/to/skill --depth quick --output json --threshold 70

standard 深度以上では、score、certify、compare は、judge レイヤーと Monte Carlo レイヤーが実験的であるという注記を stderr に出力します。プラグインディレクトリの場合、代わりに静的レイヤーのみが実行されるという警告を CLI が出力します。--threshold を付けると、総合スコアがその値未満のときにコマンドはコード 1 で終了します。plugin-eval init はコーパスインデックスを書き込みますが、それを読み取る他のコマンドはありません。

例

以下に、JSON 出力の省略した例を示します。スクリプトはそこから composite.score を読み取ることができます:

{
  "layers": [{"layer": "static", "score": 0.75, "sub_scores": {}, "anti_patterns": []}],
  "composite": {"score": 76.9, "ci_lower": null, "ci_upper": null, "badge": "silver",
                "confidence_label": "Estimated", "dimensions": []},
  "elo": null
}

トラブルシューティング

• コンテンツを追加した後にスコアが下がった場合は、JSON の layers[0].anti_patterns を確認してください。
• quick 深度で triggering_accuracy が低い場合は、「Use this skill when」のようなトリガーフレーズを description に追加し、その後にカンマ区切りの複数のコンテキストを続けてください。
• Judge スコアは実行ごとに変わります。モデルが毎回新しいテストプロンプトとタスクを書き出すためです。再現したい比較には静的レイヤーを使用してください。
• stderr が、judge が一部のディメンションを測定できなかったと表示する場合は、uv sync --extra llm で LLM エクストラをインストールしてください。

関連

eval-judge エージェントは Claude Code 内で 4 つの judge ディメンションをスコアリングし、eval-orchestrator エージェントは CLI を実行して結果をマージします。