chrome-automation

スキル：Chrome の自動化（agent-browser）

agent-browser CLI を使って、ユーザーが実際に使用している Chrome セッションでブラウザータスクを自動化します。

前提条件：agent-browser がインストールされ、Chrome でリモートデバッグが有効になっている必要があります。不明な場合は、references/agent-browser-setup.md を参照してください。

---

基本原則：ユーザーが使用中の Chrome を再利用する

このスキルは、ユーザーが実際に使用しているブラウザーである単一の Chrome プロセス上で動作します。セッション管理や別のプロファイル、新しい Playwright ブラウザーの起動はありません。

まずタブを一覧表示する

新しいページを開く前に、必ず最初に既存のタブを一覧表示してください。

agent-browser --auto-connect tab list

開いているすべてのタブが、インデックス番号、タイトル、URL とともに表示されます。必要なページがすでに開いているか確認してください。

• 対象のページがすでに開いている場合 → 新しいページを開くのではなく、そのタブに直接切り替えます。ユーザーはすでにログインしており、ページも適切な状態にあるため、そのページを開いている可能性があります。

  agent-browser --auto-connect tab <index>
  

• 対象のページが開いていない場合 → 現在のタブまたは新しいタブで開きます。

  agent-browser --auto-connect open <url>
  

これが重要な理由

• ユーザーの Chrome には、Cookie、ログインセッション、ブラウザーの状態が保存されています。
• すでに開いているページを開き直すと時間が無駄になり、ログイン状態が失われる可能性もあります。
• 多くのマーケティングプラットフォーム（ソーシャルメディアのダッシュボード、広告管理ツール、CMS ツールなど）ではログインが必要です。すでにログインしているタブを再利用すれば、再認証を避けられます。

---

接続

ユーザーが実行中の Chrome インスタンスに接続するには、必ず --auto-connect を使用してください。

agent-browser --auto-connect <command>

これにより、リモートデバッグが有効な Chrome が自動検出されます。接続に失敗した場合は、リモートデバッグを有効にする手順をユーザーに案内してください（references/agent-browser-setup.md を参照）。

Chrome 144 以降の WebSocket のみのフォールバック

Chrome 144 以降では、chrome://inspect/#remote-debugging からリモートデバッグを WebSocket のみのエンドポイントとして公開できます。この状態ではページに Server running at: 127.0.0.1:9222 と表示されますが、従来の検出 URL は 404 を返します。

curl http://127.0.0.1:9222/json/version
curl http://127.0.0.1:9222/json/list

0.27.x などの古い agent-browser バージョンでは、Chrome が準備できていても No running Chrome instance found というエラーが発生する場合があります。まずはグローバルインストールを変更せずに、最新の CLI を試してください。

npx -y agent-browser@latest connect "ws://127.0.0.1:9222/devtools/browser"
npx -y agent-browser@latest tab list

これが動作する場合は、残りのブラウザータスクでも npx -y agent-browser@latest <command> を使用してください。エンジンに関する警告やインストールエラーが発生する場合は、Node を 24 以降にアップグレードするか、最新の agent-browser をグローバルにインストールしてください。

---

一般的なワークフロー

1. ページに移動して操作する

# List tabs to find existing pages
agent-browser --auto-connect tab list

# Switch to an existing tab (if found)
agent-browser --auto-connect tab <index>

# Or open a new page
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect wait --load networkidle

# Take a snapshot to see interactive elements
agent-browser --auto-connect snapshot -i

# Click, fill, etc.
agent-browser --auto-connect click @e3
agent-browser --auto-connect fill @e5 "some text"

2. ページからデータを抽出する

# Get all text content
agent-browser --auto-connect get text body

# Take a screenshot for visual inspection
agent-browser --auto-connect screenshot

# Execute JavaScript for structured data
agent-browser --auto-connect eval "JSON.stringify(document.querySelectorAll('table tr').length)"

3. Chrome DevTools の記録を再生する

ユーザーから、Chrome DevTools Recorder でエクスポートした記録（JSON、Puppeteer JS、または @puppeteer/replay JS 形式）が提供される場合があります。詳しくは、以下の記録の再生を参照してください。

