create-verification-skill

検証スキルを作成する

本格的なプロジェクトには、実際のアプリを操作して動作を確認するためのスクリプト化された方法が必要です。アプリを起動し、ユーザーと同じように機能を使い、証拠を記録します。このスキルは、リポジトリに合わせてプロジェクト内スキル（<skills>/verify-<app>/）を生成します。<skills> は、ハーネスのプロジェクトスキルフォルダーです。Cursor では .cursor/skills/、Claude Code では .claude/skills/、Pi では .pi/skills/、Codex、OpenCode などでは .agents/skills/ です。リポジトリですでにこれらのいずれかにスキルを保存している場合は、そのフォルダーを使ってください。生成結果は人間ではなく、次のエージェントに向けて作成してください。アプリを見たことがないエージェントが、作業の途中で初めて読むことになります。

1. ユーザーではなくリポジトリに尋ねる

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

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

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

2. スキルを生成する

<skills>/verify-<app>/SKILL.md を作成します。YAML フロントマター（name: verify-<app> と、アプリ名、対象のサーフェス、どのような場合に使うべきかを示す description を含めます。フロントマターがないとスキルは登録されません）を記述し、以下のセクションを設けます。それぞれ、インタビューで実際に確認された内容に基づいて記述し、プレースホルダーを残さないでください。

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

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

<skills>/verify-<app>/features/README.md と、特定できるユーザー向け機能ごとのファイルを作成します（ルート、コマンド、メニュー、ドキュメントをもとに、まずは上位 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 を案内します。ユーザーから求められた場合にのみ、実施頻度を提案してください。