評価方法論

このドキュメントは、PluginEval がプラグインとスキルの品質をどのように測定するかについての権威的なリファレンスです。 3つの評価レイヤー、全10個のスコアリング次元、複合スコア計算式、バッジ閾値、アンチパターンフラグ、Eloランキング、 および実行可能な改善方法について説明します。

関連: 完全なルーブリック根拠

---

3つの評価レイヤー

PluginEval は3つの相補的なレイヤーを積み重ねています。各レイヤーは適用可能な次元ごとに0.0～1.0の間のスコアを生成し、 後続のレイヤーは次元別ブレンド重みに従って、以前のレイヤーを上書きまたはブレンドします。

レイヤー1 — 静的分析

速度: 2秒未満。LLM呼び出しなし。決定論的。

静的アナライザー (layers/static.py) は、解析されたSKILL.mdに対して直接6つのサブチェックを実行します:

サブチェック	測定対象
frontmatter_quality	名前の存在、説明の長さ、トリガーフレーズの品質
orchestration_wiring	出力/入力ドキュメント、コードブロック数、オーケストレーターアンチパターン
progressive_disclosure	行数とスイートスポット (200–600行) の比較、references/ と assets/ ボーナス
structural_completeness	見出し密度、コードブロック、例セクション、トラブルシューティングセクション
token_efficiency	MUST/NEVER/ALWAYS密度、重複行繰り返し率
ecosystem_coherence	他のスキル/エージェントへのクロスリファレンス、"related"/"see also"の記述

これら6つのサブチェックは、(STATIC_TO_DIMENSIONマッピングを通じて) 最終的な10個の次元のうち6つに直接フィードします。 残りの4つの次元 — output_quality、scope_calibration、robustness、およびtriggering_accuracyの一部 — は 静的な寄与を受けず、完全にレイヤー2および/またはレイヤー3に依存します。

アンチパターンペナルティはレイヤー1スコアに乗法的に適用されます:

penalty = max(0.5, 1.0 − 0.05 × anti_pattern_count)

検出される追加のアンチパターンごとに、スコアは5%削減され、50%でフロアされます。

レイヤー2 — LLMジャッジ

速度: 30–90秒。1つ以上のLLM呼び出し (デフォルトではSonnet)。非決定論的。

eval-judgeエージェントはSKILL.mdと任意のreferences/ファイルを読み、 アンカーされたルーブリック (references/rubrics.mdを参照) を使用して4つの次元をスコアリングします:

1. トリガー精度 — 10個のメンタルテストプロンプトから導出されたF1スコア
2. オーケストレーション適合性 — ワーカー純度評価 (0–1ルーブリック)
3. 出力品質 — 3つの現実的なタスクをシミュレート、指示品質を評価
4. スコープキャリブレーション — スキルのカテゴリーに対する深さと広さを判定

ジャッジは構造化されたJSONオブジェクト (マークダウンフェンスなし) を返し、評価エンジンがこれを複合スコアにマージします。 judges > 1の場合、スコアは平均化され、Cohen のカッパが判定者間の合意指標として報告されます。

レイヤー3 — モンテカルロシミュレーション

速度: 5–20分。N=50のシミュレートされたAgent SDK呼び出し (デフォルト)。統計的。

モンテカルロはN個の実プロンプトをスキルを通じて実行し、以下を記録します:

• 活性化率 — スキルをトリガーしたプロンプトの割合
• 出力一貫性 — 品質スコア間の変動係数 (CV)
• 故障率 — Clopper-Pearson正確CI付きのエラー/クラッシュ割合
• トークン効率 — 中央値トークン数、IQR、外れ値数

レイヤー3の複合スコア計算式:

mc_score = 0.40 × activation_rate
         + 0.30 × (1 − min(1.0, CV))
         + 0.20 × (1 − failure_rate)
         + 0.10 × efficiency_norm

ここで efficiency_norm = max(0, 1 − median_tokens / 8000) です。

---

複合スコアリング計算式

