browser-automation-skill

Drive a real browser from Claude Code via four routed tools (chrome-devtools-mcp / playwright-cli / playwright-lib / obscura). 42 verbs covering site/session/credential management, navigation, snapshot+ref-based interaction, capture pipelines (console/network/screenshot/Lighthouse), declarative flow runner with replay+diff, a per-archetype memory cache (browser-do) that lets agents skip LLM ref-resolution on repeat actions, and per-schema state migration tooling (browser-migrate).

Verbs

Site + session + credential management

Navigation + interaction

Capture + extract + audit

Flow runner

Telemetry / audit / tuning (browser-stats)

Per-action events are emitted automatically by open, click, fill,
snapshot, and extract (covering all 4 routes). Adding emission to a new
verb = 3 lines (see `references/browser-stats-cheatsheet.md`).
Schema: `references/stats-schema.json` — follows
OpenInference + OTel GenAI v1.40 conventions for forward-compat with
Langfuse/Phoenix/Jaeger exporters.

Memory cache (browser-do)

Schema migration (browser-migrate)

Migration & schema evolution

Skill state (~/.browser-skill/) is versioned per-schema (versions.json). Each schema (sites / sessions / credentials / captures / baselines / memory / config) carries its own schema_version; migrating one doesn't touch the others. When the skill ships a schema bump, it lands a migrator under scripts/lib/migrators/<schema>/v<from>_to_<to>.sh; the migrator becomes pending on every machine until the user runs browser-migrate run.

Key invariants:

• Doctor never auto-migrates. It only surfaces pending count as a warn: line; user runs browser-migrate run explicitly.
• Atomic-swap + automatic backup. Each migrated file is backed up to backups/<schema>/<basename>.bak.v<prior_version> (mode 0600) before the migrator runs. JSON validation via jq -e . precedes the version bump; failure restores from backup.
• Manual rollback. Single-step rollback --schema NAME restores from the newest backup. Multi-version chains require multiple invocations.
• Lock file (~/.browser-skill/.migrate.lock) prevents concurrent runs; stale PID auto-cleared.

Today's only real migration is the no-op memory v1_to_v2 identity bump (bumps schema_version from 1 to 2; no data shape change). Future per-schema migrators land case-by-case (~30 LOC + ~3 bats per new migrator).

${CLAUDE_SKILL_DIR} is the absolute path Claude Code injects when invoking the skill — symlink under ~/.claude/skills/.

${CLAUDE_SKILL_DIR} is the absolute path that Claude Code injects when it
invokes the skill — it points at the symlink under ~/.claude/skills/. Use it
in command examples so they work whether the user installed at --user or
--project scope.

Agent-workflow recipes (end-to-end command sequences)

See `references/recipes/agent-workflows/` for tutorial-shaped walkthroughs:

• `login-then-scrape.md` — first task: register site, capture session, bulk scrape
• `incremental-pattern-discovery.md` — passive observation → propose → cache-hit loop end-to-end
• `flow-record-and-replay.md` — capture a manual interaction, replay, diff against baseline
• `cache-driven-bulk-operation.md` — 50+ actions at zero LLM tokens (ROI proof)

For pattern recipes (codified discipline: privacy-canary, path-security, cache-write-security, etc.) see `references/recipes/`.

Tools

The skill routes verbs to one of these underlying tools (precedence is decided
by router.sh; see routing heuristics
for the rules):

Before running anything

If doctor reports ~/.browser-skill missing, run ./install.sh (or
./install.sh --with-hooks for the credential-leak blocker).

doctor also surfaces (advisory; never fails):

• Pending schema migrations — warn: N pending migration(s) — run 'browser-migrate check' for details.
  Doctor never auto-migrates (MIG4 invariant from Phase 10 design); apply via browser-migrate run.
• Memory cache hit-rate — ok: memory cache hit rate: X% (H/T events) once
  browser-do --intent has run at least once (writer landed in Phase 11 v2 part 1;
  events.jsonl is lazy-created mode 0600 inside the mode-0700 memory dir).
  Cheapest daily ROI signal: high hit-rate = the cache is paying for itself; low/empty = repetition isn't compounding yet.

Output contract

Every verb prints zero or more streaming JSON lines, then ends with a
single-line JSON summary. Parse with jq; route on .status (ok,
partial, error, empty, aborted).

$ bash scripts/browser-doctor.sh | tail -1 | jq .
{"verb":"doctor","tool":"none","why":"health-check","status":"ok","problems":0,"duration_ms":42}

Storage layout

~/.browser-skill/                       # mode 0700
├── version                              # schema marker
├── config.json                          # mode 0600; retention thresholds
├── current                              # current site name (mode 0600, [personal])
├── baselines.json                       # mode 0600; named baseline registry (Phase 9)
├── sites/    <name>.json + .meta.json   # mode 0600 ([shareable])
├── sessions/ <name>.json + .meta.json   # mode 0600 ([PERSONAL — gitignored])
├── credentials/                         # Phase 5 (keychain / libsecret / plaintext)
├── captures/  <NNN>/                    # Phase 7 (snapshot.json, console.json, network.har, steps.jsonl, meta.json)
└── memory/    <site>/                   # Phase 11 ([PERSONAL — gitignored])
    ├── patterns.json                    # mode 0600; URL pattern → archetype-id
    └── archetypes/<id>.json             # mode 0600; cached interactions per archetype

Roadmap

See docs/superpowers/specs/2026-04-27-browser-automation-skill-design.md for
the full design and docs/superpowers/plans/ for phase plans.