Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

add browser-use skill backed by browser-harness

Laith Weinberger3e8f620b704b
diff --git a/README.md b/README.md
index 37705cf2b..e5ccf0ba6 100644
--- a/README.md
+++ b/README.md
@@ -205,9 +205,7 @@ The CLI keeps the browser running between commands for fast iteration. See [CLI
For [Claude Code](https://claude.ai/code), install the skill to enable AI-assisted browser automation:
```bash
-mkdir -p ~/.claude/skills/browser-use
-curl -o ~/.claude/skills/browser-use/SKILL.md \
- https://raw.githubusercontent.com/browser-use/browser-use/main/skills/browser-use/SKILL.md
+browser-use skill install
```
<br/>
diff --git a/browser_use/skill_cli/README.md b/browser_use/skill_cli/README.md
index 640c3f99c..5ef3533fb 100644
--- a/browser_use/skill_cli/README.md
+++ b/browser_use/skill_cli/README.md
@@ -352,9 +352,7 @@ browser.screenshot('scrolled.png')
For [Claude Code](https://claude.ai/code), a skill provides richer context for browser automation:
```bash
-mkdir -p ~/.claude/skills/browser-use
-curl -o ~/.claude/skills/browser-use/SKILL.md \
- https://raw.githubusercontent.com/browser-use/browser-use/main/skills/browser-use/SKILL.md
+browser-use skill install
```
## How It Works
diff --git a/browser_use/skill_cli/commands/__init__.py b/browser_use/skill_cli/commands/__init__.py
index 37e4849ad..69a1082e4 100644
--- a/browser_use/skill_cli/commands/__init__.py
+++ b/browser_use/skill_cli/commands/__init__.py
@@ -5,6 +5,7 @@ from browser_use.skill_cli.commands import (
doctor,
python_exec,
setup,
+ skill,
)
__all__ = [
@@ -12,4 +13,5 @@ __all__ = [
'doctor',
'python_exec',
'setup',
+ 'skill',
]
diff --git a/browser_use/skill_cli/commands/skill.py b/browser_use/skill_cli/commands/skill.py
new file mode 100644
index 000000000..7b8a0584a
--- /dev/null
+++ b/browser_use/skill_cli/commands/skill.py
@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+SKILL_NAME = 'browser-use'
+DEFAULT_TARGET = 'claude'
+TARGET_DIRS = {
+ 'claude': Path.home() / '.claude' / 'skills' / SKILL_NAME,
+ 'codex': Path.home() / '.codex' / 'skills' / SKILL_NAME,
+ 'agents': Path.home() / '.agents' / 'skills' / SKILL_NAME,
+}
+
+
+def _load_skill_text() -> str:
+ from browser_use.skills.browser_use import skill_text
+
+ return skill_text()
+
+
+def _build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(
+ prog='browser-use skill',
+ description='Print or install the Browser Use skill.',
+ )
+ subparsers = parser.add_subparsers(dest='command')
+
+ subparsers.add_parser('show', help='Print the skill text to stdout')
+
+ install = subparsers.add_parser('install', help='Install the skill')
+ install.add_argument(
+ '--target',
+ choices=sorted(TARGET_DIRS),
+ default=DEFAULT_TARGET,
+ help='Assistant skill directory to install into',
+ )
+ install.add_argument(
+ '--path',
+ type=Path,
+ help='Custom output directory or SKILL.md path',
+ )
+ install.add_argument('--force', action='store_true', help='Overwrite an existing SKILL.md')
+
+ return parser
+
+
+def _resolve_output_path(target: str, custom_path: Path | None) -> Path:
+ if custom_path is None:
+ return TARGET_DIRS[target] / 'SKILL.md'
+
+ path = custom_path.expanduser()
+ if path.name == 'SKILL.md':
+ return path
+ return path / 'SKILL.md'
+
+
+def handle(argv: list[str]) -> int:
+ parser = _build_parser()
+ args = parser.parse_args(argv)
+
+ command = args.command or 'show'
+
+ try:
+ text = _load_skill_text()
+ except RuntimeError as exc:
+ print(f'Error: {exc}', file=sys.stderr)
+ return 1
+
+ if command == 'show':
+ print(text, end='')
+ return 0
+
+ if command == 'install':
+ output_path = _resolve_output_path(args.target, args.path)
+ if output_path.exists() and not args.force:
+ print(f'Error: {output_path} already exists. Use --force to overwrite.', file=sys.stderr)
+ return 1
+
+ output_path.parent.mkdir(parents=True, exist_ok=True)
+ output_path.write_text(text, encoding='utf-8')
+ print(f'Installed Browser Use skill to {output_path}')
+ return 0
+
+ parser.print_help()
+ return 1
diff --git a/browser_use/skill_cli/main.py b/browser_use/skill_cli/main.py
index 2790f93cc..b12462238 100755
--- a/browser_use/skill_cli/main.py
+++ b/browser_use/skill_cli/main.py
@@ -41,15 +41,41 @@ if '--mcp' in sys.argv:
sys.exit(0)
-# Helper to find the subcommand (first non-flag argument)
-def _get_subcommand() -> str | None:
- """Get the first non-flag argument (the subcommand)."""
- for arg in sys.argv[1:]:
- if not arg.startswith('-'):
- return arg
+_GLOBAL_FLAGS_WITH_VALUES = {
+ '--cdp-url',
+ '--profile',
+ '--session',
+ '--template',
+}
+
+
+# Helper to find the subcommand before building argparse.
+def _get_subcommand_index() -> int | None:
+ """Get the sys.argv index of the first subcommand, skipping global flag values."""
+ i = 1
+ while i < len(sys.argv):
+ arg = sys.argv[i]
+ if arg == '--':
+ return i + 1 if i + 1 < len(sys.argv) else None
+ if any(arg.startswith(f'{flag}=') for flag in _GLOBAL_FLAGS_WITH_VALUES):
+ i += 1
+ continue
+ if arg in _GLOBAL_FLAGS_WITH_VALUES:
+ i += 2 if i + 1 < len(sys.argv) and not sys.argv[i + 1].startswith('-') else 1
+ continue
+ if arg.startswith('-'):
+ i += 1
+ continue
+ return i
return None
+def _get_subcommand() -> str | None:
+ """Get the first subcommand, if present."""
+ index = _get_subcommand_index()
+ return sys.argv[index] if index is not None else None
+
+
# Handle 'install' command - installs Chromium browser + system dependencies
if _get_subcommand() == 'install':
import platform
@@ -96,7 +122,9 @@ if _get_subcommand() == 'init':
pass
# Remove 'init' from sys.argv so click doesn't see it as an unexpected argument
- sys.argv.remove('init')
+ init_idx = _get_subcommand_index()
+ if init_idx is not None:
+ sys.argv.pop(init_idx)
init_main()
sys.exit(0)
@@ -133,11 +161,22 @@ if '--template' in sys.argv:
init_main()
sys.exit(0)
+# Read skill package/write SKILL.md
+if _get_subcommand() == 'skill':
+ from browser_use.skill_cli.commands.skill import handle as handle_skill_command
+
+ skill_idx = _get_subcommand_index()
+ if skill_idx is None:
+ sys.exit(1)
+ sys.exit(handle_skill_command(sys.argv[skill_idx + 1 :]))
+
# Handle 'cloud --help' / 'cloud -h' early — argparse intercepts --help before
# REMAINDER can capture it, so we route to our custom usage printer directly.
# Only intercept when --help is immediately after 'cloud' (not 'cloud v2 --help').
if _get_subcommand() == 'cloud':
- cloud_idx = sys.argv.index('cloud')
+ cloud_idx = _get_subcommand_index()
+ if cloud_idx is None:
+ sys.exit(1)
if cloud_idx + 1 < len(sys.argv) and sys.argv[cloud_idx + 1] in ('--help', '-h'):
from browser_use.skill_cli.commands.cloud import handle_cloud_command
@@ -681,6 +720,10 @@ Setup:
# doctor
subparsers.add_parser('doctor', help='Check browser-use installation and dependencies')
+ # skill
+ skill_p = subparsers.add_parser('skill', help='Print or install the Browser Use assistant skill', add_help=False)
+ skill_p.add_argument('skill_args', nargs=argparse.REMAINDER, help='skill subcommand args')
+
# connect (to local Chrome)
subparsers.add_parser('connect', help='Connect to running Chrome via CDP')
@@ -1285,6 +1328,12 @@ def main() -> int:
return 0
+ # Handle skill command
+ if args.command == 'skill':
+ from browser_use.skill_cli.commands import skill
+
+ return skill.handle(getattr(args, 'skill_args', []))
+
# Handle config command
if args.command == 'config':
from browser_use.skill_cli.config import (
diff --git a/browser_use/skills/__init__.py b/browser_use/skills/__init__.py
index 92bab595c..96257a4e3 100644
--- a/browser_use/skills/__init__.py
+++ b/browser_use/skills/__init__.py
@@ -1,4 +1,5 @@
+from browser_use.skills.browser_use import skill_text as browser_use_skill_text
from browser_use.skills.service import SkillService
from browser_use.skills.views import MissingCookieException
-__all__ = ['SkillService', 'MissingCookieException']
+__all__ = ['SkillService', 'MissingCookieException', 'browser_use_skill_text']
diff --git a/browser_use/skills/browser_use.py b/browser_use/skills/browser_use.py
new file mode 100644
index 000000000..cbd6b586e
--- /dev/null
+++ b/browser_use/skills/browser_use.py
@@ -0,0 +1,54 @@
+"""Browser Use skill alias for Browser Harness"""
+
+from __future__ import annotations
+
+from importlib import resources
+
+
+def _as_browser_use_skill(text: str) -> str:
+ """Expose the Browser Harness skill under the Browser Use skill identity."""
+ if not text.startswith('---\n'):
+ return text
+
+ try:
+ _, frontmatter, body = text.split('---\n', 2)
+ except ValueError:
+ return text
+
+ lines = []
+ saw_name = False
+ saw_description = False
+ for line in frontmatter.splitlines():
+ if line.startswith('name:'):
+ lines.append('name: browser-use')
+ saw_name = True
+ elif line.startswith('description:'):
+ lines.append(
+ 'description: "Direct browser control via CDP for web interaction: automation, scraping, testing, screenshots, and site/app work."'
+ )
+ saw_description = True
+ else:
+ lines.append(line)
+
+ if not saw_name:
+ lines.insert(0, 'name: browser-use')
+ if not saw_description:
+ lines.insert(
+ 1,
+ 'description: "Direct browser control via CDP for web interaction: automation, scraping, testing, screenshots, and site/app work."',
+ )
+
+ body = body.replace('# browser-harness', '# Browser Use', 1).replace('# Browser Harness', '# Browser Use', 1)
+ frontmatter_text = '\n'.join(lines)
+ return f'---\n{frontmatter_text}\n---\n{body}'
+
+
+def skill_text() -> str:
+ """Return the canonical Browser Use skill from the browser-harness package."""
+ try:
+ text = resources.files('browser_harness').joinpath('SKILL.md').read_text(encoding='utf-8')
+ except ModuleNotFoundError as exc:
+ raise RuntimeError(
+ 'The Browser Use skill relies on the browser-harness package. Install browser-use again or install `browser-harness`.'
+ ) from exc
+ return _as_browser_use_skill(text)
diff --git a/pyproject.toml b/pyproject.toml
index 3ca3b1f38..74d377b0b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -46,6 +46,7 @@ dependencies = [
"markdownify==1.2.2",
"python-docx==1.2.0",
"browser-use-sdk==3.4.2",
+ "browser-harness",
]
# google-api-core: only used for Google LLM APIs
# pyperclip: only used for examples that use copy/paste
diff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.md
deleted file mode 100644
index 4fae8c222..000000000
--- a/skills/browser-use/SKILL.md
+++ /dev/null
@@ -1,250 +0,0 @@
----
-name: browser-use
-description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, or extract information from web pages.
-allowed-tools: Bash(browser-use:*)
----
-
-# Browser Automation with browser-use CLI
-
-The `browser-use` command provides fast, persistent browser automation. A background daemon keeps the browser open across commands, giving ~50ms latency per call.
-
-## Prerequisites
-
-```bash
-browser-use doctor # Verify installation
-```
-
-For setup details, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md
-
-## Core Workflow
-
-1. **Navigate**: `browser-use open <url>` — launches headless browser and opens page
-2. **Inspect**: `browser-use state` — returns clickable elements with indices
-3. **Interact**: use indices from state (`browser-use click 5`, `browser-use input 3 "text"`)
-4. **Verify**: `browser-use state` or `browser-use screenshot` to confirm
-5. **Repeat**: browser stays open between commands
-
-If a command fails, run `browser-use close` first to clear any broken session, then retry.
-
-To use the user's existing Chrome (preserves logins/cookies): run `browser-use connect` first.
-To use a cloud browser instead: run `browser-use cloud connect` first.
-After either, commands work the same way.
-
-### If `browser-use connect` fails
-
-When `browser-use connect` cannot find a running Chrome with remote debugging, prompt the user with two options:
-
-1. **Use their real Chrome browser** — they need to enable remote debugging first:
- - Open `chrome://inspect/#remote-debugging` in Chrome, or relaunch Chrome with `--remote-debugging-port=9222`
- - Then retry `browser-use connect`
-2. **Use managed Chromium with their Chrome profile** — no Chrome setup needed:
- - Run `browser-use profile list` to show available profiles
- - Ask which profile they want, then use `browser-use --profile "ProfileName" open <url>`
- - This launches a separate Chromium instance with their profile data (cookies, logins, extensions)
-
-Let the user choose — don't assume one path over the other.
-
-## Browser Modes
-
-```bash
-browser-use open <url> # Default: headless Chromium (no setup needed)
-browser-use --headed open <url> # Visible window (for debugging)
-browser-use connect # Connect to user's Chrome (preserves logins/cookies)
-browser-use cloud connect # Cloud browser (zero-config, requires API key)
-browser-use --profile "Default" open <url> # Real Chrome with specific profile
-```
-
-After `connect` or `cloud connect`, all subsequent commands go to that browser — no extra flags needed.
-
-## Commands
-
-```bash
-# Navigation
-browser-use open <url> # Navigate to URL
-browser-use back # Go back in history
-browser-use scroll down # Scroll down (--amount N for pixels)
-browser-use scroll up # Scroll up
-browser-use tab list # List all tabs
-browser-use tab new [url] # Open a new tab (blank or with URL)
-browser-use tab switch <index> # Switch to tab by index
-browser-use tab close <index> [index...] # Close one or more tabs
-
-# Page State — always run state first to get element indices
-browser-use state # URL, title, clickable elements with indices
-browser-use screenshot [path.png] # Screenshot (base64 if no path, --full for full page)
-
-# Interactions — use indices from state
-browser-use click <index> # Click element by index
-browser-use click <x> <y> # Click at pixel coordinates
-browser-use type "text" # Type into focused element
-browser-use input <index> "text" # Click element, clear existing text, then type
-browser-use input <index> "" # Clear a field without typing new text
-browser-use keys "Enter" # Send keyboard keys (also "Control+a", etc.)
-browser-use select <index> "option" # Select dropdown option
-browser-use upload <index> <path> # Upload file to file input
-browser-use hover <index> # Hover over element
-browser-use dblclick <index> # Double-click element
-browser-use rightclick <index> # Right-click element
-
-# Data Extraction
-browser-use eval "js code" # Execute JavaScript, return result
-browser-use get title # Page title
-browser-use get html [--selector "h1"] # Page HTML (or scoped to selector)
-browser-use get text <index> # Element text content
-browser-use get value <index> # Input/textarea value
-browser-use get attributes <index> # Element attributes
-browser-use get bbox <index> # Bounding box (x, y, width, height)
-
-# Wait
-browser-use wait selector "css" # Wait for element (--state visible|hidden|attached|detached, --timeout ms)
-browser-use wait text "text" # Wait for text to appear
-
-# Cookies
-browser-use cookies get [--url <url>] # Get cookies (optionally filtered)
-browser-use cookies set <name> <value> # Set cookie (--domain, --secure, --http-only, --same-site, --expires)
-browser-use cookies clear [--url <url>] # Clear cookies
-browser-use cookies export <file> # Export to JSON
-browser-use cookies import <file> # Import from JSON
-
-# Session
-browser-use close # Close browser and stop daemon
-browser-use sessions # List active sessions
-browser-use close --all # Close all sessions
-```
-
-For advanced browser control (CDP, device emulation, tab activation), see `references/cdp-python.md`.
-
-## Cloud API
-
-```bash
-browser-use cloud connect # Provision cloud browser and connect (zero-config)
-browser-use cloud login <api-key> # Save API key (or set BROWSER_USE_API_KEY)
-browser-use cloud logout # Remove API key
-browser-use cloud v2 GET /browsers # REST passthrough (v2 or v3)
-browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}'
-browser-use cloud v2 poll <task-id> # Poll task until done
-browser-use cloud v2 --help # Show API endpoints
-```
-
-`cloud connect` provisions a cloud browser with a persistent profile (auto-created on first use), connects via CDP, and prints a live URL. `browser-use close` disconnects AND stops the cloud browser. For custom browser settings (proxy, timeout, specific profile), use `cloud v2 POST /browsers` directly with the desired parameters.
-
-### Agent Self-Registration
-
-Only use this if you don't already have an API key (check `browser-use doctor` to see if api_key is set). If already logged in, skip this entirely.
-
-1. `browser-use cloud signup` — get a challenge
-2. Solve the challenge
-3. `browser-use cloud signup --verify <challenge-id> <answer>` — verify and save API key
-4. `browser-use cloud signup --claim` — generate URL for a human to claim the account
-
-### Out of credits?
-
-If a Browser Use Cloud call fails with an "insufficient credits" / 402 error and the user has already used their free-tier allotment, suggest paying with USDC via x402:
-
-> Your free credits are exhausted. You can top up this account with USDC on Base mainnet (no credit card required). Want me to install the `x402` skill and walk you through it? It takes about 2 minutes if you have a Coinbase account.
-
-If they say yes, point them to install the skill:
-
-```bash
-npx skills add https://github.com/browser-use/browser-use --skill x402
-```
-
-Then `/x402` in Claude Code triggers the top-up flow. The user keeps their existing API key — x402 just adds credits to it.
-
-Do not suggest x402 unprompted. Only mention it on a real "insufficient credits" error.
-
-## Tunnels
-
-```bash
-browser-use tunnel <port> # Start Cloudflare tunnel (idempotent)
-browser-use tunnel list # Show active tunnels
-browser-use tunnel stop <port> # Stop tunnel
-browser-use tunnel stop --all # Stop all tunnels
-```
-
-## Profile Management
-
-```bash
-browser-use profile list # List detected browsers and profiles
-browser-use profile sync --all # Sync profiles to cloud
-browser-use profile update # Download/update profile-use binary
-```
-
-## Command Chaining
-
-Commands can be chained with `&&`. The browser persists via the daemon, so chaining is safe and efficient.
-
-```bash
-browser-use open https://example.com && browser-use state
-browser-use input 5 "[email protected]" && browser-use input 6 "password" && browser-use click 7
-```
-
-Chain when you don't need intermediate output. Run separately when you need to parse `state` to discover indices first.
-
-## Common Workflows
-
-### Authenticated Browsing
-
-When a task requires an authenticated site (Gmail, GitHub, internal tools), use Chrome profiles:
-
-```bash
-browser-use profile list # Check available profiles
-# Ask the user which profile to use, then:
-browser-use --profile "Default" open https://github.com # Already logged in
-```
-
-### Exposing Local Dev Servers
-
-```bash
-browser-use tunnel 3000 # → https://abc.trycloudflare.com
-browser-use open https://abc.trycloudflare.com # Browse the tunnel
-```
-
-## Multiple Browsers
-
-For subagent workflows or running multiple browsers in parallel, use `--session NAME`. Each session gets its own browser. See `references/multi-session.md`.
-
-## Configuration
-
-```bash
-browser-use config list # Show all config values
-browser-use config set cloud_connect_proxy jp # Set a value
-browser-use config get cloud_connect_proxy # Get a value
-browser-use config unset cloud_connect_timeout # Remove a value
-browser-use doctor # Shows config + diagnostics
-browser-use setup # Interactive post-install setup
-```
-
-Config stored in `~/.browser-use/config.json`.
-
-## Global Options
-
-| Option | Description |
-|--------|-------------|
-| `--headed` | Show browser window |
-| `--profile [NAME]` | Use real Chrome (bare `--profile` uses "Default") |
-| `--cdp-url <url>` | Connect via CDP URL (`http://` or `ws://`) |
-| `--session NAME` | Target a named session (default: "default") |
-| `--json` | Output as JSON |
-| `--mcp` | Run as MCP server via stdin/stdout |
-
-## Tips
-
-1. **Always run `state` first** to see available elements and their indices
-2. **Use `--headed` for debugging** to see what the browser is doing
-3. **Sessions persist** — browser stays open between commands
-4. **CLI aliases**: `bu`, `browser`, and `browseruse` all work
-5. **If commands fail**, run `browser-use close` first, then retry
-
-## Troubleshooting
-
-- **Browser won't start?** `browser-use close` then `browser-use --headed open <url>`
-- **Element not found?** `browser-use scroll down` then `browser-use state`
-- **Run diagnostics:** `browser-use doctor`
-
-## Cleanup
-
-```bash
-browser-use close # Close browser session
-browser-use tunnel stop --all # Stop tunnels (if any)
-```
diff --git a/skills/browser-use/references/cdp-python.md b/skills/browser-use/references/cdp-python.md
deleted file mode 100644
index 46522647f..000000000
--- a/skills/browser-use/references/cdp-python.md
+++ /dev/null
@@ -1,76 +0,0 @@
-# Raw CDP & Python Session Reference
-
-The CLI commands handle most browser interactions. Use `browser-use python` with raw CDP when you need browser-level control the CLI doesn't expose — activating a tab so the user sees it, intercepting network requests, emulating devices, or working with Chrome target IDs directly.
-
-## How the Python session works
-
-`browser-use python "statement"` executes one Python statement per call. Variables persist across calls — set a value in one call, use it in the next.
-
-A `browser` object is pre-injected with sync wrappers for common operations (`browser.goto()`, `browser.click()`, etc.). For anything beyond those, two internals give you full access:
-
-- `browser._run(coroutine)` — run any async coroutine synchronously (60s timeout)
-- `browser._session` — the raw `BrowserSession` with full CDP client access
-
-## Getting a CDP client
-
-```bash
-browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
-```
-
-After this, `cdp` persists across calls. Use `cdp.cdp_client.send.<Domain>.<method>()` for any CDP command and `cdp.session_id` for the session parameter.
-
-## Recipes
-
-### Activate a tab (make it visible to the user)
-
-The CLI's `tab switch` only changes the agent's internal focus — Chrome's visible tab doesn't change. To actually show the user a specific tab:
-
-```bash
-# Get all targets to find the target ID
-browser-use python "targets = browser._session.session_manager.get_all_page_targets()"
-browser-use python "print([(i, t.url) for i, t in enumerate(targets)])"
-
-# Activate target at index 1 so the user sees it
-browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session(target_id=None, focus=False))"
-browser-use python "browser._run(cdp.cdp_client.send.Target.activateTarget(params={'targetId': targets[1].target_id}))"
-```
-
-### List all tabs with target IDs
-
-```bash
-browser-use python "targets = browser._session.session_manager.get_all_page_targets()"
-browser-use python "
-for i, t in enumerate(targets):
- print(f'{i}: {t.target_id[:12]}... {t.url}')
-"
-```
-
-### Run JavaScript and get the result
-
-```bash
-browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
-browser-use python "result = browser._run(cdp.cdp_client.send.Runtime.evaluate(params={'expression': 'document.title', 'returnByValue': True}, session_id=cdp.session_id))"
-browser-use python "print(result['result']['value'])"
-```
-
-### Emulate a mobile device
-
-```bash
-browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
-browser-use python "browser._run(cdp.cdp_client.send.Emulation.setDeviceMetricsOverride(params={'width': 375, 'height': 812, 'deviceScaleFactor': 3, 'mobile': True}, session_id=cdp.session_id))"
-```
-
-### Get cookies via CDP
-
-```bash
-browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
-browser-use python "cookies = browser._run(cdp.cdp_client.send.Network.getCookies(params={}, session_id=cdp.session_id))"
-browser-use python "print(cookies)"
-```
-
-## Tips
-
-- Each `browser-use python` call is one statement. Multi-line strings work for `for` loops and `if` blocks, but you can't mix statements and expressions. Use multiple calls.
-- Variables persist: set `cdp = ...` in one call, use `cdp` in the next.
-- The `browser._run()` bridge has a 60-second timeout. For long operations, increase it or use the async internals directly.
-- All CDP domains are available via `cdp.cdp_client.send.<Domain>.<method>()`. See the [Chrome DevTools Protocol docs](https://chromedevtools.github.io/devtools-protocol/) for the full API.
diff --git a/skills/browser-use/references/multi-session.md b/skills/browser-use/references/multi-session.md
deleted file mode 100644
index 1679b5bd3..000000000
--- a/skills/browser-use/references/multi-session.md
+++ /dev/null
@@ -1,92 +0,0 @@
-# Multiple Browser Sessions
-
-## Why use multiple sessions
-
-When you need more than one browser at a time:
-- Cloud browser for scraping + local Chrome for authenticated tasks
-- Two different Chrome profiles simultaneously
-- Isolated browser for testing that won't affect the user's browsing
-- Running a headed browser for debugging while headless runs in background
-
-## How sessions are isolated
-
-Each `--session NAME` gets:
-- Its own daemon process
-- Its own Unix socket (`~/.browser-use/{name}.sock`)
-- Its own PID file and state file
-- Its own browser instance (completely independent)
-- Its own tab ownership state (multi-agent locks don't cross sessions)
-
-## The `--session` flag
-
-Must be passed on every command targeting that session:
-
-```bash
-browser-use --session work open <url> # goes to 'work' daemon
-browser-use --session work state # reads from 'work' daemon
-browser-use state # goes to 'default' daemon (different browser)
-```
-
-If you forget `--session`, the command goes to the `default` session. This is the most common mistake — you'll interact with the wrong browser.
-
-## Combining sessions with browser modes
-
-```bash
-# Session 1: cloud browser
-browser-use --session cloud cloud connect
-
-# Session 2: connect to user's Chrome
-browser-use --session chrome connect
-
-# Session 3: headed Chromium for debugging
-browser-use --session debug --headed open <url>
-```
-
-Each session is fully independent. The cloud session talks to a remote browser, the chrome session talks to the user's Chrome, and the debug session manages its own Chromium — all running simultaneously.
-
-## Listing and managing sessions
-
-```bash
-browser-use sessions
-```
-
-Output:
-```
-SESSION PHASE PID CONFIG
-cloud running 12345 cloud
-chrome running 12346 cdp
-debug ready 12347 headed
-```
-
-PHASE shows the daemon lifecycle state: `initializing`, `ready`, `starting`, `running`, `shutting_down`, `stopped`, `failed`.
-
-```bash
-browser-use --session cloud close # close one session
-browser-use close --all # close every session
-```
-
-## Common patterns
-
-**Cloud + local authenticated:**
-```bash
-browser-use --session scraper cloud connect
-browser-use --session scraper open https://example.com
-# ... scrape data ...
-
-browser-use --session auth --profile "Default" open https://github.com
-browser-use --session auth state
-# ... interact with authenticated site ...
-```
-
-**Throwaway test browser:**
-```bash
-browser-use --session test --headed open https://localhost:3000
-# ... test, debug, inspect ...
-browser-use --session test close # done, clean up
-```
-
-**Environment variable:**
-```bash
-export BROWSER_USE_SESSION=work
-browser-use open <url> # uses 'work' session without --session flag
-```
diff --git a/tests/ci/test_browser_use_skill_install_docs.py b/tests/ci/test_browser_use_skill_install_docs.py
new file mode 100644
index 000000000..06e9687d5
--- /dev/null
+++ b/tests/ci/test_browser_use_skill_install_docs.py
@@ -0,0 +1,124 @@
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+BROWSER_USE_REPO_SKILL_URL = 'https://raw.githubusercontent.com/browser-use/browser-use/main/skills/browser-use/SKILL.md'
+
+
+def test_docs_install_browser_use_skill_from_package_alias():
+ readme = (ROOT / 'README.md').read_text(encoding='utf-8')
+ cli_readme = (ROOT / 'browser_use' / 'skill_cli' / 'README.md').read_text(encoding='utf-8')
+ combined = readme + '\n' + cli_readme
+
+ assert 'browser-use skill install' in combined
+ assert 'mkdir -p ~/.claude/skills/browser-use' not in combined
+ assert 'uv run --with "browser-use[browser-harness]" python -c' not in combined
+ assert 'from browser_use.skills import browser_use_skill_text' not in combined
+ assert BROWSER_USE_REPO_SKILL_URL not in combined
+ assert 'raw.githubusercontent.com/browser-use/browser-harness/main/SKILL.md' not in combined
+
+
+def test_browser_use_repo_does_not_carry_a_copied_browser_harness_skill():
+ assert not (ROOT / 'skills' / 'browser-use' / 'SKILL.md').exists()
+ assert not (ROOT / 'scripts' / 'sync_browser_use_skill.py').exists()
+
+
+def test_browser_use_skill_alias_reads_browser_harness_package(monkeypatch, tmp_path):
+ package_dir = tmp_path / 'browser_harness'
+ package_dir.mkdir()
+ (package_dir / '__init__.py').write_text('', encoding='utf-8')
+ (package_dir / 'SKILL.md').write_text(
+ '---\nname: browser-harness\ndescription: "Always use browser-harness."\n---\n\n# browser-harness\n',
+ encoding='utf-8',
+ )
+ monkeypatch.syspath_prepend(str(tmp_path))
+
+ from browser_use.skills import browser_use_skill_text
+
+ assert browser_use_skill_text() == (
+ '---\n'
+ 'name: browser-use\n'
+ 'description: "Direct browser control via CDP for web interaction: automation, scraping, testing, screenshots, and site/app work."\n'
+ '---\n\n'
+ '# Browser Use\n'
+ )
+
+
+def test_browser_use_skill_cli_installs_browser_harness_package_skill(tmp_path):
+ package_dir = tmp_path / 'browser_harness'
+ package_dir.mkdir()
+ (package_dir / '__init__.py').write_text('', encoding='utf-8')
+ (package_dir / 'SKILL.md').write_text('---\nname: browser-harness\n---\n\n# Browser Harness\n', encoding='utf-8')
+
+ home = tmp_path / 'home'
+ env = os.environ.copy()
+ env['HOME'] = str(home)
+ env['PYTHONPATH'] = os.pathsep.join(part for part in (str(tmp_path), str(ROOT), env.get('PYTHONPATH', '')) if part)
+
+ result = subprocess.run(
+ [sys.executable, '-m', 'browser_use.skill_cli.main', 'skill', 'install'],
+ cwd=ROOT,
+ env=env,
+ capture_output=True,
+ text=True,
+ timeout=10,
+ )
+
+ assert result.returncode == 0, result.stderr
+ installed = home / '.claude' / 'skills' / 'browser-use' / 'SKILL.md'
+ assert installed.read_text(encoding='utf-8') == (
+ '---\n'
+ 'name: browser-use\n'
+ 'description: "Direct browser control via CDP for web interaction: automation, scraping, testing, screenshots, and site/app work."\n'
+ '---\n\n'
+ '# Browser Use\n'
+ )
+
+
+def test_browser_use_skill_cli_uses_real_subcommand_index_when_session_is_named_skill(tmp_path):
+ package_dir = tmp_path / 'browser_harness'
+ package_dir.mkdir()
+ (package_dir / '__init__.py').write_text('', encoding='utf-8')
+ (package_dir / 'SKILL.md').write_text('---\nname: browser-harness\n---\n\n# browser-harness\n', encoding='utf-8')
+
+ env = os.environ.copy()
+ env['HOME'] = str(tmp_path / 'home')
+ env['PYTHONPATH'] = os.pathsep.join(part for part in (str(tmp_path), str(ROOT), env.get('PYTHONPATH', '')) if part)
+
+ result = subprocess.run(
+ [sys.executable, '-m', 'browser_use.skill_cli.main', '--session', 'skill', 'skill', 'show'],
+ cwd=ROOT,
+ env=env,
+ capture_output=True,
+ text=True,
+ timeout=10,
+ )
+
+ assert result.returncode == 0, result.stderr
+ assert result.stdout == (
+ '---\n'
+ 'name: browser-use\n'
+ 'description: "Direct browser control via CDP for web interaction: automation, scraping, testing, screenshots, and site/app work."\n'
+ '---\n\n'
+ '# Browser Use\n'
+ )
+
+
+def test_browser_use_cli_does_not_treat_session_value_named_skill_as_skill_command(tmp_path):
+ env = os.environ.copy()
+ env['HOME'] = str(tmp_path / 'home')
+ env['PYTHONPATH'] = os.pathsep.join(part for part in (str(ROOT), env.get('PYTHONPATH', '')) if part)
+
+ result = subprocess.run(
+ [sys.executable, '-m', 'browser_use.skill_cli.main', '--session', 'skill', 'sessions'],
+ cwd=ROOT,
+ env=env,
+ capture_output=True,
+ text=True,
+ timeout=10,
+ )
+
+ assert result.returncode == 0, result.stderr
+ assert 'No active sessions' in result.stdout