create-verification-skill

検証スキルを作成する

本格的なプロジェクトには、実際のアプリを操作して動作を確認するためのスクリプト化された方法が必要です。アプリを起動し、ユーザーと同じように機能を操作して、証拠を記録します。このスキルは、リポジトリに合わせたプロジェクトローカルのスキル（.agents/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. スキルを生成する

.agents/skills/verify-<app>/SKILL.md を作成し、使用中の CLI がスキルを検出するディレクトリ（npx skills がインストール時に管理するディレクトリ）にスキルディレクトリをリンクして、すべての CLI から見つけられるようにします。YAML フロントマター（name: verify-<app> と、アプリ名、対象サーフェス、どのようなときに使うべきかを明記した description）を使い、以下のセクションを設けます。各セクションは、インタビューで実際に判明した内容に基づいて記述し、プレースホルダーを残さないでください。フロントマターがないと、スキルは登録されません。

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

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

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

UI 機能では、各要素に関係する状態を Sub-features に列挙します。空、読み込み中、エラー、データあり、一部データ、オーバーフロー、0件、1件、複数件、長文などを検討します。該当する各状態について、到達方法と、操作手順における観測可能な合格条件を記載します。確認した場合はエビデンスを記録するか、未確認であることを明記します。その機能で起こり得ない状態は省略します。

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

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

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

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