最終スコアは、各次元に対する3つのレイヤー全体の重み付きブレンドで、その後合計されます:

composite = Σ(dimension_weight × blended_dimension_score) × 100 × anti_pattern_penalty

次元の重み

次元	重み	重要な理由
triggering_accuracy	0.25	スキルが発動しない、または誤った発動をする場合、価値がありません
orchestration_fitness	0.20	スキルはピュアなワーカーである必要があり、スーパーバイザロジックはエージェントに属します
output_quality	0.15	正確で完全な出力が主要な成果物です
scope_calibration	0.12	スタブでもなく、肥大化したモンスターでもない
progressive_disclosure	0.10	SKILL.mdは軽く、詳細はreferences/に存在します
token_efficiency	0.06	呼び出しごとの最小限のコンテキスト無駄
robustness	0.05	エッジケースをクラッシュなしで処理
structural_completeness	0.03	正しいセクションが正しい順序にある
code_template_quality	0.02	動作する、コピー&ペースト対応の例
ecosystem_coherence	0.02	クロスリファレンス、兄弟スキルとの重複なし

レイヤーブレンド重み

各次元は異なるレイヤーから異なる比率で引き出されます。3つのレイヤーが全てアクティブな場合 (--depth deep または certify):

次元	静的	ジャッジ	モンテカルロ
triggering_accuracy	0.15	0.25	0.60
orchestration_fitness	0.10	0.70	0.20
output_quality	0.00	0.40	0.60
scope_calibration	0.30	0.55	0.15
progressive_disclosure	0.80	0.20	0.00
token_efficiency	0.40	0.10	0.50
robustness	0.00	0.20	0.80
structural_completeness	0.90	0.10	0.00
code_template_quality	0.30	0.70	0.00
ecosystem_coherence	0.85	0.15	0.00

--depth standard (静的+ジャッジのみ) の場合、ブレンドは正規化されてモンテカルロ列が削除されます。 --depth quick (静的のみ) の場合、すべての重みはレイヤー1に落ちます。

ブレンドスコア計算

与えられた深度に対して、次元dのブレンドスコアは:

blended[d] = Σ( layer_weight[d][layer] × layer_score[d][layer] )
             ─────────────────────────────────────────────────────
             Σ( layer_weight[d][layer] for available layers )

この正規化により、標準深度でモンテカルロをスキップしてもスコアが人為的に低下しません。

---

次元スコアの解釈

各次元スコアは[0.0, 1.0]内の浮動小数点数です。CLIはこれを成績文字に変換します:

成績	スコア範囲	意味
A	0.90 – 1.00	優秀 — 意味のある改善は不要
B	0.80 – 0.89	良好 — わずかなギャップのみ
C	0.70 – 0.79	適切 — 1つまたは2つの明確な改善領域
D	0.60 – 0.69	限界 — ターゲットとした作業が必要
F	< 0.60	不合格 — 重大な修復が必要

レポートを読むときは、最も高い重みを持つ最も低く評価された次元に最初に焦点を当てます。 triggering_accuracy (重み0.25) のDは、ecosystem_coherence (重み0.02) のDよりもはるかに多くのコストがかかります。

信頼区間はレイヤー2またはレイヤー3が実行されたときにレポートに表示されます。 狭いCI (± < 5ポイント) は安定したスコアを示します。広いCIは矛盾を示唆しており、 曖昧な説明やいくつかのプロンプトスタイルでは機能するが他のスタイルでは機能しない指示が原因であることが多いです。

---

品質バッジ

バッジは複合スコア閾値AND Elo閾値の両方が必要です (Eloが利用可能な場合)。 Badge.from_scores()ロジックは複合をまず確認し、その後(提供されていれば) Eloを確認します:

