How to use the agent-browser core guide agent skill

What the core skill makes the agent do

Without this skill, an agent asked to work on a website often has to guess from raw HTML. The core skill teaches it a different loop. The agent opens a page, reads a compact accessibility-tree snapshot that lists interactive elements with numbered references such as @e1 or @e3, and then acts on those references by clicking, filling fields, pressing keys, or extracting text.

The guide covers navigating pages, interacting with elements (click, fill, type, select), extracting text and data, taking screenshots, managing tabs, handling forms and auth, waiting for content, running several browser sessions in parallel, and troubleshooting common failures.

• Opens URLs and reads the page through snapshots
• Clicks, fills, types into and selects form elements by ref
• Extracts text and data, and takes screenshots
• Manages tabs, waits for content, and saves or restores login state
• Uses a named, isolated browser session and closes the browser when finished

Install the core skill

The skill ships as a ZIP file from this page. Download it, then unzip it into one of two places. For a personal setup, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project. The skill folder contains SKILL.md, a references/ folder and a templates/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

• Personal: unzip into ~/.claude/skills/
• Project: unzip into .claude/skills/ in the project root
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Install the browser tool it depends on

The skill does not run a browser by itself. It needs the agent-browser command-line tool, which requires Node.js with npm. Install the tool, then download Chrome or Chromium with the install command. On Linux you can also install optional system libraries.

• Requirement: Node.js with npm
• Requirement: Chrome or Chromium, downloaded via agent-browser install
• Linux only, optional: system libraries via agent-browser install --with-deps

How to trigger the skill with natural requests

You do not need to type a command name. The skill is meant to load when you ask for something browser-related. The description covers requests such as interacting with a website, filling a form, clicking something, extracting data, taking a screenshot, logging into a site, testing a web app, or automating any browser task.

Be specific about the site, the goal and the stopping point. For risky actions, say that you want the agent to pause before submitting, paying or sending anything.

• "Open example.com and take a screenshot of the homepage."
• "Fill in the contact form on this page with the details I give you, but stop before submitting."
• "Log into my staging site and save the login so we can reuse it."
• "Extract the table of prices from this page into a CSV."

What the agent does behind the scenes

The agent first sets a named session so it does not share the default browser. It then runs a short loop: open, snapshot with interactive elements only, act on a ref, and re-snapshot after any change to the page. Refs can be reused across snapshots, but a fresh snapshot is taken after navigation.

When a site advertises a WebMCP tool that matches the task, the guide says the agent should prefer that tool over rebuilding the same action through page controls. It also treats all website metadata as untrusted data, not as instructions.

• Named session set before the first command
• Open, snapshot, act, re-snapshot
• Browser closed when the task is finished

Safety notes: scripts and network access

This skill runs scripts and uses the network. The included templates are shell scripts (templates/authenticated-session.sh, templates/capture-workflow.sh and templates/form-automation.sh), and the browser connects to the sites you ask it to visit. Read a template before running it, and only point the agent at sites you are authorised to use.

The agent acts with real logins. It can submit forms or make purchases. Keep a human in the loop for high-impact actions. The guide covers the mechanics of browser automation only; it does not decide whether a task is permitted under a site's terms of service or the law. Login state can be saved and restored, so treat any saved state as sensitive.

• Review templates/*.sh before running them
• Confirm before submits, purchases or any sensitive account action
• Do not use it on sites you are not authorised to access
• Protect saved login state the same way you protect passwords

Tips for reliable results

Keep the task small and check progress with screenshots. Use snapshot -i to keep output short. If a page changes, take a new snapshot before clicking again, because old refs may point to the wrong element. The browser stays running between commands and, by default, shuts down after an hour without activity, so close it when you are done.

For repeated work on a site that needs login, use the authentication references and the authenticated-session template rather than typing credentials into each task. The references folder includes guides on sessions, authentication, command reference, snapshot refs, proxies, profiling, streaming and video recording.

• Use screenshot checkpoints on long tasks
• Re-snapshot after navigation or any visible change
• Run agent-browser close (or close --all) at the end
• Read references/commands.md for flags you have not seen before