create-verification-skill

検証スキルを作成する

本格的なプロジェクトには、実際のアプリを操作して動作を確かめるスクリプトが必要です。アプリを起動し、ユーザーと同じように機能を試し、その証拠を記録します。このスキルは、リポジトリに合わせてプロジェクト内のスキル（.cursor/skills/verify-<app>/）を生成します。生成した内容は人間向けではなく、次のエージェント向けに作成します。アプリを見たことがないエージェントが、タスクの途中で初めて読むことになります。

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

コードベースから次の点を確認し、観察できないことだけをユーザーに尋ねます。

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

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

2. スキルを生成する

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

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

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

.cursor/skills/verify-<app>/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 です。このマップは、リポジトリで維持管理する検証の情報源です。マップに別の入口が記載されている場合、便利な入口を 1 つ操作しただけの証明では不十分です。

4. 引き渡す前に生成したスキルを検証する

生成したスキルの手順を最初から最後まで 1 回実行します。起動、診断、マップにある機能の操作（1 つで十分です。マップがあるため、後続の実行で残りを検証できます）、証拠の取得、クリーンアップを行います。クリーンアップ後、指定した場所に証拠が残っていることを確認してください。証拠を消してしまうクリーンアップは、この手順を満たしません。失敗した場合は修正し、失敗した試行の後も、生成したクリーンアップを実行して、プロセスやポートを残さないようにしてください。実行されていない生成スキルは成果物ではなく、下書きです。

5. メンテナンスの流れを案内する

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