バッジ	複合	Elo	意味
Platinum ★★★★★	≥ 90	≥ 1600	リファレンス品質 — ゴールドコーパスに適している
Gold ★★★★	≥ 80	≥ 1500	本番環境対応
Silver ★★★	≥ 70	≥ 1400	機能的、改善の余地あり
Bronze ★★	≥ 60	≥ 1300	最小限の実行可能性 — ユーザーにはまだ推奨されません
—	< 60	任意	最小基準を満たさない

Elo閾値は、Eloが計算されていない場合 (すなわち、certifyなしで高速または標準深度の場合) にスキップされます。 その場合、スキルは複合スコアのみでバッジを獲得できます。

---

アンチパターンフラグ

静的アナライザーは5つのアンチパターンを検出します。各パターンはペナルティ計算式にフィードされる重大度乗数を負っています。

OVER_CONSTRAINED

トリガー: SKILL.md内にMUST、ALWAYS、またはNEVERが15回以上出現しています。

問題: 過度に規範的な指示は、モデルの柔軟性を低下させ、トークンオーバーヘッドを増加させ、 著者が原則的なガイダンスを提供するのではなく、すべての出力をマイクロマネジメントしようとしていることを示します。

修正方法: すべてのMUST/ALWAYS/NEVERを監査します。可能な限り、指示言語を説明的なフレーミングに置き換えます。 ハードな制約は、実質的なセキュリティまたは正確性要件のために予約しておきます。100行あたり10個未満のディレクティブを目指します。

EMPTY_DESCRIPTION

トリガー: フロントマターdescriptionフィールドは、ストリップ後20文字未満です。

問題: 意味のある説明がない場合、Claude Code プラグインシステムはスキルを呼び出すタイミングを判断できません。 スキルは自律的な呼び出しから見えなくなります。

修正方法: 以下を含む最低60–120文字の説明を書きます:

• "Use this skill when..." または "Use when..." トリガー句
• コンマまたは "or" で区切られた2つ以上の具体的なコンテキスト

MISSING_TRIGGER

トリガー: 説明に "use when"、"use this skill when"、"use proactively"、 または "trigger when" (大文字小文字を区別しません) が含まれていません。

問題: 長い説明でさえ、自律的な呼び出しのための明確なトリガー信号が含まれていない場合は無用です。 システムのルーティングモデルは明示的な手がかりが必要です。

修正方法: 説明の前に "Use this skill when..." を付け、その後に具体的なシナリオを続けます。 例: "Use this skill when measuring plugin quality, interpreting score reports, or explaining badge thresholds to a team."

BLOATED_SKILL

トリガー: SKILL.md が800行を超えており、スキルにreferences/ディレクトリがありません。

問題: モノリシックなSKILL.mdは、すべてのドキュメントを各呼び出しでコンテキストに強制し、 エッジケースでのみ必要なコンテンツにトークンを無駄にします。

修正方法: references/ディレクトリを作成し、サポート資料をそこに移動します:

• 詳細なルーブリック → references/rubrics.md
• 拡張された例 → references/examples.md
• 構成リファレンス → references/config.md

SKILL.md は [text](references/filename.md) でこれらのファイルにリンクして、 モデルが必要に応じてオンデマンドで取得できるようにします。

ORPHAN_REFERENCE

トリガー: SKILL.md にマークダウンリンク[text](references/filename)が含まれており、 filenameがreferences/ディレクトリに存在しません。

問題: デッドリンクは解決されることのないコンテキストにトークンを無駄にし、モデルを混乱させます。

修正方法: 欠落しているリファレンスファイルを作成するか、デッドリンクを削除します。

DEAD_CROSS_REF

トリガー: SKILL.md が相対パスで別のスキルまたはエージェントを参照し、 そのパスをskills/ディレクトリから解決できません。

問題: 壊れたエコシステムリンクはプラグインのコヒーレンススコアを損なわせ、 モデルが存在しないファイルへのナビゲーションを試みるかもしれません。

修正方法: 参照されたスキルが存在することを確認します。パスを更新するか、リファレンスを削除します。

---

Eloランキング

PluginEval は Elo/Bradley-Terry レーティングシステムを使用して、スキルをゴールドコーパスに対してランク付けします。

