show-and-tell(ショー&テル) は何をしますか?
あなたとユーザーが共有する Chrome for Testing ウィンドウです。あなたはページ上の要素を指し示し、ユーザーは show-and-tell サイドパネル(注釈、録画、メッセージ)から応答できます。どちらの方向にもツアーは不要です。ガイドツアーや動画はオプションの追加機能です。パネルはブラウザのUIであり、ページのスクリーンショットには含まれません。
<skill> はこのスキルのディレクトリ(このSKILL.mdが置かれているフォルダ)を指します。コマンドは任意のシェルで動作します。
構成要素
- ブラウザ: 独自プロファイルを使用する Chrome for Testing、CDP
127.0.0.1:9334、拡張機能プリロード済み。start_browserで起動(べき等)し、パネルを開きます。セッションを越えて存続します。 - show-and-tell MCP:
start_browser、status、highlight、clear_highlights、hide_overlays、get_queue、wait_for_action、request_demo、set_step、load_tour、goto_step、end_tour、record_tour、stop_recording。 各ツールはCLIとしても利用可能です:node "<skill>/bridge" <start|status|highlight <css> [--label t] [--gesture g] [--direction d] [--to css] [--url u] [--style s] [--keep]|clear|hide|show|queue [--recent]|wait|cancel|request <prompt>| step <label>|tour <file>|goto <n>|end|record <file> [--name n] [--size s]|record-stop|record-cancel> browser_*ツール: 同じMCP(Playwright MCP、このブラウザに接続)のツールで、highlightだけでは不十分な場合にページを操作します。browser_snapshot、browser_click、browser_type、browser_evaluate、browser_navigate… これらは必要に応じてブラウザを起動し、アプリタブ上で動作し、パネルでは動作しません。 ホストに別途プレーンな Playwright サーバーがある場合、それはユーザーに見えないあなた専用のブラウザです。ユーザーに見せてはいけない作業にのみ使用してください。
ユーザーが見ている環境での作業
ユーザーは共有ブラウザを見ています。パネルには各 browser_* 呼び出し(「クリック中…」「ページ経由でデータをリクエスト中…」)が表示されます。追跡可能に保つには:
- 何かを表示または再現する場合:可視UI(ナビゲート、クリック、入力)を使用して、ページにそれが表示されるようにします。
- 大量のデータ(ログ、リスト、JSON)を読み取る場合:
browser_evaluate内でfetchを使ってアプリ独自のAPIを呼び出すのは問題ありません。ユーザーのセッションを使用しますが、画面には何も変化しません。事前にチャットで伝えてください(「GrafanaのAPIを使ってあなたのタブ内のログを読み取っています」)。 - こうしたリクエストは小さく保ちます(短い時間範囲、
limit):約1分以上かかる呼び出しはMCPクライアントによって中断されます。同じクエリを再試行するのではなく、長い範囲を分割してください。
ガードレール:許可ホスト
共有ブラウザにはユーザーのログイン情報が保持されているため、ここでのすべてのツール(ポインティング、ツアー、動画、browser_*)は許可されたホストでのみ動作します。このマシンは常に許可されます:localhost、ループバックアドレス、およびホストファイルがループバックにマッピングする名前。他のホスト(別のネットワーク上のプライベートホストであっても)は、最初に使用しようとしたときにサイドパネルで確認が行われます(「いいえ」「このセッション」「常に」)。呼び出しは回答を最大2分間待機します。
許可されていません:ユーザーが許可しませんでした…:それを尊重し、再試行したり回避策を探したりしないでください。…が応答しませんでした…:パネルが確認を求めていることを1行でユーザーに伝え、その後1回だけ再試行してください。extension/config.jsonやconfig.local.jsonを自分で編集しないでください。ホストの許可はユーザーのみが行います。
ウォッチャー:ユーザーの声を聞く
ユーザーはいつでも送信できます。あなたはウォッチャー(バックグラウンドシェルジョブ)を通じてそれを受け取ります。
start_browser、status、およびブラウザを操作するすべてのツールはwatcherを返します。runningが false の場合、watcher.commandをバックグラウンドジョブ(シェルツール、backgroundオプション)としてすぐに開始し、その完了を待たないでください。- 完了時に
{"actions": [...]}を返します。それを処理し(次のセクション)、その後ウォッチャーを再起動します。timeoutまたはcancelledでアクションがない場合:ウォッチャーを再起動し、何も言わないでください。 - チャット中はウォッチャーを実行し続け、チャットメッセージに応答するためにウォッチャーをキャンセルしないでください。
- パネルは最後にブラウザを操作したセッションに送信し、「<セッション> がリッスンしています」と表示します。
- この環境ではバックグラウンドジョブは使用しません:ユーザーが何かを送信、マーク、録画したと言った場合は、
get_queue(recent: trueを指定すると過去1時間の配信済みアイテムも返します)を呼び出してください。
ユーザーに何かを示す
highlight({ selector, text?, label?, gesture?, direction?, to?, url?, style?, keep? }):
urlを指定すると、まずそのページがアプリタブで開かれます。Playwrightは不要です。found: falseの場合は、その前に確認してください。label:短い吹き出し。style:outline(デフォルト)、spotlight(他の部分を暗くする)、none(枠なし)。gestureは要素上でイラストをループ表示します。実際に実行されるわけではありません。タッチ:tap、double-tap、long-press、swipe、pinch。マウス:click、double-click、right-click、hover、drag、scroll。direction:left/right/up/down(swipe、drag、scroll)、in/out(pinch)。to:スワイプ・ドラッグ終了点のCSSセレクタ。keep: trueを指定すると現在のハイライトに追加されます。指定しないと置き換えられます。clear_highlightsで削除します。- 安定したセレクタ(id、
data-testid、aria)とtextを優先してください。チャットで1〜3文で説明してください。
ユーザーが送信するもの
actions 内の各アイテムには type(ツアー実行中は step も)があります:
question:メッセージ(text)。チャットで回答してください。annotation:ユーザーがページにマーク(「注釈」:クリックで要素をマーク、ドラッグで描画)し、textを記入しました。あなただけが見られるインライン画像が返されます。ユーザーの番号付き・色付きのマークと注釈、および各マークが指す要素の周りに点線の枠(1a、1b…とラベル付け)が表示されます。annotations[]は凡例です:n、kind(element/rect/arrow/pen)、color、rect、矢印のfrom/to、note、elements[](label、selectors、tag、text、rect)。座標はドキュメント座標です。imageAreaは画像が示す範囲です。マークを参照するときは、番号や色と要素テキストを使用し、1aのようなラベルは使わないでください。imagePathはユーザー自身のバージョンです。recording:ユーザーが何かを実演しました(「録画」、またはあなたのrequest_demoに応じて。requestIdとpromptが含まれます)。recording.stepsは Chrome DevTools Recorder の形式に従います(navigate、click(button: "secondary"とmodifiersあり)、doubleClick、change、keyDown、scroll)に加えてlongPress、swipe、urlChange。要素ステップにはselectors、tag、textが含まれます。textはユーザーのコメントです。demoDeclined:ユーザーがリクエストを拒否しました。- ツアーと動画のイベント:
next/back、agentStep、stepError、tourEnd、videoReady、videoError、videoDiscarded(以下のセクション)。
request_demo({ prompt }) はユーザーに何かを示すよう依頼します。パネルが録画を開始します。
ガイドツアー
- チャットで計画します:タイトルと各ステップが示す内容、1ステップにつき1つのアイデア。
- スクリプト
{ steps: [{ title, explanation, url?, actions?, highlights?, agent? }] }:explanation:2〜5文。パネルに表示されます。url:最初にナビゲートします。「戻る」は最も近い前のurlがあるステップから再生されるため、ページ状態を変更する各ステップには到達可能なurlを指定してください。actions:{click|fill|waitFor|hover|doubleClick|rightClick|longPress|swipe|drag|scroll: css, text?, value?, to?, direction?, ms?}、{scrollBy: px, in?: css}、{press: key, on?: css}、{wait: ms}。highlights:highlight()と同じ形式。最初の1つは置き換え、残りは追加されます。agent: trueは手動で行う必要があるステップのみに指定します:実行、set_step("n/N – title")、ハイライト、説明、そして「次へ」が来たらgoto_step(n+1)を実行します。 セレクタは事前に確認してください(browser_evaluate)。存在しないセレクタはstepErrorになります。
- 開始:
start_browser(ウォッチャーを開始)、bridge.panelOpenを確認し、load_tour({ tour })を実行してから、ツアーがパネルで実行されていることを1行でユーザーに伝えます。 - 応答:
stepError→ ステップを修正し、start: stepを指定してload_tour。tourEnd→end_tourと短いサマリーを表示。ツアー中の質問やマークは現在のstepに関連します。
コード変更のデモ
- 範囲:未コミットの変更(
git diff HEAD)、またはそのブランチとベースブランチの差分。不明な場合は質問してください。 - 変更された各ファイルを、その影響が表示される画面と要素にマッピングします。視覚的な影響がない変更は、最後のサマリーステップにまとめます。
- アプリ:アクセスできない場合、プロジェクトのスクリプトから開発サーバーをバックグラウンドジョブとして起動します。 その後、可視変更ごとに1ステップのツアーを、アプリの自然な順序で作成します。
レビュー動画
record_tour({ tour, name?, size?, pace?, captions?, cards?, zoom?, hidpi?, out? }) はスクリプト化されたツアーを自動再生し、タブをMP4として録画します。キャプション、チャプターラベル、プログレスバー、イントロ/セクション/アウトロカード、すべてのアクションに対する描画カーソルまたは指、.vtt ファイル、チャプターリストが含まれます。すぐに戻り、その後ウォッチャーが videoReady { path, vtt, chapters, durationMs, … } または videoError { step, error } を受け取ります。動画ツアーを作成する前に references/video.md を読んでください。
証拠スクリーンショット
プレーンなページを表示するスクリーンショットの前に hide_overlays(true) を呼び出し、その後 hide_overlays(false) で元に戻します。
トラブルシューティング
extensionConnected: false:start_browserを再度実行します。拡張機能は約15秒以内に再接続し、その間にユーザーが送信した内容を再生します。bridge not running:MCPが接続されていません。CLI(start、wait)は単独で動作します。browser_*呼び出しでブラウザが閉じていると言われた場合:自動的に1回再接続を試みます。それでも失敗する場合はstart_browserを実行して再試行してください。- 1つのブラウザは同時に1つのツアーまたは動画のみを処理します。
statusが自分が設定していないステップを表示している場合、別のセッションが使用中です。最初にユーザーに確認してください。 - Chrome for Testing がない場合:
npx playwright install chromiumを実行するか、DEMO_BROWSER_PATHを設定してください。