agent-plugin-eval

エージェントプラグインの評価

ポータブルな Agent Plugins 仕様を正とします。クライアント固有の マニフェスト（例：.codex-plugin/plugin.json、.claude/settings.json、 .cursor/mcp.json）は、ルートの必須ファイルである plugin.json の代わりにはなりません。

パラメーター

パラメーター	説明	デフォルト
target	ローカルリポジトリ／プラグインのパス、または Git URL	未指定の場合は確認
compare	任意の比較対象パスまたは Git URL	なし
output	スコアカードの保存先	返信のみ。要求された場合にのみ書き込み
spec_version	評価対象の Agent Plugins バージョン	plugin.json に記載されたバージョン、または 1.0.0

安全性の境界

信頼できないリポジトリは静的に監査してください。ユーザーが実行を明示的に許可しない限り、同梱の実行ファイル、フック、インストールスクリプト、パッケージマネージャー、MCP サーバー、ネットワークを使用するテストを実行しないでください。秘密情報と疑われる値は伏せ字にし、場所と種類のみを報告してください。秘密情報らしいキーや値は疑いの対象にすぎず、認識可能な有効な認証情報の形式、信頼できる秘密情報スキャナー、リポジトリの履歴／出所、またはユーザーによる確認などの裏付けとなる証拠がない限り、FAIL ゲートを割り当てないでください。認証情報を確認するだけの目的で、サービスに対して試さないでください。

ワークフロー