初期レーティング: 1500 (慣例によるコーパス中央値)。

K-factor: 32 (中程度のステークのレーティングの標準)。

期待スコア計算式(標準Elo):

E(A vs B) = 1 / (1 + 10^((B_rating − A_rating) / 400))

各マッチアップ後のレーティング更新:

new_rating = old_rating + 32 × (actual_score − expected_score)

ここでactual_scoreは勝利の場合は1.0、引き分けの場合は0.5、敗北の場合は0.0です。

信頼区間は500サンプルブートストラップ経由で計算され、95% CIとして報告されます。 コーパスパーセンタイルはゴールドコーパスに対するペアワイズ勝率を反映します。 ポジションバイアス確認: ペアは両方の順序で評価され、相違点はフラグが立てられます。

plugin-eval initコマンドはプラグインディレクトリからコーパスインデックスを構築します:

plugin-eval init ./plugins --corpus-dir ~/.plugineval/corpus

---

CLIリファレンス

スキルをスコアリング (高速静的分析のみ)

plugin-eval score ./path/to/skill --depth quick

2秒未満でレイヤー1の結果を返します。著作中の高速フィードバックに役立ちます。

LLMジャッジでスコアリング (デフォルト)

plugin-eval score ./path/to/skill

静的+LLMジャッジ(標準深度)を実行します。30–90秒かかります。

JSONとしての完全な出力でスコアリング

plugin-eval score ./path/to/skill --output json

composite.score、composite.dimensions、およびlayers[0].anti_patternsを含む構造化JSONを出力します。 CI統合に適しています:

plugin-eval score ./path/to/skill --depth quick --output json --threshold 70
# スコア < 70の場合、コード1で終了します

完全認証 (3つのレイヤー全て+Elo)

plugin-eval certify ./path/to/skill

静的+LLMジャッジ+モンテカルロ(50シミュレーション)+Eloランキングを実行します。15–20分かかります。 品質バッジを割り当てます。スキルをマーケットプレイスに公開する前に使用します。

ヘッドツーヘッド比較

plugin-eval compare ./skill-a ./skill-b

両方のスキルを高速深度で評価し、次元別比較表を出力します。 2つの実装のいずれかを決定する場合、または書き直し前/後の改善を測定する場合に役立ちます。

Elo用のコーパス初期化

plugin-eval init ./plugins

ローカルコーパスインデックスを~/.plugineval/corpusに構築します。Eloランキングが機能する前に必要です。

複合スコア計算式のスクリプト化

オフラインで複合スコアを再現 (プリコミットフック、CIゲート):

def composite_score(dimension_scores: dict, anti_pattern_count: int = 0) -> float:
    """PluginEval複合計算式をレプリケート。"""
    WEIGHTS = {
        "triggering_accuracy":    0.25,
        "orchestration_fitness":  0.20,
        "output_quality":         0.15,
        "scope_calibration":      0.12,
        "progressive_disclosure": 0.10,
        "token_efficiency":       0.06,
        "robustness":             0.05,
        "structural_completeness":0.03,
        "code_template_quality":  0.02,
        "ecosystem_coherence":    0.02,
    }
    raw = sum(WEIGHTS[d] * s for d, s in dimension_scores.items())
    penalty = max(0.5, 1.0 - 0.05 * anti_pattern_count)
    return round(raw * 100 * penalty, 2)

# 例: トリガー精度が弱いスキル
scores = {
    "triggering_accuracy":    0.65,  # D — 説明の作業が必要
    "orchestration_fitness":  0.85,
    "output_quality":         0.80,
    # … 残りの7つの次元を入力 …
}
# composite_score(scores, anti_pattern_count=1) → ~76.5

JSON出力フォーマット

--output jsonのトップレベル形状:

