create-verification-skill

検証スキルを作成する

太字またはバッククォートで示されたスキル名、あるいは /<name> として実行されるスキルは、このスキルのディレクトリの隣にある ../<name>/SKILL.md ファイルです。接頭辞なしで示された原則名は ../principle-<name>/SKILL.md です。そのファイルを読み、従ってください。pstack スキルのほとんどはユーザー専用のため、スキルツールでは読み込めません。

本格的なプロジェクトには、実際のアプリを操作して動作を証明するスクリプト化された方法が必要です。アプリを起動し、ユーザーと同じように機能を操作して、証拠を記録します。このスキルは、リポジトリに合わせたプロジェクトローカルのスキル（.agents/skills/verify-<app>/。.claude/skills/verify-<app> からリンク）を生成します。人間向けではなく、次のエージェント向けにジェネレーターの出力を作成してください。アプリを見たことのないエージェントが、作業の途中で初めて読みます。

1. ユーザーではなくリポジトリを調べる

コードベースから以下を確認し、観察できないことだけをユーザーに尋ねてください。

• 対象画面： ユーザーが実際に操作するものは何ですか？Web UI、CLI/TUI、デスクトップアプリ、API、モバイルアプリ、ライブラリのどれですか？リポジトリに複数ある場合は、主要なものを選び、ほかも記載してください。
• 起動方法： アプリをローカルで起動するにはどうしますか？リポジトリに記載された開発コマンド（パッケージスクリプト、Makefile、README のクイックスタートなど）を優先してください。ポート、環境変数、シードデータ、認証について記載してください。
• 操作方法： エージェントがプログラムから操作するにはどうすればよいですか？まず既存のハーネスを確認します。Playwright/Cypress のテスト、expect スクリプト、PTY ヘルパー、curl で呼び出せるエンドポイント、デバッグポートなどです。そのうえで、汎用的な方法を選びます。Web UI には preview_* ツール（動画には preview_recording_start / preview_recording_stop）、Electron にはデバッグポート上の CDP、iOS と Android のシミュレーターには device_* ツール、CLI/TUI にはシェル内の tmux/PTY ハーネス、サービスには通常の HTTP を使います。
• 観察方法： どのような証拠を記録できますか？スクリーンショット、ターミナルの記録、レスポンス本文、ログ、終了コード、DB の状態などです。
• 分離方法： 2 つのインスタンスを並行して実行できますか（ポート、データディレクトリ、プロファイルなど）？できない場合は、生成するスキルにその旨を記載してください。共有インスタンスを二重操作してユーザーのセッションを破損させるより、操作を拒否する方が適切です。

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

2. スキルを生成する

実際のディレクトリ .agents/skills/verify-<app>/ と相対シンボリックリンク .claude/skills/verify-<app> -> ../../.agents/skills/verify-<app> を作成し、Claude Code と Codex の両方のスレッドで読み込まれるようにします。両方をコミットします。そこに YAML フロントマター（name: verify-<app> と、アプリ名、対象となる操作面、どのようなときに使用するかを明記した description を含めます。フロントマターがないとスキルは登録されません）付きの SKILL.md を作成し、以下のセクションを記述します。各セクションの内容は、実際のインタビューで判明したことに基づくものとします（プレースホルダーを残さないでください）。

