create-verification-skill

検証スキルを作成する

アプリを変更するコーディングエージェントは、ユーザーから見たときと同じように変更を確認できる必要があります。このスキルでは、e2e を基盤として、1 つのプロジェクト用の検証手順をスキル .agents/skills/verify-<app>/ として作成します。設定でアプリを起動し、e2e mcp で実際に操作し、テストで満たすべき条件を固定し、e2e explore でバグを探し、.e2e/ に証拠を保存します。出力は人間ではなく、次のエージェント向けに作成してください。アプリを一度も見たことがないエージェントが、作業の途中で初めて読むことになります。

e2e スキルは、e2e のすべての機能についてのリファレンスです。まずこれを読み、内容を繰り返すのではなく、参照先としてリンクしてください。これは、このスキルのインストール元にかかわらず、同階層にある e2e スキルです。見つからない場合は、npx skills add tester-army/e2e または npx e2e init でインストールできます。npx e2e guide <topic> は、プロジェクトにインストールされたパッケージのリファレンスを表示します。内容が異なる場合は、そちらを優先してください。以下に記載されているトピック（setup、writing-tests、mcp、explore、bug-bash、running、debugging）は、リファレンスファイル名です。

1. ユーザーではなく、リポジトリに聞く

コードベースから確認できることはそこから把握し、確認できないことだけをユーザーに尋ねます。

質問	答えがある場所	判断する内容
サーフェス	ユーザーが操作する対象です。Web UI、iOS または Android アプリ、API などです	主なサーフェスごとにスキルを1つ作成し、その他は次回実行用に名前を挙げます。Web では @e2e-dev/web、iOS と Android では @e2e-dev/mobile を使用します。UI のない API にも、ランナーが起動できるよう app.url と app.command を指定した web() ターゲットを設定します。また、そのテストでは app のみを受け取り、fetch を使用します（トピック writing-tests）。ネイティブのデスクトップアプリには、まだ e2e エンジンがありません。その場合はその旨を伝えて終了します。エンジンが操作できるサーフェスを持たないプロジェクト（CLI、ライブラリ、バッチジョブなど）も同様です。また、ブラウザーにネイティブランタイムの通知しか出力しないデスクトップフロントエンドも該当します。UI のない HTTP サービスはこれらには該当せず、この行の手順で web() を使って操作します。書き込み後ではなく、確認した時点で終了します。エントリーポイントと、それを操作できないエンジンを明示し、スキルを生成しなかったことを伝えます
実行	ドキュメントに記載された開発コマンド、ポート、環境変数、シードデータ、認証	ターゲットの app.command（トピック setup）。アクセス時に初めてルートをコンパイルする開発サーバーは、エージェントからは壊れているように見えます。そのため、リポジトリに本番ビルド用コマンドがある場合はそちらを優先します
e2e の状態	e2e.config.ts、tests の glob、package.json の e2e、.agents/skills/e2e/、.codex/config.toml、.mcp.json、.cursor/mcp.json にある MCP サーバー、および Playwright や Cypress のテストスイート	サーフェスの行でエンジンが操作できる対象を確認できている場合、ここに何もなければ、まず npx e2e init を実行します（トピック setup）。このスキルを実行すると、そのセットアップが要求されます。Init は Claude Code と Cursor 用の MCP を登録します。Codex には専用のプロジェクトエントリが必要です（トピック mcp）。実際に操作する前に、セッションで e2e ツールを使えることを確認します。既存の Playwright または Cypress のテストスイートは、ロケーター、シードデータ、サインイン手順を調べる最適な情報源です。内容を確認してください。モデルを指定していない設定では、決定論的な手順と MCP ツールだけが実行され、それ以外は実行されません
観察	トレースページ、スクリーンショット、動画、レポート、およびファイル、行、送信メッセージ、ログにアプリが残すもの	副作用の保存先によって「Evidence」セクションの内容が決まります。今のうちに確認してください
分離	2つのインスタンスを並行して実行できますか？	app.url のポートを 0 にすると、実行ごとに専用のアプリが起動します。command.reuseExisting: true を指定すると、そのポートですでに起動しているアプリに接続します。複製できない共有インスタンス（データベースが1つだけ、シミュレーターが1台だけなど）がある場合は、生成するスキルにルールとして記載します。ユーザーのセッションを壊すより、同時に2回操作することを拒否するほうが適切です
名前	パッケージ名またはリポジトリ名	スコープを付けずに小文字で指定した verify-<app> の <app>