{
  "composite": { "score": 76.5, "badge": "Silver", "elo": null },
  "dimensions": {
    "triggering_accuracy": { "score": 0.65, "grade": "D", "ci_low": 0.60, "ci_high": 0.70 },
    "orchestration_fitness": { "score": 0.85, "grade": "B", "ci_low": 0.80, "ci_high": 0.90 }
  },
  "layers": [
    { "name": "static", "duration_ms": 1243, "anti_patterns": ["OVER_CONSTRAINED"] },
    { "name": "judge", "duration_ms": 48200, "judges": 1, "kappa": null }
  ]
}

CIでcomposite.scoreを解析してデプロイメントをゲート:

score=$(plugin-eval score ./my-skill --output json | python3 -c "import sys,json; print(json.load(sys.stdin)['composite']['score'])")
if (( $(echo "$score < 70" | bc -l) )); then
  echo "Quality gate failed: score $score < 70"
  exit 1
fi

---

スキルのスコアを改善するためのヒント

次元を重み順に処理します。最大の利得は、最も重くスコアリングされた次元を最初に修正することから生まれます。

最初に改善する次元

複数のD/F成績を示すスコアレポートがあり、取り組みの優先順位を付ける必要がある場合、 このテーブルを使用します。

次元	重み	典型的な修復労力	スコア影響/時間	以下の場合最初に修復
triggering_accuracy	0.25	低 — 説明の書き直し	高	総スコア < 70
orchestration_fitness	0.20	中 — セクション再構成	高	スキルがワーカー+スーパーバイザーロジックを混合
output_quality	0.15	中 — 例を追加	中	ジャッジスコア < 0.70
scope_calibration	0.12	低 — コンテンツをreferences/に移動	中	ファイルが < 100または > 800行
progressive_disclosure	0.10	低 — references/ディレクトリを作成	中	references/ディレクトリが存在しない
token_efficiency	0.06	低 — MUST/ALWAYS/NEVERを削減	低	アンチパターン数 ≥ 3
robustness	0.05	低 — トラブルシューティングセクションを追加	低	ドキュメント化されたエッジケース処理なし
structural_completeness	0.03	非常に低 — 見出し/コードブロックを追加	低	4未満のH2見出し
code_template_quality	0.02	非常に低 — 言語タグを追加	非常に低	言語タグが欠落しているコードブロック
ecosystem_coherence	0.02	非常に低 — 関連セクションを追加	非常に低	クロスリファレンスなし

経験則: triggering_accuracyを最初に修正します — 重み0.25では、 すべての低重み次元を組み合わせた時間あたりの複合スコア利得以上を提供します。

トリガー精度 (重み0.25)

• "Use this skill when..." に続けて、3–4個のコンマ区切りの具体的なコンテキストを含めます。
• スキルが明示的なユーザーリクエストなしに自動アクティブ化される場合、"proactively" を追加します。
• メンタルテスト: それをトリガーすべき5つのプロンプトと、そうすべきでない5つを書きます — あなたの説明は区別していますか？そうでない場合は、コンテキスト句を追加または厳しくします。

オーケストレーション適合性 (重み0.20)

• スキルが受け取るもの、スキルが返すものをドキュメント化します — オーケストレートするものではなく。
• SKILL.md で "orchestrate"、"coordinate"、"dispatch"、"manage workflow" を避けます。
• "Output format" セクションと、具体的なワーカー動作を示す2つ以上のコードブロックを含めます。

出力品質 (重み0.15)

• 単なるゴール以上の、具体的で実行可能な指示を与えます。
• 明示的に少なくとも1つのエッジケースをカバーします (空の入力、不正形式のデータなど)。
• 代表的な入力と予想される出力を示す例セクションを含めます。
• 指示が具体的なほど、ジャッジはこの次元をより高くスコアリングします。

スコープキャリブレーション (重み0.12)

• 200–600行を目指します。100未満はスタブ、references/がない800以上は肥大化しています。
• 背景資料、拡張例、およびリファレンステーブルをreferences/に移動します。
• 非常に狭いスキルは兄弟とマージされるべき、非常に広いものは分割されるべき。