操作手順ガイド

スナップショットの取得

-i を付けた snapshot を使うと、参照 ID（@e1、@e2 など）付きの対話可能な要素がすべて表示されます。

agent-browser --auto-connect snapshot -i

出力には、各対話可能な要素のロール、テキスト、参照 ID が表示されます。以降の操作では、これらの参照 ID を使用してください。

ステップの種類とコマンドの対応

操作	コマンド
ページに移動	agent-browser --auto-connect open <url>（必要に応じて wait --load networkidle を使用します。ただし Reddit のように networkidle に到達しないサイトもあります。open ですでにページタイトルが表示されている場合は省略してください）
クリック	snapshot -i → 参照 ID を探す → click @eN
標準の入力欄に入力	click @eN → fill @eN "text"
リッチテキストエディターに入力	click @eN → keyboard inserttext "text"
キーを押す	press <key>（Enter、Tab、Escape など）
スクロール	scroll down <amount> または scroll up <amount>
要素を待つ	wait @eN または wait "<css-selector>"
スクリーンショット	screenshot または screenshot --annotate
ページのテキストを取得	get text body
現在の URL を取得	get url
JavaScript を実行	eval <js>

入力タイプの見分け方

• 標準の入力欄／テキストエリア → fill を使用します
• Contenteditable div／リッチテキストエディター（LinkedIn のメッセージボックス、Gmail の作成画面、Slack、CMS エディター）→ 先にクリックしてフォーカスし、その後 keyboard inserttext を使用します

Ref のライフサイクル

Refs（@e1、@e2 など）はページが変わると無効になります。次の操作の後は、必ずスナップショットを再取得してください。

• ナビゲーションを引き起こすリンクやボタンをクリックしたとき
• フォームを送信したとき
• 動的なコンテンツの読み込み（AJAX、SPA ナビゲーション）を発生させたとき

確認

重要な操作を行うたびに、結果を確認してください。

agent-browser --auto-connect snapshot -i   # check interactive state
agent-browser --auto-connect screenshot     # visual verification

---

録画の再生

対応フォーマット

1. JSON（推奨）— 構造化されており、順次読み取れます。

   # Count steps
   jq '.steps | length' recording.json
   
   # Read first 5 steps
   jq '.steps[0:5]' recording.json
   

2. @puppeteer/replay JS（import { createRunner }）

3. Puppeteer JS（require('puppeteer')、page.goto、Locator.race）

再生方法

1. 録画を解析する — 操作を行う前に、全体の意図を把握します。録画の内容を要約します。
2. 最初にタブを一覧表示する — 対象のページがすでに開いているか確認します。
3. ナビゲーションする — 可能な場合は既存のタブを再利用しながら、navigate ステップを実行します。
4. 各操作ステップで：
   • スナップショット（snapshot -i）を取得し、現在の操作可能な要素を確認します。
   • 録画の aria/... セレクターをスナップショットと照合します。
   • 該当するものがない場合は、text/...、次に CSS クラスのヒント、最後にスクリーンショットを試します。
   • ember ID、数値 ID、正確な XPath に依存しないでください — これらはページの読み込みごとに変わります。
5. 各ステップの後に確認する — スナップショットまたはスクリーンショットで確認します。

---

iframe が多いサイト

snapshot -i はメインフレームのみを対象とし、iframe の内部にはアクセスできません。LinkedIn、Gmail、埋め込みエディターなどのサイトでは、iframe 内にコンテンツが表示されます。

iframe の問題を検出する

• snapshot -i の結果が予想外に短い、または空である
• 録画で参照されている要素がスナップショットの出力に表示されない
• get text body のコンテンツがスクリーンショットの表示と一致しない

回避策

1. eval を使用して iframe のコンテンツにアクセスする：

   agent-browser --auto-connect eval --stdin <<'EVALEOF'
   const frame = document.querySelector('iframe[data-testid="interop-iframe"]');
   const doc = frame.contentDocument;
   const btn = doc.querySelector('button[aria-label="Send"]');
   btn.click();
   EVALEOF
   

   注：同一オリジンの iframe でのみ機能します。