チェックアウトの状態でビルドまたは起動できない場合は、まず修正するか、スキルを生成する前に問題を正確に報告します。壊れた状態を基にスキルを書くと、誤った手順を教えることになります。API が配信しない静的ディレクトリやサンプル設定ファイルなど、関係のないアセットが不足している場合は、生成したスキルで作成して「検証用の足場」と明記し、クリーンアップ時に削除してもかまいません。

既存の verify-<app>/ がある場合は、何かを書き込む前にその内容を確認します。既存の SKILL.md と機能ファイルは維持し、マップに不足している機能を追加します。既存のファイルを変更するのは、アプリの実態と食い違う場合だけです。

2. スキルを生成する

YAML フロントマターを付けて .agents/skills/verify-<app>/SKILL.md を作成します。 name: verify-<app> と、アプリ名、サーフェス、スキルを使うタイミングを明記した description を設定します。フロントマターがないと、スキルは登録されません。プロジェクトに .claude/skills/ がある場合は、e2e init と同じ方法でリンクします。相対シンボリックリンク .claude/skills/verify-<app> のリンク先は ../../.agents/skills/verify-<app> です。各セクションには、調査で判明した内容を記載し、プレースホルダーは使いません。

セクション	内容
最初に読む	e2e スキルを案内し、このスキルが操作する設定ファイルと tests の glob を示す一文
起動	検証のためにアプリを起動する正確なコマンドと、準備完了を確認する方法。対象に app.command がある場合、起動方法は npx e2e run <smoke file> または MCP 経由の open_session です。ランナーがアプリを起動し、URL を待ってから停止します。ない場合は、app.url のみを持つ対象と、ユーザーが手動で起動する開発コマンド、およびポートが応答していることを示す行を記載するか、コマンドはそのままにして reuseExisting: true を設定します。コマンドに必要なポートと環境変数、およびデータのシード方法を記載します
診断	「このインスタンスは操作する価値があるか？」に答える読み取り専用チェックを一つ記載します。npx e2e list は設定を読み込み、何も起動せずにすべてのテストと対象の組み合わせを表示するため、設定エラーはまずここに表示されます。次にスモークテストを実行します。スモークテストはモデル不要のテストで、アプリを開いてランドマークを一つ固定します。終了コード 0 は、アプリが起動し、エンジンが実行され、ランドマークが表示されたことを意味します。プロジェクトにスモークテストがない場合は、今すぐ tests/smoke.e2e.ts を作成します。サインインが必要なアプリの認証診断は、名前付きセッションを使用する通常のサインイン済みスモークテストです。そのテストを選択するとセットアップが実行され、復元された状態がチェックされるため、一つのコマンドでアプリの起動、セッションの復元、サインイン済みのランドマークの表示を確認できます。セットアップファイルだけを実行するとテストが選択されず、NO_TESTS で終了するため、診断にはなりません。何かおかしい場合、エージェントはまず診断を実行します
操作	2 つの方法と、それぞれを使う場面を記載します。MCP を使ったライブ操作：open_session、observe、各種動作、ロケーターを記述する前の locate（トピック mcp）。セッションのカタログで利用できるプロジェクトのツールと認証情報を列挙します。スクリプト操作：tests の glob に一致するテスト、画面上の名前がわかっている場合の screen、フローが変化する場合の agent.act（トピック writing-tests）。安定したハンドル、ロールとアクセシブル名、ラベル、テスト ID、ルートを優先します。サインイン済みの操作を始める際に使用する認証情報とセッションを明記します
証拠	証明に保存する内容と保存先を記載します。すべての実行で .e2e/report.json が書き込まれます。失敗したテストには .e2e/results/<test>/trace.md が保存され、--trace on を指定すると成功したテストにも保存されます。--video は試行を記録します（トピック running）。app.screenshot('<name>') は名前付きのフレームを保存します（トピック writing-tests）。次回の実行では、診断も含めて .e2e/results/ が消去されます。その後も残す必要がある証明は、--output .e2e/proof/<name> を指定して実行するか、次に何かを実行する前にその試行ディレクトリを別の場所へコピーします。証明の基準（以下）を明記します
バグバッシュ	このアプリでバグバッシュを行う方法（トピック bug-bash）を記載します。作成するバグバッシュ設定（ローカルアプリでできないこと、体勢、インタビューで選んだ分離方法）、シードするアカウント、.e2e/bugbash/ を .gitignore に追加すること、チャーターは機能マップ（セクション 3）から作成するというルールを含めます。検証基準：発見事項は、それを表すアサーションで tests/bugbash/<slug>.e2e.ts が ASSERTION_FAILED で失敗した場合にのみ、バグとみなされます
クリーンアップ	何を停止・削除するかを記載します。ランナーは起動したアプリを停止し、close_session はセッションが起動したアプリを停止します。ユーザーが起動したサーバーはそのまま残します。プロセス名で終了してはいけません。自分が起動したものだけを停止します。クリーンアップではインスタンスと一時状態（シード済みアカウント、足場、すべての発見事項が却下されたチャーター）を削除し、証拠は削除しません。証拠の保存先を明記します
ヘルパー	スキルに同梱するスクリプトはすべて実行可能で、その呼び出し方をスキル本文に記載します。読者がリバースエンジニアリングしなければならないものは、ヘルパーとはいえません。ほとんどのプロジェクトではヘルパーは不要です。e2e CLI がヘルパーです
Evidence セクションの証拠基準：内部セッターやテスト専用エンドポイントではなく、実際のユーザーフローを実行します。最終画面だけでなく、操作とその結果の状態を記録します。インタビューで確認したストアで、副作用（書き込まれたファイル、挿入された行、送信されたメッセージ）を検証します。外部システムが本番環境の境界ですでに分離されている場合に限り、モックを使用します。安全な方法がドライランまたはテストモードの場合は、その名前を信じるのではなく、ファイル、ネットワーク、参照先を監視して、何がスキップされるかを検証します。

