How to use the Browser Harness agent skill (browser-harness)

What is an agent skill, and what does browser-harness make the agent do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent when and how to perform a task. The agent reads the skill's description and loads its instructions when a request matches.

The browser-harness skill (skill name: browser-harness) teaches the agent to drive a real browser. Once installed, the agent can attach to your running Chrome or Chromium instance and perform clicks, typing, navigation and screenshots.

• Interacting with pages that need clicks, typing or form submission
• Working on JavaScript-rendered pages
• Using your logged-in browser session
• Reaching pages that block simple HTTP fetches

Install the browser-harness skill

Option 1: download the ZIP from this page and unzip it into your personal skills folder, ~/.claude/skills/, or into a project's .claude/skills/ folder so it applies only to that project.

Option 2: in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

The skill's own install guide (install.md) covers installing the browser-harness CLI and connecting it to a browser. The skill depends on that CLI, so complete that setup too.

• Personal: ~/.claude/skills/browser-harness/
• Project: .claude/skills/browser-harness/ inside your project
• Claude apps: Settings → Capabilities → Skills

Check what you need before you start

The skill needs Google Chrome or Chromium with remote debugging available, plus Python tooling and the browser-harness CLI. The setup steps are in install.md and pyproject.toml in the skill files.

Browser Use Cloud is optional. It is only needed for remote browsers. macOS users may need to grant Accessibility permission to the mac-approve helper.

• Google Chrome or Chromium with remote debugging
• Python tooling and the browser-harness CLI (see install.md and pyproject.toml)
• Optional: Browser Use Cloud account and API access for remote browsers
• macOS only, if needed: Accessibility permission for the mac-approve helper

How to trigger the skill with natural requests

You do not need special syntax. Describe a task that needs a real browser and the agent will pick the skill when it matches. Name the site and the action you want.

For plain reads of public pages or APIs, the skill tells the agent to use curl or a basic fetch first. It only opens the browser if those fail or return a shell page, so you do not need to ask for curl explicitly.

• "Log into my dashboard on the billing site and download this month's invoice."
• "Fill in the signup form on this page and take a screenshot of the confirmation."
• "This page is JavaScript-heavy. Open it and read the table that loads after the page renders."

Basic usage the agent follows

The agent runs browser-harness with a heredoc script. The helpers are pre-imported, so a short script can read the current page. The first navigation for a task opens a new tab, and the agent is told to reuse a matching tab where possible.

The agent is instructed to keep the browser in the background. It does not bring Chrome to the foreground unless you explicitly ask to see a tab. If a site needs focus, the agent is told to enable focus emulation temporarily and disable it afterwards.

• Tabs are reused per task or site, not duplicated
• Tabs the agent created are closed at task completion when no longer needed
• Tabs you did not create are not closed

Safety notes: scripts and network access

This skill runs scripts and uses the network. The agent acts with your logged-in session, so anything it can do in that browser (including changing data) it can do on your behalf.

Keep sensitive accounts such as banking or email out of agent control unless you can supervise closely. Chrome may also show remote-debugging Allow prompts; you should approve them only for sessions you intend.

Domain skills are off by default. Enable them only if you want the agent to read and write site-specific notes, by setting BH_DOMAIN_SKILLS=1.

• Runs scripts: yes
• Uses network: yes
• The agent uses your logged-in session, so it can change data
• Keep banking and email under close supervision

Tips for reliable results

Let the agent use curl for public reads. Browser control is slower and riskier, so reserve it for interaction or logged-in work.

If the connection fails, ask the agent to run the diagnostics command. Use the default local connection rather than creating extra named sessions, since each new one can trigger another Chrome Allow prompt.

On macOS, if Chrome asks for remote-debugging permission, the agent may use the mac-approve helper. On Linux or Windows, click Allow yourself when Chrome shows the dialog.

• Prefer curl or a basic fetch for public pages and APIs
• Use the default local connection for sequential work
• Run browser-harness --doctor when the connection fails
• Use Browser Use Cloud only when you need remote or parallel browsers