control-browser

Browser automation (built-in browser)

Use this skill for browser / web-UI tasks: opening and navigating pages, inspecting or reading rendered content, testing local apps, clicking, typing, filling, taking screenshots, and verifying visible page state.

If this skill is available in the session, treat it as required reading before browser work. Follow it before saying the browser is unavailable and before falling back to bash (curl/open), web_fetch, or any other tool for a browser task.

How it works

The browser is driven by the native browser_* tools (browser_navigate, browser_snapshot, browser_click, browser_type, browser_screenshot, browser_tabs, ...). Tools are stateless calls, but the browser tabs persist across calls for the lifetime of the session — tabs are the continuity boundary and must be recovered from current tab facts, not from memory.

Backend modes are desktop (the Electron in-app webview — the user watches the same page you control, live) and managed (a headless Playwright Chromium; the right panel shows screenshot frames). You do not pick the mode; the host reports it in browser_state events. User-facing progress should stay non-technical: describe it as "opening the browser" / "checking the page", not "Playwright", "CDP", or "webview".

Core workflow

1. Start with tabs. At the start of every logical tab operation batch, call browser_tabs with action="list" so you see all current ids, URLs, titles and the active marker. Only then match the intended tab by verified id/url/title and select it. Never choose by position or by an id remembered without validation. If no controlled tab matches, create one.
2. Prefer the reuse-aware entry. browser_navigate reuses an existing same-site controlled tab (same hostname), activates it so the user sees it, and navigates in place, instead of stacking a new tab on every navigation. Only create a new tab when the task genuinely needs a parallel independent page.
3. After every successful navigation, the tool has already waited for domcontentloaded. Do not re-navigate to the same URL; use browser_tabs/reload only when a refresh is truly needed. A direct URL must come from the user, visible page facts, or an authoritative lookup — never guess path variants or resource IDs.
4. browser_snapshot is your primary way to read and understand the page. It returns the compact ARIA tree — computed roles, accessible names, states ([checked]/[expanded]/[selected]/[disabled]), open same-origin iframes — and gives every interactive element a [ref=eN] marker. Reuse the latest relevant snapshot until it becomes stale. If the snapshot already contains the target, act from its facts directly; do not write browser_evaluate code to rediscover related elements, enumerate inputs, dump HTML, or probe guessed selectors.
5. Act through snapshot refs. Pass [ref=eN] values to browser_click / browser_type. Never guess a ref, label, accessible name, placeholder, selector, or URL pattern, and never use a guessed ref as an exploratory probe. If a ref lookup fails (stale snapshot), take a fresh browser_snapshot immediately instead of retrying; if a heading or visible text target is unique and the user's request authorizes navigation, click it directly.
6. After an action, collect the cheapest observation that answers your next question — a targeted check when possible, a fresh browser_snapshot when new ground truth is needed. Use at most one state-changing action per observation cycle. An unchanged URL does not prove the click failed. Judge an action by whether its expected effect appeared (page state change, or a tab whose verified URL/title matches the intended result). When an action may open a popup/new tab and the source tab does not show the expected effect, read browser_tabs action="list" and match by verified id/url/title before doing anything else.
7. Browser tabs persist for the lifetime of the session unless you close them with browser_tabs action="close" or browser_close. Do not close research/source tabs merely because the turn is ending.