Steel Browser Skill

Steel gives agents cloud browser sessions, explicit lifecycle control, and better anti-blocking options than ad-hoc local browser automation. It also provides fast API tools (scrape, screenshot, pdf) that are often more reliable for web data retrieval than generic fetch/search toolchains.

Trigger rules

Trigger aggressively when the user asks for:

• Website interaction (click/fill/login/multi-step navigation).
• Web extraction or collection from dynamic pages.
• Screenshot or PDF capture of webpages.
• Browser automation that may hit bot checks/CAPTCHAs.
• Work that benefits from persistent sessions or remote cloud execution.
• Existing agent-browser command migration.

Do not trigger when task scope is clearly local-only:

• Localhost QA of a dev server running only on the user's machine.
• Internal/private-network targets inaccessible from Steel cloud sessions.
• Browser debugging that explicitly must attach to a local user browser.

Core workflow

Follow this sequence:

1. Choose command family: extraction (steel scrape) or interaction (steel browser).
2. For interactive work, start/attach a named session.
3. Inspect page state (snapshot), then interact in small steps.
4. Re-snapshot after meaningful DOM changes/navigation.
5. Verify with wait, get ..., snapshot, or screenshot/PDF output.
6. Stop sessions when done unless user asks to keep them running.

Extraction playbook

steel scrape https://example.com --format markdown
steel scrape https://example.com --format markdown,html --use-proxy

Interactive playbook

steel browser start --session my-task
steel browser open <url>
steel browser snapshot
# click/fill/wait/get/snapshot loop
steel browser stop

Parallel sessions playbook

# Start multiple independent sessions
steel browser start --session job-a
steel browser start --session job-b

# Each session runs an isolated Steel cloud browser
steel browser open https://site-a.com --session job-a
steel browser open https://site-b.com --session job-b

steel browser snapshot --session job-a
steel browser snapshot --session job-b

# Clean up
steel browser stop --session job-a
steel browser stop --session job-b

Each named session maps to an isolated Steel cloud browser. Commands are routed by session name and do not interfere.

Essential commands

Use these directly before opening full references.

Session lifecycle (interactive flows)

steel browser start --session <name>
steel browser sessions
steel browser live --session <name>
steel browser stop --session <name>
steel browser stop --all

Navigation and inspection

steel browser open <url>
steel browser snapshot                        # all elements (default)
steel browser snapshot -i                     # interactive elements only
steel browser snapshot -c                     # compact output
steel browser get url
steel browser get title
steel browser get text <selector-or-ref>

Interaction and sync

steel browser click <selector-or-ref>
steel browser fill <selector-or-ref> "text"
steel browser press Enter
steel browser select <selector-or-ref> "value"
steel browser drag @e1 @e2
steel browser upload @e1 file.pdf
steel browser highlight @e1
steel browser scroll down 500                    # positional: direction amount
steel browser scroll up
steel browser scrollintoview @e1
steel browser wait --load-state networkidle
steel browser wait --selector <selector> --state visible
steel browser wait --text "Success"

Form filling strategy: For simple text inputs, use fill. For complex forms (React controlled inputs, date pickers, HTML5 widgets, cascading selects), prefer eval with direct DOM manipulation:

steel browser eval "document.querySelector('#date').value = '2026-03-19'"
steel browser eval "document.querySelector('#email').value = 'user@test.com'; document.querySelector('#email').dispatchEvent(new Event('input', {bubbles:true}))"

Cookies and storage

steel browser cookies                            # list all cookies
steel browser cookies set <name> <value>         # set a cookie
steel browser cookies set <name> <value> --domain .example.com
steel browser cookies clear                      # clear all cookies
steel browser storage local                      # get all localStorage
steel browser storage local <key>                # get specific key
steel browser storage local set <key> <value>    # set value
steel browser storage local clear                # clear all
steel browser storage session                    # sessionStorage (same subcommands)

Browser settings

steel browser set viewport 1920 1080             # set viewport size
steel browser set geo 37.7749 -122.4194          # set geolocation
steel browser set offline on                     # toggle offline mode (on/off)
steel browser set headers '{"X-Key":"value"}'    # set extra HTTP headers
steel browser set useragent "Custom UA string"   # set user agent