1. プラグインのルートを特定します。 ローカルの対象はそのまま使用します。Git URL の場合は、mktemp -d ディレクトリに浅くクローンします。プラグインのルートにはルートの plugin.json が含まれます。リポジトリ内に候補がゼロまたは複数ある場合は、推測せず曖昧であることを報告します。すべての対象が明示的なプラグインのルートに一つずつ対応付けられたら完了です。
2. 適用されるルールを読み込みます。 references/spec-checklist.md と references/rubric.md を読みます。Agent Plugins 1.0.0 には、同梱されたスナップショットを使用します。宣言されたバージョンが異なる場合、またはユーザーが最新仕様を求めている場合は、agent-plugins.org の正式な仕様とスキーマを参照し、評価したバージョンと取得日を記録します。JSON Schema と矛盾する場合は、規範となる本文を優先します。
3. すべてのパッケージパスを調査します。 ドットファイル、シンボリックリンク、スキルの直下の子要素、拡張機能の名前空間、実行可能ファイル、Git の無視対象ファイルを含めます。すべてのシンボリックリンクとパッケージ相対パスをプラグインのルートを基準に解決します。見つかったすべてのパスを、移植可能なコア、クライアント拡張機能、補助ファイル、または包含違反のいずれかとして分類したら完了です。
4. 決定論的スキャンを実行します。 python3 scripts/inspect_plugin.py <plugin-root> --json を実行します。出力は調査の手がかりとして扱い、最終判断とはしません。報告された各問題をソースで確認し、file:line または JSON ポインターの根拠を追加します。たまたまクライアントが受け入れるという理由で、規範上の指摘を決して緩和しないでください。
5. コンポーネントをすべて確認します。 すべての skills/*/SKILL.md とすべての mcpServers エントリーを調査します。Agent Skills は独自の仕様に照らして検証します。指示、リソース、スクリプト、MCP 設定、拡張機能の分離、まとまり、実用性を評価します。skill-evaluation が利用可能であれば、個々のスキルの品質分析を深めるために使用できますが、このプラグインレベルのルーブリックに代わるものではありません。
6. 採点する前に適合性を分類します。 references/spec-checklist.md に定められた正確な失敗境界を使用し、PASS、PARTIAL、FAIL のいずれかに分類します。クライアント互換性と移植可能な適合性は分けて扱います。クライアント固有の機能は、そのクライアントにとって優れたものであっても、移植可能な適合性への加点はゼロとなる場合があります。
7. 根拠がなければ採点しません。 references/rubric.md の該当するすべての基準を採点します。各スコアには具体的な根拠が必要です。N/A にはすべて理由が必要です。加重結果と上限を求めるために scripts/score.py を実行し、手計算はしないでください。すべての基準と指摘が適合性ステータスと整合したら完了です。
8. 指定された言語で回答します。 references/output-template.md を読み、その構成に従って出力します。判定を最初に示し、ブロッカーと推奨事項を区別して、具体的な修正方法を提示します。compare が設定されている場合は、差分を計算する前にそれぞれを独立して評価します。両方のプラグインに同じ N/A の項目を無理に適用しないでください。

ゲートと採点

• PASS：規範違反が見つかっていません。スコアの上限はありません。
• PARTIAL：致命的ではないマニフェストの逸脱、または無効化／スキップされたコンポーネントがあります。最終スコアの上限は59です。
• FAIL：致命的なマニフェスト／パッケージルートの不備、ルートマニフェストからの逸脱、または埋め込み認証情報が確認されています。最終スコアの上限は39です。
• 上限適用前のスコアも表示し、設計品質とリリースを妨げる適合性の問題を作者が区別できるようにします。

各基準につき criterion:score:weight の組を一つ指定して、計算ツールを呼び出します。

python3 scripts/score.py --gate partial 1:90:3 2:80:3 3:NA:2

Jev による評価（任意）

TypeSafe Jev を利用できる場合は、主観的な品質基準の評価に使用します。Jev は、決定論的チェックを補完する、調整済みの確率判断を提供します。

Jev を使用するタイミング

評価の種類	Jev を使用しますか？	方法
軸 1～3 の適合性	いいえ	決定論的に判定（inspect_plugin.py）
軸 4 の製品品質	はい	スコア評価（UX、ドキュメント、エラー）
軸 2 の品質基準	はい	スコア評価（スキーマ設計、命名）
ゲートの分類	はい	Noul（合格／不合格の分類）
シークレットの検出	はい	Noul（疑いあり／疑いなし）
品質チェックリスト	はい	Noul（存在／欠落）

検出プロトコル

from typesafe import jev_available

if jev_available():
    from typesafe import Score, Noul
    # Use Jev for subjective criteria
else:
    # Fall back to heuristic scoring

質問と統合

質問は scripts/jev_questions.json で定義されています。

• 7 つの Score 質問：軸 4（UX の一貫性、ドキュメントの明確さ、エラー処理）と軸 2（検証、スキーマ設計、命名、API の洗練度）
• 20 の Noul 質問：ゲート（G1～G4）、シークレット（4）、品質チェックリスト（7）、コンポーネントの有効性（4）

Score の結果（0.0～1.0）は軸ごとに平均され、ルーブリック（0～25）に合わせてスケーリングされます。 Noul の結果は、ゲートとチェックリストの分類を示します。

統合パターンとコード例の詳細は、references/jev-integration.md を参照してください。

出力形式

Jev を使用した場合、スコアカードには jev セクションが含まれます。

{
  "jev": {
    "available": true,
    "quality_scores": { "ux_coherence": 0.72, ... },
    "gate_classifications": { "G1": {"label": "conformant", "passed": true} },
    "secret_findings": { "requires_review": false }
  }
}

注意点

• v1 のポータブルコアに含まれるのは、Agent Skills と MCP サーバーのみです。Hooks、commands、agents、apps、marketplaces、および配布ポリシーは、有効な拡張名前空間に配置されていない限り、クライアント固有です。
• オプションの skills/ または mcp.json がなくてもエラーではありません。存在するパスのファイルシステム上の種類が正しくない場合は、無効なコンポーネントタイプです。
• 不明なルートマニフェストフィールドはスキーマ違反ですが、仕様上、限定的な非致命的扱いとなります。その他のマニフェストスキーマ違反の大半は、プラグイン全体を不合格にします。
• 無効なスキルまたは MCP サーバーが 1 つあっても、独立したすべてのコンポーネントが無効であるかのように報告してはいけません。
• ${PLUGIN_ROOT} と ${PLUGIN_DATA} は、MCP の args、env の値、cwd でのみ展開されます。command、URL、ヘッダーでは展開されません。
• クライアントネイティブのプラグインが高品質であっても、ルートに plugin.json がない場合、ポータブル標準に準拠しないことがあります。両方の事実を、平均化して曖昧にせず報告してください。
• 資格情報の可能性があるものは「疑いあり」と表示し、伏せ字にしてください。ヒューリスティックによる検出だけでもセキュリティスコアは下がり、修正の確認が必要になりますが、資格情報が確認された場合の FAIL ゲートにはなりません。

最終品質ゲート

• すべての対象が、ちょうど 1 つのルートに解決されている
• すべてのファイル、シンボリックリンク、スキル、MCP サーバー、拡張機能を検査している
• すべての規範的な違反を、適切な失敗境界に対応付けている
• すべてのスコアの根拠を示し、N/A の理由を説明している
• 疑いのあるシークレットを伏せ字にしている
• scripts/score.py でスコアを算出している
• 比較差分に、独立して算出したスコアを使用している