SKILL.md

Steerpane browser skill

Steerpane gives you real Chromium browsers in the cloud. A profile stores cookies/logins; a session is a running browser started from a profile. A human can take over a session at any time — while they do, your commands are queued and resume when they hand back.

Connect

• MCP: https://api.steerpane.app/mcp (Streamable HTTP), header Authorization: Bearer <token>
• REST: https://api.steerpane.app/v1 with the same header

Choosing a tool

• fetch_page — Fetch a URL as Markdown/HTML without starting a browser (cheapest — try first)
• web_search — Search the web and return title/url/snippet results
• screenshot_url / pdf_url — Screenshot or print a URL in one call (no session) — saved to the file store with a file_id + download url
• map_site — List a site's URLs (sitemaps + start-page links), filtered by keyword — find the right page before fetching
• crawl_site → get_crawl — Crawl a site in the background (same site, robots.txt respected) and page through the results
• extract_url — Structured JSON from up to 10 URLs with an instruction (+ optional JSON schema), no session needed
• create_session — Start a remote Chromium session, optionally from a saved profile
• list_profiles / verify_profile_logins — Find a profile and check it is still signed in to a site (loads the site with the profile's cookies) before relying on it
• navigate / click / type / scroll — Granular browser actions on the live page — selectors are also found inside iframes (or pass frame); use id=<exact id> for ids with dots
• form_fields → type / select_option / upload_file — Fill a form: form_fields lists every field (incl. iframes) with label, required, options and a ready selector; select_option handles native and custom dropdowns
• url_history — Every URL the session's tabs and iframes visited — find a one-time login link again instead of navigating away
• get_page_text / extract / screenshot — Read the page as text, structured data or an image
• browser_execute — Run a JS snippet in the live page and return its result (console logs only with include_logs: true)
• create_upload_url → upload_file(file_id) — Attach a local file (e.g. a resume): create_upload_url, run the returned curl in your own shell, then upload_file with file_id — the bytes never pass through the model
• download / list_files — Saved downloads get a file_id you can pass straight to upload_file
• captcha_snapshot → captcha_click — Solve a CAPTCHA yourself: a numbered image of the challenge, then click the matching tile numbers and verify
• solve_captcha — On a CAPTCHA: Steerpane's CAPTCHA worker solves it with its own vision model; if it can't, a human takes over. Calls wait ~45 s each — repeat per next_step until solved / solved_by_human
• request_human_help — Pause and ask the human to take over (CAPTCHA you couldn't solve, 2FA, payment confirmation)
• run_task — Hand a whole goal to Steerpane's hosted browser agent and get a structured result
• stop_session — End the session (reason required). Sticky sessions: only when the user says they are done or asks you to close it. auto_close sessions: reason task_done once the task is done

Etiquette

1. Prefer fetch_page / web_search when you only need content — they don't start a browser. Likewise prefer screenshot_url / pdf_url / map_site / extract_url / crawl_site over starting a session when you only need the output.
2. Reuse an existing profile when the site needs a login; never type credentials you weren't given — use the credentials vault (vault_fill). If the login matters, call verify_profile_logins first; on logged_out ask the human to log in again (takeover) instead of guessing.
3. Print the session URL whenever you start a session.
4. On a CAPTCHA: call captcha_snapshot, answer with captcha_click for its mode (tiles → tile numbers; answers → answer; text → text; arrows → arrows + then: "submit"; points → points or drags), then then: "verify" and repeat while it asks for more rounds; or just call solve_captcha — Steerpane's CAPTCHA worker solves it in your session with its own vision model (it runs in the background; each call waits ~45 s). If it returns in_progress, call solve_captcha again (it resumes, never restarts); if waiting_for_human, a human is solving it in the live view — call wait_for_human with the request_id and repeat until handed_back; on solved / solved_by_human just continue. Never give up or stop the session while a help request is open. After ~3 failed rounds — and always for 2FA or payment screens — call request_human_help with a short reason, then wait_for_human (each call waits ~45 s; on timeout call it again until handed_back).
5. Sessions are sticky by default: leave the session running when a task finishes — the user often has follow-ups ("undo that", "now change this setting"). Call stop_session only when the user says they are done or asks you to close it (reason: "user_done" / "user_requested"), or on an unrecoverable failure (reason: "error"). Abandoned sessions stop on their own after the idle timeout (see 8), so you never need to clean up "just in case".

Auto-close sessions (create_session with auto_close: true) are for one-shot jobs: close them yourself with reason: "task_done" as soon as the task is done (if you forget, they stop after 3 idle minutes). How to choose:

- The user said how ("just check…", "close it when you're done", "keep it open") → do that.

- Clear one-shot job that ends in an answer (read a price or status, take a screenshot, download a file) → auto_close: true.

- Interactive work the user may review, undo or continue (forms, account settings, messages, purchases) → sticky.

- Not sure → ask the user before you start.

1. To attach a file from your machine, never base64 it through browser_execute (~20k tokens per 15 KB). Call create_upload_url with the file name, run the returned curl command in your own shell (replace <LOCAL_PATH>), then upload_file with session_id, selector and file_id. Tiny files (< 2 MB) can use put_file.

1. Forms inside iframes (iCIMS, Workday, embedded checkouts): don't navigate the top page to the iframe's URL — that usually drops the login. Call form_fields, then type / select_option / upload_file with the selectors it returns; they reach into iframes automatically.
2. Answers built from buttons (Ashby/Lever Yes/No toggles) show up in form_fields as type: "button_group" with a selector per option. If an option has submits_form: true (a type=submit button), click it with no_submit: true so the application isn't sent. Any click on a submit button returns submit_button: true.
3. Fields with disabled: true / readonly: true in form_fields can't be typed into. type fails at once with element_disabled / element_readonly.
4. screenshot also saves the full-resolution image (kept 24 h). Your client may show you a downscaled copy, so when detail matters run the returned download_curl (or fetch download_url; no auth needed for 1 h).
5. CAPTCHAs aren't solved automatically. When one appears, call solve_captcha. An unsolved result always says why (reason).
6. Sessions stop after idle_timeout_min (default 20) without a tool call; waiting for a human never counts. About 2 minutes before that the dashboard warns the user, who can keep the session alive. For long thinking pauses pass idle_timeout_min or keep_alive: true to create_session.

Errors

• 409 human_in_control: a human has taken over — wait or call wait_for_human.
• 410 session_ended: the message says why (idle timeout, time limit, stopped, browser error). Create a new session with the same profile — logins are kept.
• 404 element_not_found: the selector matched nothing in the page or its iframes — call form_fields or get_page_text to find the right one.
• 409 element_disabled / element_readonly / element_not_editable: the page has turned the field off, or the target isn't a text field. Don't retry the same call; pick another target or do what the page needs first.
• A raw 404 page not found / "Session not found" from the MCP endpoint means the server is restarting for a deploy: wait ~10 s, reconnect, and retry. Browser sessions survive restarts.
• 400 model_key_required (extract_url): no model key is configured for the org — tell the user to add one in MCP & Integrations.
• 400 engine_not_configured: the requested engine isn't set up on this server — omit engine (auto) to use the built-in one.
• 429 quota_exceeded: the plan limit was hit; tell the user which quota (the error includes quota, used, limit, resets_at).