• Launch： 検証のためにアプリを起動する正確なコマンドと、起動完了を判断する方法（ログ行、プロンプトなど）。空のデータディレクトリから使用可能な状態まで起動できる必要があります。これには、必要なマイグレーションとシードデータも含まれます。起動完了とは、単にプロセスが応答することではなく、使用可能な状態を指します。データベースのヘルスチェックが成功しても、初期化スクリプトがまだ実行中の場合があります。終了方法も含めます。短時間で終了する CLI や TUI には維持すべきサーバーがありません。その場合、起動とはバイナリを一度ビルド（または依存関係をインストール）してから、それぞれの操作を独立した PTY または tmux セッションで開始することを意味します。
• Doctor： 「このインスタンスを操作する価値があるか」に答える、読み取り専用のチェックを1つ記載します。プロセスが起動しているか、バージョン／ビルドが正しいか、ポートがこのアプリによって使用されているか、認証が有効かを確認します。何か問題があるように見える場合、エージェントはまずこのチェックを実行します。
• Drive： 例ではなく、このリポジトリに実在するセレクター／コマンドを使ったハーネスの手順を記載します。座標やタブ順よりも、安定した識別子（ARIA ラベル、データ属性、プロンプト文字列、ルートパスなど）を優先します。
• Evidence： 証明用に何をキャプチャし、どこに保存するかを記載します。証明の基準も明記します。内部のセッターやテスト専用エンドポイントではなく、実際のユーザーパスを操作すること。最終画面だけでなく、操作とその結果の状態をキャプチャすること。画面上で見える内容に加えて、副作用（書き込まれたファイル、挿入された行、送信されたメッセージなど）も検証すること。モックは、本番環境との境界で外部システムがすでに分離されている場合に限ります。安全な手段としてドライランやテストモードを使う場合は、そのモードで実際に何が省略されるかを、名前を信用せず観察して検証します（ファイル、ネットワーク、git の参照など）。ドライランでもネットワークに接続したり、ブラウザーを開いたりすることがあります。
• Cleanup： 実行中に作成したインスタンスを終了する方法を記載します。プロセス名で強制終了してはいけません。自分で開始したものだけを終了します。クリーンアップではインスタンスと一時データを削除しますが、証拠は削除しません。証明用の成果物は終了後も残り、スキル内で指定した場所に保存されます。
• Helpers： スキルに同梱するスクリプトは実行可能にし、その呼び出し方をスキル本文に記載します。読み手がリバースエンジニアリングしなければ使えないものは、ヘルパーではありません。

3. 機能マップを用意する

生成したスキルのディレクトリに features/README.md と、特定できるユーザー向け機能ごとのファイルを1つずつ作成します（ルート、コマンド、メニュー、ドキュメントをもとに、まずは上位3〜5件を目指します）。references/feature-map-example/ にある形式に従い、README の索引と機能ごとのファイルを用意します。各ファイルでは、ユーザーの視点から、その機能の概要、アクセス方法、ハーネスを使った操作方法、正常に動作していることを証明する観察可能な最終状態を説明します。4つの H2 は Sub-features、How to get to it (user POV)、Driving it with <harness>、Gotchas とします。シードデータにユーザージャーニーで必要な前提条件が欠けている場合、そのジャーニーは失敗を報告し、理由を該当する機能の Gotchas に記載します。成功させるためにジャーニーの基準を緩めてはいけません。このマップはリポジトリで維持される検証情報源です。マップに複数の入口が記載されている場合、そのうち都合のよい入口を1つ操作しただけの証明は不完全です。

4. 引き渡す前に、生成したスキルが動作することを確認する

スキル独自の手順を最初から最後まで一度実行します。起動し、診断し、マッピングした機能を1つ操作し（1つで十分です。マップがあるので、後の実行では残りを確認できます）、証拠を記録して、クリーンアップします。クリーンアップ後、証拠が指定された場所に残っていることを確認します。証拠を消してしまうクリーンアップでは、この手順を完了したことになりません。失敗した箇所を修正し、失敗した試行の後も、毎回生成されたクリーンアップを実行します。壊れた試行によってプロセスやポートが残らないようにしてください。一度も実行していない生成スキルは成果物ではなく、草稿です。実際の対象の代わりとなる環境（新しい VM の代わりにコンテナ、リモート環境の代わりにローカルスタック）で動作を確認した場合は、その代替環境で実行したセットアップ手順のうち、実際の対象では行われないものをすべて列挙してください。それらの手順は、実際の対象で実行して確認するまで未検証のままです。

5. メンテナンスの手順を案内する

アプリの変更に合わせてマップを正確に保つため、ユーザーに /maintain-verification-skill を案内します。ユーザーから求められた場合にのみ、実施頻度を提案してください。