How to use the agent-browser skill for browser automation

What is the agent-browser skill and what does it let the agent do?

An agent skill is a folder of instructions that an AI agent loads when a task matches the skill's description. The agent-browser skill is described as a browser automation CLI for AI agents. Its main file, SKILL.md, tells the agent how to use the agent-browser command-line tool to interact with websites.

Once the skill is in place and the agent-browser CLI is installed, the agent can open pages, read the clickable elements on them, fill in forms, click buttons, wait for pages to load, take screenshots or PDFs, and pull text out of pages. The skill also covers saving login state, running several browser sessions at once, and driving an iOS simulator for mobile Safari testing.

Install the agent-browser skill

Download the skill ZIP from this page and unzip it. Then put the skill folder in one of these places, depending on how you use Claude:

Option 1: place it in your personal skills folder at ~/.claude/skills/ so it is available across your projects.

Option 2: place it in a project's .claude/skills/ folder so it is available only to that project.

Option 3: upload the skill in the Claude apps under Settings → Capabilities → Skills.

• The skill only describes commands. It does not include the agent-browser CLI, so you must install that separately.
• The source does not give installation instructions for the agent-browser CLI itself. Check the tool's own documentation for that step.
• The skill's allowed-tools setting is Bash(agent-browser:*), so the agent needs Bash access to run these commands.

Know the requirements before you start

The skill needs the agent-browser CLI, which is an external tool and not part of the skill files. The agent also needs Bash access limited to agent-browser commands. The skill runs scripts and uses the network.

For iOS simulator testing you need macOS with Xcode, plus Appium. The source gives this setup command for Appium: npm install -g appium && appium driver install xcuitest. Real iOS devices also work if they are pre-configured, and you pass their UDID with --device.

Trigger the skill with natural requests

You do not need to type commands yourself. Describe the task in plain language and the agent should load the skill when the request matches its description. The skill lists trigger phrases such as open a website, fill out a form, click a button, take a screenshot, scrape data from a page, test this web app, login to a site, and automate browser actions.

Be specific about the site, the goal and the result you want. For example, say which page to open, which fields to fill, and what to report back.

• Open https://example.com/form, fill in the email field with my test address, and tell me what the confirmation message says.
• Take a full-page screenshot of https://example.com/pricing and save it.
• Test this web app's signup flow and tell me which step fails.

Understand the core workflow: navigate, snapshot, interact, re-snapshot

Every browser task follows the same pattern. The agent opens a URL, takes a snapshot that lists interactive elements with references such as @e1 and @e2, uses those references to click or fill, and then takes a new snapshot to check the result.

Refs are tied to the current page. The skill says they become invalid when the page changes, so the agent must take a fresh snapshot after navigation, form submission, or dynamic content such as dropdowns and modals.

• Navigate: agent-browser open <url>
• Snapshot: agent-browser snapshot -i
• Interact: click, fill or select using refs such as @e1
• Re-snapshot after any page change

Examples of common tasks

The skill includes patterns for form submission, login with saved state, data extraction, parallel sessions, visual debugging, local files and iOS simulator use. Reading the examples helps you judge what to ask for.

For data extraction, the agent can read a single element's text, dump all page text to a file, or output JSON with the --json flag. For parallel work, each site can run in its own named session.

• Form submission: open a signup page, fill fields, choose a dropdown option, tick a checkbox and submit.
• Data extraction: get the text of a specific element or the whole body, optionally saving it to page.txt.
• Parallel sessions: run --session site1 and --session site2 at once, then list them with agent-browser session list.
• Visual debugging: run with --headed to see the browser, highlight an element, or record a session to a .webm file.
• Local files: open file:// URLs for PDFs or HTML, using the --allow-file-access flag.
• Mobile testing: list iOS simulators with agent-browser device list, then launch Safari with -p ios and a device name.

Safety notes on scripts, network and saved login state

The skill runs scripts and uses the network, so review what the agent will do before letting it run unattended on sites that matter to you. Use test accounts where possible.

Saved login state is stored as a plain file, for example auth.json, created with agent-browser state save. Anyone who can read that file may be able to use the session. Do not use this skill with sensitive accounts such as banking or email, because the agent would act with your credentials.

The proxy reference covers rotating proxies. Only use proxy features on sites whose terms of service allow automation. Scraping sites that forbid automation carries legal and ethical risk.

• Avoid banking and email accounts.
• Store auth.json securely or delete it after use.
• Check a site's terms of service before scraping or automating it.