3. 機能マップを作成する

.agents/skills/verify-<app>/features/README.md と、特定できるユーザー向け機能ごとのファイルを1つずつ作成します。まずはルート、ナビゲーション、コマンド、ドキュメントから、上位3〜5件を作成します。 references/example/verify-playground/ に従ってください。これは、このジェネレーターが e2e プレイグラウンドアプリ向けに生成し、実行したスキルです。エントリポイントは SKILL.example.md です。クライアントがこれを別のインストール可能なスキルとして検出しないようにするためです。 インデックスは、機能、ルート、テストファイル、ステータス（tested または untested）を記載した表です。各機能ファイルには、ユーザーの視点から次の H2 見出しを設けます。

H2	内容
Sub-features	機能の構成要素を1行ずつ記載します
How to get to it (user POV)	ルート、ナビゲーション、必要なアカウント
Driving it with e2e	機能を固定するテストファイル、重要なロケーター（locate で確認済み）、実際に操作するための MCP 手順
Proof	機能が動作していることを示す、画面上および副作用のストアにおける観測可能な最終状態
Charters	この機能に対する e2e explore の目標を1つまたは2つ記載します。それぞれ、対象領域は1つ、姿勢は1つ、文は1つです（トピックは bug-bash、ステップ2）。バグバッシュで貼り付けられるよう、slug|target|agent|charter の形式でファンアウト行として記述します。サインイン済みの状態から始まるチャーターでは、--session を明記し、単独で実行します
Gotchas	壊れているように見えても実際には問題ない点、およびローカルアプリではできないこと