進行的な情報開示 (重み0.10)

• references/ディレクトリを追加 (0.15–0.25ボーナスを獲得) し、SKILL.md を実行パスに焦点を当てます。 assets/ディレクトリはさらにボーナスを追加します。

トークン効率 (重み0.06)

• MUST/ALWAYS/NEVER数を監査します。10行あたり1未満を目指します。
• 近似的なダブルの箇条書きと繰り返し構造テーブルを統合します。

堅牢性 (重み0.05)

• "Troubleshooting" または "Edge Cases" セクションを追加し、少なくとも3つの障害モードをカバーします。
• スキルがタスクを完了できない場合に返すものを述べます。

構造的完成度 (重み0.03)

• 最低4つのH2/H3見出し、3つのコードブロック、例セクション、およびトラブルシューティングセクションを確認します。

コードテンプレート品質 (重み0.02)

• すべてのコードブロックは構文的に有効で、言語タグ付きでコピー&ペースト対応である必要があります。

エコシステムコヒーレンス (重み0.02)

• 兄弟スキルまたはエージェントを相対パスでリストする "## Related" セクションを追加します。
• 既に別のスキルに存在するコンテンツを複製することは避け、代わりにそれにリンクしてください。

---

トラブルシューティング

「コンテンツを追加した後、スコアが予想より大幅に低くなった」

アンチパターンペナルティは合成されます。--output jsonで実行し、 layers[0].anti_patternsを検査します。5つ以上のアンチパターンがある場合、 コンテンツがどれほど良いかに関わらず、乗数はスコアを生のスコアの75%に削減できます。 最初にフラグを修正します。

「詳細な説明があるにもかかわらず、triggering_accuracyが低い」

_description_pushinessスコアラーは、長さだけでなく、特定の構文パターンを探します。 あなたの説明に "Use this skill when" または "Use when" というフレーズが含まれていることを確認してください (正確なフレーズが重要です — 正規表現一致です)。また、特異性ボーナスを獲得するために、 コンマまたは "or" で区切られた複数のユースケースがあることを確認してください。

「実行間でLLMジャッジスコアが大きく変動する」

これは曖昧なスキルでは予想されます。ジャッジは10個のメンタルテストプロンプトを非決定論的に生成します。 説明を厳しくし、具体的な例を追加することで、スコア安定性を改善します。 judges > 1の場合、平均化されたスコアはより安定します。--depth deepでcertifyを使用して、 統計的に境界付けられたスコアを取得します。

「ファイルが正しい長さであるにもかかわらず、progressive_disclosureスコアが低い」

ファイルが200–600行のスイートスポットにあるかどうかを確認します。100行未満のファイルは、 このサブチェックで0.20しかスコアしません。また、references/ファイルが空でないことを確認してください — スコアラーはディレクトリではなく、空でないリファレンスファイルをチェックします。

「比較で書き直しが元のスコアより低い結果を示している」

高速深度 (--depth quick) は静的分析のみを実行します。書き直しがコンテンツをreferences/に移動し、 SKILL.md を大幅に短縮した場合、構造的完全性の静的スコアは、全体的な品質が改善した場合でも低下する可能性があります。 LLMジャッジの評価を含む --depth standard でより公正な比較を実行してください。

---

リファレンス

• 完全なルーブリック根拠 — すべての4つのジャッジ次元

関連エージェント

• eval-judge (../../agents/eval-judge.md) — レイヤー2の次元をスコアリングするLLMジャッジ (triggering_accuracy, orchestration_fitness, output_quality, scope_calibration)。 ジャッジレイヤーのみを再実行するか、その推論を検査する必要がある場合に直接呼び出します。
• eval-orchestrator (../../agents/eval-orchestrator.md) — すべての3つのレイヤーをシーケンス処理し、 結果をマージし、バッジを割り当て、最終レポートを書く、トップレベルのオーケストレーター。 完全な認証パスを実行するか、2つのスキルをヘッドツーヘッドで比較する場合に呼び出します。