2. keyboard を使用してブラインド入力する：iframe 要素にフォーカスがある場合、keyboard inserttext "..." を使用すると、フレーム境界に関係なくテキストを送信できます。

3. get text body を使用して、iframe を含むページ全体のコンテンツを読み取ります。

4. スナップショットの信頼性が低い場合は、視覚的な確認に screenshot を使用します。

ユーザーに確認するタイミング

同じステップで回避策を 2 回試しても失敗する場合は、いったん停止して次の内容を説明します。

• ページでは iframe が使用されており、スナップショットからはアクセスできないこと
• 必要な要素と、予想していた内容
• そのステップを手動で実行してから続行するよう、ユーザーに依頼すること

---

予期しない状況への対応

自動で対応する（停止しない）：

• ポップアップやバナー → 閉じます（find text "Dismiss" click または find text "Close" click）
• Cookie 同意ダイアログ → 同意するか、閉じます
• ツールチップのオーバーレイ → 先に閉じます
• 要素がスナップショットにない → find text "..." click を試すか、scroll down 300 でスクロールして表示します

いったん停止してユーザーに確認する：

• ログイン／認証が必要
• CAPTCHA が表示される
• ページ構成が想定とまったく異なる
• 破壊的な操作（データの削除、実際のコンテンツの送信など）を行う直前 — 先に確認します
• 同じステップで 2 回以上試しても進めない
• iframe の回避策をすべて試しても失敗する

停止する際は、現在のステップ、予想していた内容、実際に表示されている内容を明確に説明します。

主要コマンドのリファレンス

コマンド	説明
tab list	開いているすべてのタブのインデックス、タイトル、URLを一覧表示します
tab <index>	インデックスを指定して既存のタブに切り替えます
tab new	新しい空のタブを開きます
tab close	現在のタブを閉じます
open <url>	URLに移動します
snapshot -i	参照ID付きで操作可能な要素を一覧表示します
click @eN	参照IDで要素をクリックします
fill @eN "text"	標準の入力欄／テキストエリアをクリアして入力します
type @eN "text"	クリアせずに入力します
keyboard inserttext "text"	テキストを挿入します（contenteditableに最適です）
press <key>	キーを押します
scroll down/up <amount>	ページをピクセル単位でスクロールします
wait @eN	要素が表示されるまで待機します
wait --load networkidle	ネットワークが落ち着くまで待機します
wait <ms>	指定した時間だけ待機します
screenshot [path]	スクリーンショットを撮影します
screenshot --annotate	番号付きラベルを付けてスクリーンショットを撮影します
eval <js>	ページ内でJavaScriptを実行します
get text body	すべてのテキストコンテンツを取得します
get url	現在のURLを取得します
set viewport <w> <h>	ビューポートのサイズを設定します
find text "..." click	テキストを意味的に検索してクリックします
close	ブラウザーセッションを終了します

---

既知の制限事項

1. Iframeの不可視性：snapshot -iではiframe内を確認できません。Iframeを多用するサイトを参照してください。
2. find textの厳密モード：複数の要素が一致すると失敗します。代わりに snapshot -iを使って、対象の参照IDを特定してください。
3. fillとcontenteditable：fillは<input>と<textarea>でのみ動作します。リッチテキストエディターではkeyboard inserttextを使用してください。
4. evalはメインフレームのみ：iframeのコンテンツを操作するには、document.querySelector('iframe').contentDocument...をたどってください。

---

複数プラットフォームでの操作

ユーザーが複数のプラットフォームにまたがる操作（例：「この記事をDev.to、LinkedIn、Xに投稿して」）を依頼した場合、1回の会話ですべてのプラットフォームを操作しようとしないでください。代わりに、プラットフォームごとに1つずつ、順次サブエージェント／ワーカーを起動してください。このスキルの選択は、この複数プラットフォームのワークフローでサブエージェント／ワーカーを使用する明示的な許可です。

サブエージェントを使用する理由