このマップは、プロジェクトが継続的に管理する検証ソースであり、バグバッシュはそのチャーターを読み取ります。マップにほかのエントリポイントが記載されている場合、都合のよいエントリポイントを1つ操作するだけでは証明として不十分です。また、マップに記載された機能を省略したバグバッシュでは、その抜けが報告されます。テストのない機能にはステップ4でテストを追加するか、インデックスで untested とマークします。

4. 引き渡す前に、生成したスキルが機能することを証明する

プロジェクト内のシェルから、そのスキルの指示に従って最初から最後まで一度実行します。

1. 診断：スキルが指定する npx e2e list の呼び出しとスモークテストを実行します。どちらも終了コードが 0 である必要があります。
2. マッピングした機能を1つ、テストファイルを通して実行します。1つで十分です。マップがあるので、後続の実行では残りの機能も対象になります。テストがない場合は、MCP でロケーターを確認したうえで、機能ファイルをもとに今すぐ作成します。
3. マップからチャーターを1つ選んで、バグバッシュを実施します：npx e2e explore '<charter>' --config <bug-bash config> --agent <persona> --max-steps 3 --output .e2e/bugbash/<slug>。チャーターでセッションが指定されている場合は、--session <name> も追加します。Findings を読み、トリアージします。現時点では、すべての指摘を検証する必要はありません。次に、実行結果の report.json にある run.explore を読みます。終了状態が aborted の場合、またはマッピングしたチャーターではなく一般的な調査が実行された場合、そのバグバッシュは証明されていないため、引き渡し時にその旨を伝えます。手順はチャーターが実行されたことを証明するものであり、終了コードを証明するものではありません。手順が1つも実行されなかった実行も、終了コードは 1 になります。--max-steps による終了状態には、実行で到達したカバレッジが示されます。これで証明できるのはモデル、設定、チャーター、出力ディレクトリであり、アプリではありません。モデルがない場合はこの手順を省略し、バグバッシュが証明されていないことを引き渡し時に伝えます。
4. クリーンアップを行い、指定した場所に証拠が残っていることを確認します。証拠を消してしまうクリーンアップは、この手順を満たしません。

失敗した箇所を修正し、失敗した試行の後も毎回クリーンアップを実行して、ポートやプロセスが残らないようにします。一度も実行されていない生成済みスキルは、成果物ではなく下書きです。プロジェクトはユーザーが使用していた状態のままにします。変更対象は、生成したスキル、その機能マップ、gitignore の行、追加したテストです。ユーザーから別途依頼がない限り、.e2e/ の出力とバグバッシュ設定は未追跡のままにします。

5. 引き渡す

何を作成したかをユーザーに伝えます。スキルのパス、マッピングした機能とそのうちテストがあるもの、チャーター、証明の実行で確認できたこと、証拠のパスを伝えます。マップを使って実行することで、内容が実態に即したものになります。ルートやラベルが変わってテストが失敗した場合は、同じコミットで機能ファイルも変更します。アプリにマップにない機能が追加されたら、このスキルを再実行します。既存のマップをどう扱うかはセクション 1 に記載されています。

対応している機能がないプロジェクトでは、セクション 1 で作業を止めます。その場合の引き渡しでは、確認した内容と、何も作成していないことを報告します。

ルール

• 観察した内容に基づいて生成します。どのアプリにも当てはまるようなセクションは未完成です。
• e2e スキルの1文を、自分で書く段落より優先します。該当するトピックにリンクします。
• 生成したスキルやマップに秘密情報を記載してはいけません。認証情報の名前を記載します（トピック setup）。
• ユーザーに代わってコミットしてはいけません。作成したものを列挙します。