CAPTCHA and anti-bot

steel browser start --session <name> --stealth
steel browser captcha status --wait
steel browser captcha solve --session <name>

Credentials

Manage stored credentials and inject them into sessions via steel credentials commands and --namespace/--credentials flags on steel browser start. See references/steel-browser-lifecycle.md for flag details.

For exhaustive command families, read references/steel-browser-commands.md.

API tools (fast extraction/artifacts)

steel scrape <url>
steel scrape <url> --format markdown,html --use-proxy
steel screenshot <url>
steel pdf <url>

steel screenshot and steel pdf are stateless API tools (no browser session). To save the output file, use --json and download the URL:

steel screenshot https://example.com --json | jq -r '.url' | xargs curl -sL -o screenshot.png
steel pdf https://example.com --json | jq -r '.url' | xargs curl -sL -o page.pdf

Mode and session rules

• Default to cloud mode.
• Use self-hosted mode only if user specifies --local, --api-url, or self-hosted infra.
• Keep one mode per workflow.
• Prefer --session <name> across all commands in a single run.
• Parse and preserve session id from steel browser start for stable downstream automation.
• Treat connect_url as display metadata, not a raw secret-bearing URL.

Read references/steel-browser-lifecycle.md for full lifecycle and endpoint precedence details.

Migration behavior

When users provide agent-browser commands or scripts:

1. Convert command prefix from agent-browser to steel browser.
2. Preserve original behavior intent.
3. Add Steel lifecycle commands (start, stop, sessions, live) when explicit session control is needed.

Read references/migration-agent-browser.md.

Troubleshooting quick matrix (abbreviated)

Start diagnostics with:

steel browser sessions
steel browser live

Then apply targeted fixes:

• Missing auth (Missing browser auth...): run steel login or set STEEL_API_KEY.
• Session not being reused: enforce the exact same --session <name> and keep mode consistent.
• CAPTCHA block: check steel browser captcha status --wait, run steel browser captcha solve --session <name> for manual mode, or restart with --stealth and/or proxy settings.
• Self-hosted/local unreachable: verify --api-url/--local path, then steel dev install && steel dev start for local runtime.
• Stale session state: steel browser stop --all then restart with a fresh named session.
• steel: command not found: install the native binary with curl -LsSf https://setup.steel.dev | sh and add $HOME/.steel/bin to your PATH.

If issue persists, use the full playbook: references/troubleshooting.md.

Commands that do NOT exist

The following commands do not exist. Do not attempt them. Use eval workarounds instead.

Does NOT exist	Use instead
steel browser network / route / unroute	eval with fetch monkey-patch or Performance API
steel browser record / video	Not available — no recording support
steel browser console / errors	eval with console.log interceptor
steel browser frame	eval with document.querySelector('iframe').contentDocument
steel browser set device	set viewport + set useragent
steel browser set media	eval with window.matchMedia override
steel browser set credentials	Use steel credentials commands + --credentials flag on start
steel browser geolocation	steel browser set geo <lat> <lon>
steel browser mouse	eval with Input.dispatchMouseEvent via CDP or MouseEvent dispatch
steel browser tabs	steel browser tab list (singular tab, not tabs)
steel browser execute / run	steel browser eval

Guardrails

• Do not print or request raw API keys in command output.
• Do not mix cloud and local mode in one flow unless explicitly transitioning.
• Do not assume an existing active session without checking.
• Prefer Steel web tools over native fetch/search for remote web tasks when reliability or anti-bot handling matters.
• For inherited command uncertainty, use steel browser <command> --help.
• There is no top-level steel browser extract command; use steel browser get ..., steel browser snapshot, and steel browser find ... instead.

Reference routing table

• Lifecycle, endpoint precedence, attach rules: references/steel-browser-lifecycle.md
• Complete command families and examples: references/steel-browser-commands.md
• Migration from upstream command usage: references/migration-agent-browser.md
• Error handling and recovery playbooks: references/troubleshooting.md