Communitygithub.com

show-and-tell(ショー&テル)

ユーザーと共有するブラウザ上で、双方向のポインティングチャンネルを提供します。ハイライト、ラベル、タップ/スワイプ/ドラッグなどのジェスチャー図示を表示し、ユーザーはサイドパネルから注釈や録画、メッセージを送信できます。さらに、ガイド付きツアーやレビュー動画(MP4、キャプション、チャプター、カード付き)もサポートします。

show-and-tell(ショー&テル) とは?

show-and-tellは、AIエージェント(Claude Code、Cursor、Codexなど)と人間のユーザーとの間で、共有ブラウザを介した視覚的なコミュニケーションを実現するスキルです。エージェントはページ上の要素をハイライト、ラベル、ジェスチャーアニメーションで指し示し、ユーザーは専用のサイドパネルから注釈(マーク+テキスト)、操作の録画、メッセージを送信できます。これにより、「ここをクリックして」「これを見て」「この変更を確認して」といった指示を、曖昧さなく直感的に行えます。さらに、ガイド付きツアー(Next/Backボタン付き)や、完全自動で録画されるレビュー動画(MP4、キャプション、チャプターカード付き)をオプションとして提供し、デモやコードレビュー、お客様向けレビュー動画の作成に活用できます。ブラウザはChrome for Testing上で動作し、CDPとMCPサーバーを介して制御されます。エージェントは`highlight`、`get_queue`、`load_tour`、`record_tour`などのツールと、Playwright MCP(`browser_snapshot`、`browser_click`など)を組み合わせて使用します。ユーザーの操作はバックグラウンドのウォッチャーが常時監視し、注釈や質問が届いたら即座にエージェントが応答します。

対応✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/Knyrps/agent-skills/tree/main/skills/show-and-tell

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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ステップにつき1つのアイデア。
  2. スクリプト { 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 になります。
  3. 開始:start_browser(ウォッチャーを開始)、bridge.panelOpen を確認し、load_tour({ tour }) を実行してから、ツアーがパネルで実行されていることを1行でユーザーに伝えます。
  4. 応答:stepError → ステップを修正し、start: step を指定して load_tour。tourEnd → end_tour と短いサマリーを表示。ツアー中の質問やマークは現在の step に関連します。

コード変更のデモ

  1. 範囲:未コミットの変更(git diff HEAD)、またはそのブランチとベースブランチの差分。不明な場合は質問してください。
  2. 変更された各ファイルを、その影響が表示される画面と要素にマッピングします。視覚的な影響がない変更は、最後のサマリーステップにまとめます。
  3. アプリ:アクセスできない場合、プロジェクトのスクリプトから開発サーバーをバックグラウンドジョブとして起動します。 その後、可視変更ごとに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 を設定してください。

関連スキル