Browser Max Automation Skill

Browser Max Automation

Browser automation via Playwright MCP, existing-browser CDP, and direct CDP helpers.

When to Use

ブラウザ自動化、UI 確認、フォーム操作、スクリーンショット取得
MCP で手順を確立してから Python で一括実行したいとき
既存ブラウザのログイン状態を CDP 経由で使いたいとき
Playwright MCP / connect_over_cdp() が不安定で、raw CDP WebSocket に切り替えたいとき
モーダルや file chooser など、通常クリックが壊れやすい UI を扱うとき

Not the Best Fit

API / CLI を先に検討: 公式 API（YouTube Data API、Microsoft Graph、GitHub API 等）や CLI で read/write が完結するならそちらを優先し、UI が脆い兆候（native file chooser / shadow DOM / 多段ウィザード / レンダラーを止める modal）で固執せず切り替える（例: YouTube Studio UI → captions.insert）
API / CLI だけで完結するなら、該当 domain skill / script を使う
PowerPoint / Loop / Dynamics 365 の expense entry 画面など専用 skill がある UI は、該当 skill の操作ルールを優先する
認証情報、秘密情報、MFA 応答をチャットで受け取らない。必要な入力はブラウザ上でユーザーに処理してもらう
例外: 対象サイトが passkey / FIDO2 / WebAuthn 対応なら、CDP 仮想認証機で完全無人化できる。優先順位は passkey (仮想認証機) > メール OTP > SMS > 物理キー / 生体。詳細は references/instructions/webauthn-virtual-authenticator.md を参照する

Choose Mode First

| モード | 向く場面 | メリット | 注意点 | | ------------------ | ------------------------------------------------------ | ------------------------------ | -------------------------- | | 新規ブラウザ | まず安定して動かしたい | 設定が簡単 | 既存ログイン状態は使えない | | 既存ブラウザ (CDP) | 普段のブラウザ状態をそのまま使いたい | ログイン済み状態を再利用できる | デバッグモード起動が必要 | | 直接 CDP WebSocket | Playwright CDP が不安定、または MCP と競合させたくない | 低レベル操作で安定しやすい | CDP コマンドを自前管理する |

既存ブラウザ CDP の起動、profile 確認、port drift、認証 URL encode は references/instructions/cdp-existing-browser.md を参照する。直接 WebSocket CDP の起動フラグ、websocket-client 接続、SPA hash navigation、virtual scroll 操作は references/instructions/cdp-direct-websocket.instructions.md を参照する。

Quick Reference

| Command | Purpose | | ------------------------- | ----------------- | | browser_navigate | URL を開く | | browser_snapshot | 要素 ref を取る | | browser_click | ref でクリック | | browser_type | テキスト入力 | | browser_take_screenshot | 画面確認 | | browser_wait_for | 表示待機 | | browser_evaluate | DOM 直接操作 | | browser_file_upload | file chooser 対応 |

Core Loop

1. browser_navigate(url)
2. browser_snapshot で ref を取る
3. browser_click / browser_type で操作する
4. browser_snapshot or screenshot で結果確認する

UI verification では、操作前に期待する state と確認方法を決める。成功 toast やボタン押下だけを成功判定にせず、DOM、URL、永続化された一覧行、API の read 結果、または screenshot / trace などの証跡で確認する。

API と DOM の状態が一時的にずれるケースがある。API が stale / capture failure を返しても、画面上の cell / row の aria-label や status text が進展した状態を示しているなら DOM も正本候補として扱う。API 単独で「未完了」と断定しない。

Decision Patterns

| Situation | Action | | --- | --- | | Flow or selectors are still unknown | Use MCP interactively | | Flow is stable and must run for many items | Switch to a CLI/API helper | | Snapshot returns a ref | Use normal click/type | | Element is visible but has no ref | Confirm visually, then use evaluate or the relevant UI fallback | | Element is not visible | Wait or reload before forcing interaction | | Read-only tabular extraction | Keep navigation evidence, then return compact JSON from DOM evaluation |

unsaved editor / draft タブを壊さない

未保存 form を持つ editor / SPA タブに別 URL を踏ませると beforeunload dialog で upload や遷移が崩れる。既存タブは再利用し、新規作業は別タブで開く。dialog.accept() / page.reload() / API トリガー目的の reload で dirty を踏み越さない。詳細と Qiita / CMS 例は references/instructions/unsaved-form-tabs.md を参照する。

Azure Portal iframe / OOPIF / trusted event の注意は references/instructions/azure-portal.md を参照する。 Angular Material / mat-select / cdk-overlay / disabled save の注意は references/instructions/angular-material.md を参照する。

iframe、force click、file chooser、hidden input、evaluate+fetchは UI Fallbacks を参照する。force: true は要素の実在と可視性を確認した後の最終手段とする。

Safety Rules

CDP 排他制御

MCP Playwright と Python スクリプトは 同じ CDP ポートへ同時接続しない。とくに Python 側も connect_over_cdp() を使う場合、MCP と Playwright セッションが二重になり、ページ操作が競合して「遷移先が想定外」「フォーム送信が効かない」等の不定失敗が起きる。

| ルール | 内容 | | ------------- | ------------------------------------------------------------------------------------------------------------------ | | 同時接続禁止 | MCP と Python を同じ CDP に同時接続しない | | MCP 切断優先 | Python 実行前に browser_close で MCP ページを解放 してから実行する | | プロセス確認 | 実行前にゾンビ Python を確認する | | 標準フロー | MCP で手順確立 → browser_close → Python 単独実行 → 完了後に MCP 再接続して検証 | | raw WebSocket | websocket-client 等で CDP WebSocket に直接繋ぐスクリプトは MCP と共存可能（Playwright セッションを張らないため） |

raw WebSocket を使う場合は、CDP command id で応答をフィルタし、Runtime.enable / Page.enable など必要な domain を先に有効化する。詳細は references/instructions/cdp-direct-websocket.instructions.md を参照する。

CDP recovery、blocking dialog、context/page selection は references/instructions/cdp-recovery-and-context.md を参照する。

破綻しやすい場面

modal overlay が snapshot に出ない
file chooser が残って後続操作を塞ぐ
CDP 二重接続で入力先が混線する
CDP の別 context/page を使い、未ログイン画面や別アカウントを操作してしまう
「見えているがクリックできない」状態を無理に通常 click で押し切る

Subprocess + CDP Stability (Windows)

Windows の PIPE デッドロック、VS Code terminal の SIGINT、JSON status artifact、taskkill tree kill は references/instructions/windows-subprocess-cdp.md を参照する。

Reference Map

Done Criteria

MCP または CDP 設定が完了している
対象ページまで安定して到達できる
目的の操作が完了している
成功判定を toast だけに頼らず、DOM / URL / API read / screenshot / status artifact のいずれかで確認している
modal / file chooser / iframe / CDP context のどこで詰まるか説明できる
一括処理が必要なら MCP から CLI / API helper へ切り替える判断ができている

Agent Skills: Browser Max Automation

Install this agent skill to your local

Skill Files