/browser-tools

name: browser-tools
license: MIT
compatibility: "Claude Code 2.1.277+. Requires network access."
description: "Safety rules over the upstream agent-browser skill: scraping ethics, auth, request pacing, local URLs. Use for browser automation."
user-invocable: false
metadata:
  owner-agent: "web-research-analyst"
  category: mcp-enhancement
  upstream-skill: agent-browser
  upstream-version-tested: "0.38.1"
  version: "6.1.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "browser, automation, security, scraping-ethics"
allowed-tools: "Read Glob Grep WebFetch WebSearch"

Browser Tools — Security Wrapper

OrchestKit security wrapper for `agent-browser`. **For command reference and usage patterns, use the upstream `agent-browser` skill directly.** This skill adds safety guardrails only.

> **Command docs**: Refer to the upstream `agent-browser` skill for the full command reference (50+ commands: interaction, wait, capture, extraction, storage, semantic locators, tabs, debug, mobile, network, cookies, state, vault).

Upstream coverage (do not restate)

These topics belong to the vendor. Read them at the source; do not copy them back into this skill.

| Topic | First-party source | |-------|--------------------| | CLI command reference, snapshot and ref loop, waits, auth options, eval, config file | `agent-browser` skill · https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md | | Electron and desktop-app automation over CDP (`connect`, `--cdp`, webviews, tabs) | https://github.com/vercel-labs/agent-browser/blob/main/skill-data/electron/SKILL.md | | Slack workspace navigation and extraction recipes | https://github.com/vercel-labs/agent-browser/blob/main/skill-data/slack/SKILL.md | | Running headless in a Vercel Sandbox microVM (deps, snapshots, cron) | `vercel:vercel-sandbox` skill · https://github.com/vercel-labs/agent-browser/blob/main/skill-data/vercel-sandbox/SKILL.md | | Exploratory QA sweep with repro evidence (issue taxonomy, report template) | `dogfood` skill · https://github.com/vercel-labs/agent-browser/blob/main/skill-data/dogfood/SKILL.md | | Named `.localhost` dev URLs | `ork:portless` skill · https://github.com/vercel-labs/portless |

**Our delta over all of the above**: `references/ork-delta.md`, covering what nothing checks any more, polite pacing across sessions, and the local-URL policy.

Decision Tree

# Fallback decision tree for web content
# 1. Try WebFetch first (fast, no browser overhead)
# 2. If empty/partial -> Try Tavily extract/crawl
# 3. If SPA or interactive -> use agent-browser
# 4. If login required -> authentication flow + state save
# 5. If dynamic -> wait @element or wait --text

Local Dev URLs

Use **Portless** (`npm i -g portless`) for stable local dev URLs instead of guessing ports. When Portless is running, navigate to `myapp.localhost` instead of `localhost:3000`. Nothing in OrchestKit blocks local URLs. If the operator turned on the sandbox network allow list, the local host names must be in `allowedDomains`.

# With Portless: stable, named URLs
agent-browser open "https://myapp.localhost"

# Without: fragile port guessing
agent-browser open "http://localhost:3000"  # which app is this?

New in 2026-04 to 2026-09 (agent-browser 0.23 to 0.38.1)

**0.38.1** (bug fix only): recording cursor and mouse-move timing stay synchronized with page content during drags and timed moves.

**0.38.0**, CLI surface confirmed against the installed 0.38.1 binary (`agent-browser --help`, `snapshot --help`, `screenshot --help`, `record --help`, `session --help`, `auth --help`, `agent-browser doctor`): seven additions worth adopting.

• **`snapshot --delta`** returns a full baseline on the first call, then either `unchanged` or a compact structural change (an exact ref/tree-change splice) on every call after. `--full` forces a fresh baseline. Documented behaviour per `snapshot --help`; not exercised end-to-end here (see the Verification note below).
• **`screenshot --if-changed`** (plus `--threshold <0-1>` for a tolerated changed-pixel ratio) skips capturing and re-encoding a screenshot that looks the same as the last one for that tab, and omits the image path from JSON when it skips. Documented behaviour per `screenshot --help`; not exercised end-to-end here.
• **Persistent snapshot refs** survive same-document DOM changes; only replaced elements or a navigation/iframe swap invalidate a ref. Pairs directly with `--delta`, so a step loop no longer needs a full re-snapshot just because something on the page moved.
• **`--human`** (per click/drag) and session **`--input-mode <instant|smooth|human>`** add reproducible curved pointer movement instead of an instant jump, for flows where a site's bot heuristics react to teleporting cursors.
• **`record start/restart`** default to 30 fps (was uncontrolled before), take `--fps 1-60`, and add `--cursor` (animated pointer overlay, video-only, stripped from accessibility snapshots) and `--contact-sheet` (a timestamped PNG of the distinct visual changes during the take).
• **`auth login --no-navigate`** fills an already-open login page after verifying its origin against the saved profile's URL, instead of always navigating there first.
• **WebMCP catalog summaries** now appear on normal `open`/navigation responses (concise, content-bounded, on discovery or change only); full per-tool schemas stay opt-in via `webmcp list <tool>`.

**0.37.0**: `record start`/`restart` capture the active page (not a blank tab) at 30 fps via `Page.startScreencast`; `doctor` reports the ffmpeg encoders needed. WebMCP availability is now advertised in navigation output. New tabs opened via `tab new` or a page click inherit the active session's headers, credentials, user agent, locale, timezone, geolocation, offline mode, routes and init scripts before their first load.

> **Verification note**: `agent-browser doctor` confirmed CLI 0.38.1, a Chrome for Testing 149.0.7827.54 bina