evaluate-skill

スキルを評価する

スキルの編集の良し悪しは、生成されるレポートによって決まります。このワークフローでは、スキルファイル、1 行のビジネス概要、ロックダウンされたローカル MCP エンドポイント以外は何も知らないセッションで候補のスキルを実行し、返された内容を比較します。

前提条件

• 認証なしモードのローカルサーバー：.env.local で AUTH_MODE=local_noauth を設定し、pnpm db:migrate:local と pnpm dev（または pnpm dev:agents）を実行します。表示された URL に /mcp を付けたものを --endpoint として渡します。デフォルトのローカル D1 を使用し、リモートバインディングやリモート Postgres は決して使用しないでください。ログイン機能がないため、非公開にしてください。
• codex CLI がパス上にあること。実行時には、設定済みのデフォルトモデルを高い推論レベルで使用します。モデル名を記録する必要がある場合は、イベントログから解決済みのモデルを確認してください。
• リサーチ用クレジット：ローカルサーバーも引き続き DataForSEO を呼び出します。監査を 1 回実行すると、ツールを 20～40 回呼び出します。比較に必要な以上のセッションは実行しないでください。

実行

node .agents/skills/evaluate-skill/scripts/run.mjs \
  --skill seo-audit \
  --site example.com --site holdout.example \
  --brief "Evaluation brief: Acme at example.com sells <what>. The goal is relevant organic visitors who could become customers. No first-party analytics are connected." \
  --brief "Evaluation brief: <the holdout business>. ..." \
  --endpoint http://<local-dev-host>/mcp

実行には約 10～14 分かかり、並列で行われます。ツール呼び出しのタイムアウトでシェルが終了するとセッションも終了するため、スクリプトはデタッチして起動してください。

(nohup node .agents/skills/evaluate-skill/scripts/run.mjs ... > .logs/eval.log 2>&1 &)

サイトごとに、スクリプトは次の処理を行います。

1. 候補のスキルと seo-report を新しい一時フォルダーにコピーします。実行中の編集によって指示が変わることはありません。マニフェストにはスキルのハッシュが記録されます。
2. 概要だけをシードとして、新しいローカルプロジェクトを作成します。
3. ローカル MCP の前にゲートウェイを起動し、固定のツールリストのみを許可します。また、別のプロジェクト ID に対する呼び出しをすべて拒否し、開始前にその拒否を確認します。
4. ユーザー設定、メモリ、アプリ、プラグイン、マルチエージェントを無視し、スキルのセルフレビューだけをレビュアーとして codex exec をエフェメラルモードで実行します。
5. 保存されたレポートの HTML、すべての MCP 呼び出しと応答、イベントストリーム、最終メッセージを出力フォルダーに記録します。

node .agents/skills/evaluate-skill/scripts/report-text.mjs <out>/*-report.html でレポートを確認します。各セッションの作業メモ（seo-audit の場合は opportunities.md と evidence/）は、一時フォルダーに残ります。その場所は manifest.json に記載されています。

分離ルール

• 指示： 凍結したコピーのみを使用します。セッションから作業ツリーを参照させないでください。
• 会話： 実行ごとに新しい codex exec を使用します。再開やフォークはしないでください。
• データ： 実行ごとに新しいプロジェクトを作成し、ユーザー提供の概要以外は何も入れずにシードします。セッションが読み取れるプロジェクトに、評価者のメモ、以前のレポート、参照用の回答を書き込まないでください。
• プロンプト： すべてのバリアントで同じ中立的なプロンプトを使用します。想定される調査結果、ターゲットキーワード、評価基準については明かさないでください。
• 評価資料（評価基準、参照監査、以前のレポート）は、セッションフォルダーとリポジトリの外に保管します。未加工の成果物は、無視対象の .logs/ に保存します。

これは実用上の分離であり、セキュリティ境界ではありません。セッションはローカルアカウント、プロバイダーのキャッシュ、組織の制限を共有します。

比較

調整対象のサイトで少なくとも2回、形態の異なるホールドアウトサイトで1回、必ずセッションを実行してください。そうすれば、ある企業の回答にしか当てはまらない指示を見つけられます。失敗を含め、すべての実行結果を残してください。複数の結果から最良のものだけを選び、スキルが修正されたと判断してはいけません。

ツールのトレースを開く前に各レポートを採点し、その後トレースを確認して、見落としを発見、ツール、推論、レポートのいずれに分類するか判断してください。監査レポートでは、次のように評価します。

項目	配点	優れたレポートの特徴
発見と網羅性	25%	商用ページとその関連ページ、ツール、技術的な経路を確認し、兆候があれば調査範囲を広げる
診断と証拠	20%	実際のページと検索結果を確認し、観察事項と原因を区別し、出典、日付、設定を記録する
ビジネス価値と規模	20%	各施策を実在する購入者と結び付け、競合する機会を比較し、コンバージョンや収益を決してでっち上げない
優先順位付け	15%	購入可能性の高いユーザーに関する、実証済みの問題を対象に、範囲を限定した変更を最優先し、保守や広範な施策は後回しにする
判断の適切さ	10%	アナリティクスがなくても有用な判断を示し、証拠で裏付けられないペナルティ、因果関係、傾向の主張をしない
伝達と実行可能性	10%	ページ、変更内容、理由を明記し、レポートを短縮しても重要な調査結果を残す

重大な事実誤認があれば、採点結果にかかわらず問題とします。レポートの数値を信頼する前に、別のモデルに依頼し、実行時のMCPログだけを使って、実際の掲載順位をすべて再計算してください。

どのサイトにも応用できる網羅性の確認項目：

• 重要なページ群（比較、料金、テンプレート、地域）の関連ページを並べて確認し、共有回答内の名前だけを差し替えたページに気付いている。
• 対象クエリですでに上位にあるページは、書き換えずに保護している。
• 有望な候補はすべて、推奨事項にするか、実質的な理由を添えて表の行に記載している。曖昧な「後で対応」は見落としとみなす。
• 検索ボリューム、訪問数、収益をそれぞれ区別し、米国の需要を世界全体の数値に単純に掛け合わせていない。

過去の評価から得た教訓

• 指示は長いほど効果が落ちます。 注意事項を並べた3,600語のスキルは、固定の手順を設けた2,200語のスキルよりも成績が悪くなりました。警告ではなく、手順を追加してください。
• 比較を必須にしてください。 下書きの前に候補リストを作成したセッションでは診断内容が保たれましたが、調査からすぐに下書きを作成したセッションでは、生の検索ボリューム順に候補を並べていました。
• 却下した候補も示してください。 レポート内の「ほかに確認した項目」表が、レポートを短縮したときに重要な調査結果が消えるのを防ぎます。
• 一度だけのスナップショットは当てになりません。 8位から12位あたりの順位は、数分間隔の確認でも変わります。決定的なクエリはスキルで再実行し、両方の結果を報告してください。
• ラベルは注記に勝ります。 読者は「オーガニック検索結果17件中10番目」や矢印を受け入れませんでした。現在は市場と日付を見出しに記載し、表には「#10（1ページ目）」と示しています。

クリーンアップ

各実行のプロジェクト、レポート、監査は、delete_report、delete_site_audit、update_project_context を使ってMCP経由で削除するか、ローカルデータベースに残しておくことができます。以前のプロジェクトがクリーンな状態だと証明するより、実行ごとに新しいプロジェクトを作成するほうが簡単です。作業が終わったら、ローカルサーバーを停止してください。