プラットフォームごとの操作では、約25〜40Kトークンを消費します（リファレンスファイル＋スナップショット＋操作）。1つのコンテキストで3〜5個のプラットフォームを扱うと、コンテキスト上限に達し、後半のプラットフォームでの精度が低下するおそれがあります。各サブエージェント／ワーカーには、新しいコンテキストウィンドウが割り当てられます。

実行方法

1. コンテンツを準備する — 投稿文、タイトル、タグ、およびプラットフォーム固有の調整内容をユーザーに確認します。
2. プラットフォームごとに、以下を含むプロンプトを指定してサブエージェント／ワーカーを起動します。
   • 公開するコンテンツ全体
   • 該当するリファレンスファイルを読む指示（例：Read /path/to/skills/chrome-automation/references/x.md）
   • コマンドのリファレンスとしてagent-browserスキルファイルを読む指示
   • 具体的なタスク（投稿、コメント、返信など）
   • プラットフォーム固有の指示（例：「LinkedInではこれらのハッシュタグを使う」）
3. サブエージェント／ワーカーは順番に実行します（一度に1つ）。すべてのサブエージェント／ワーカーが--auto-connectを通じて同じChromeブラウザーを共有するためです。並行して実行すると、タブの競合が発生します。
4. 各サブエージェント／ワーカーの完了後、次のサブエージェント／ワーカーを起動する前に、結果をユーザーに報告します。

サブエージェントのプロンプトテンプレート

You are automating a browser task on [PLATFORM].

First, read these files for context:
- /absolute/path/to/skills/chrome-automation/references/[platform].md
- The installed agent-browser skill file, if available (agent-browser command reference)

Then connect to the user's Chrome browser using `agent-browser --auto-connect` and perform the following task:

[TASK DESCRIPTION]

Content to publish:
[CONTENT]

Important:
- Always list tabs first (`tab list`) and reuse existing logged-in tabs
- Re-snapshot after every navigation or action
- Confirm with the user before submitting/publishing (destructive action)
- If login is required or a CAPTCHA appears, stop and explain

サブエージェントを使用しない場合

• 単一のプラットフォーム — 現在の会話で直接実行してください。
• 読み取り専用のタスク（閲覧、検索、データ抽出）— コンテキストの使用量が少ないため、1つの会話で2〜3個のプラットフォームに対応できます。

---

プラットフォーム別のリファレンス

特定のプラットフォームでタスクを自動化する場合は、ページ構造の詳細、一般的な操作、既知の注意点について、該当するリファレンスドキュメントを参照してください。

プラットフォーム	リファレンス	主な注意点
Reddit	references/reddit.md	独自のfaceplate-*コンポーネントを使用します。networkidleに到達しません。コメント用テキストボックスにラベルがありません。要素が重複しているため、find textは失敗します。
X (Twitter)	references/x.md	openはタイムアウトすることがよくあります（既存のタブを再利用するにはtab listを使用してください）。投稿の詳細を表示するにはタイムスタンプをクリックします（ユーザー名ではありません）。DraftJSのcontenteditable入力欄（data-testid="tweetTextarea_0"）を使用します。networkidleは避けてください。
LinkedIn	references/linkedin.md	Ember.jsのSPAです。Enterキーでコメントが送信されるため、改行にはShift+Enterを使用してください。コメント欄と投稿作成欄で同じラベルが使われています。networkidleは避けてください。メッセージングオーバーレイがコンテンツをブロックする場合があります。
Dev.to	references/devto.md	高速なサーバーサイドレンダリングHTML（Forem/Rails）です。コメント／投稿には標準の<textarea>（Markdown）を使用します。リアクションは5種類です。Algoliaを利用した検索機能があります。networkidleは通常どおり機能します。
Hacker News	references/hackernews.md	最小限のプレーンHTMLです。すべてのフォームフィールドにラベルがありません。link "reply"をクリックすると別ページに移動します。networkidleはすぐに機能します。投稿／コメントにはレート制限があります。

---

インストールとChromeのセットアップ手順については、references/agent-browser-setup.mdを参照してください。