# Browser Agent

> Use when browser work needs multiple Chrome DevTools Protocol phases: security/cookie/storage audits, network analysis, DOM inspection, coverage, workers, device emulation, or multi-step automation. Spawn the browser profile through the unified agent tool and manage follow-ups through the same facade. For one CDP operation, call chromeDebug directly.

- Skill: `bgauryy/browser-agent` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add bgauryy/browser-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bgauryy/browser-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: bgauryy (https://skillmd.com/u/bgauryy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bgauryy/browser-agent

---


# Browser Agent

Choose the smallest workflow that can produce the required evidence. The skill owns that judgment; `agent` and `chromeDebug` own deterministic execution.

## Choose the execution path

| Need | Action |
|---|---|
| One screenshot, console check, DOM query, or scheme call | Call `chromeDebug` directly |
| Multiple dependent CDP phases or user-driven follow-ups | Spawn `agent` with `profile:"browser"` |

Do not spawn a worker merely to wrap one deterministic browser operation.

## Spawn

Give the browser worker a bounded packet with explicit scope, acceptance, and return requirements. The profile routes the task to relevant CDP domains, runs the configured initial analysis, and starts the worker.

```
agent({queries:[{
  reasoning: "The audit needs dependent security, storage, and network phases.",
  type: "spawn",
  profile: "browser",
  name: "browser-audit",
  task: "Goal: audit the login flow\nContext: inspect https://example.com\nScope: security headers, cookies, storage, and login traffic\nOwnership: browser inspection only; do not modify repository files\nAcceptance: report evidence for every requested surface\nReturn: emit [FINDING], [ACTION], and terminal [DONE], [BLOCKED], or [FAILED] lines",
  url: "https://example.com",
  port: 9222,
  launch: false,
  runNow: true
}]})
→ { agentId: "abc123…" }
```

Use `launch:true` only when the tool should start Chrome. `runNow:true` performs the routed initial analysis before the worker starts; use `runNow:false` when an existing authenticated or interactive state must be preserved for the worker.

Spawn first. Lifecycle operations that reference the returned `agentId` must be separate calls.

## Multi-turn lifecycle

```
agent({queries:[{reasoning:"Collect the current browser-worker snapshot.", type:"wait", agentId:"abc123…"}]})
agent({queries:[{reasoning:"Queue the next audit phase.", type:"message", agentId:"abc123…", delivery:"followUp", message:"Now inspect /api/login and compare its cookie behavior."}]})
agent({queries:[{reasoning:"Inspect the complete retained result.", type:"inspect", agentId:"abc123…", full:true}]})
agent({queries:[{reasoning:"Release the completed browser worker.", type:"kill", agentId:"abc123…", remove:true}]})
```

Use `inspect` without `agentId` to list all workers. `wait` returns the current transcript snapshot; repeat it only when fresh output is expected. Use `steer` when the current direction must change before the worker's next model step. Use `message` with `delivery:"followUp"` to queue the next phase.

## Output protocol

The browser worker prefixes evidence lines:

| Prefix | Meaning |
|---|---|
| `[STATUS] …` | Current activity |
| `[FINDING] …` | Specific issue or discovery |
| `[ACTION] …` | Recommended next step |
| `[METRIC] …` | Measurement such as size, count, percentage, or duration |
| `[SCREENSHOT] path` | Absolute screenshot path |
| `[BLOCKED] reason` | Input or external state is required |
| `[FAILED] reason` | Objective cannot be completed; partial findings should follow |
| `[DONE] summary` | The bounded objective is complete |

Relay findings and actions with their evidence. A terminal prefix is a worker claim, not proof: compare it with the acceptance criteria and inspect full output when the result matters.

If the worker emits `[BLOCKED]`, resolve the missing input and send it through `agent` with `type:"message"`. Always kill and remove the worker after collecting the final result.

## Long-running work

For monitors or user-interaction flows, use short snapshot checks while other useful work continues:

```
agent({queries:[{reasoning:"Check browser-monitor progress.", type:"inspect", agentId:"abc123…"}]})
```

If a worker is stuck well beyond the expected duration, interrupt its current turn without destroying the process, inspect the result, then either redirect or remove it:

```
agent({queries:[{reasoning:"Interrupt the unresponsive browser turn.", type:"abort", agentId:"abc123…", full:true}]})
agent({queries:[{reasoning:"Inspect the interrupted browser worker.", type:"inspect", agentId:"abc123…", full:true}]})
agent({queries:[{reasoning:"Release the interrupted browser worker.", type:"kill", agentId:"abc123…", remove:true}]})
```

## Parallel browser lanes

Parallelize only independent inspections. Use separate debugging ports and give each worker disjoint scope. Multiple spawn queries may share one call; collect and reconcile every result before finalizing.

```
agent({queries:[
  {reasoning:"Run the independent security lane.", type:"spawn", profile:"browser", name:"security-lane", task:"Goal: audit browser security\nContext: inspect https://example.com\nScope: headers, cookies, and storage\nOwnership: read-only browser inspection on port 9222\nAcceptance: evidence for each security surface\nReturn: findings and terminal status", url:"https://example.com", port:9222},
  {reasoning:"Run the independent performance lane.", type:"spawn", profile:"browser", name:"performance-lane", task:"Goal: audit browser performance\nContext: inspect https://example.com\nScope: web vitals, heap, layout, and script metrics\nOwnership: read-only browser inspection on port 9223\nAcceptance: measured evidence for each metric family\nReturn: metrics, actions, and terminal status", url:"https://example.com", port:9223}
]})
```

## `chromeDebug` scheme guide

| Scheme | Use it for |
|---|---|
| `debug` | Exceptions, HTTP errors, blocked requests, DOM state, and screenshot |
| `network` | Requests, responses, and cookie flags |
| `security` | Security headers, cookie flags, and sensitive storage keys |
| `storage` | Cookies, web storage, IndexedDB, Cache Storage, and quota |
| `accessibility` | Accessibility tree and common labeling/structure gaps |
| `workers` | Web workers and service-worker lifecycle |
| `performance` | Web vitals, heap, layout, and script metrics |
| `css-coverage` / `js-coverage` | CSS and JavaScript usage coverage |
| `emulate` | Viewport, network, geolocation, and media emulation |
| `intercept` | Request capture or mocking |
| `screenshot` | PNG, JPEG, WebP, or PDF capture |
| `raw` | A specific `Domain.Method` call |

Inspect the live `chromeDebug` tool schema before constructing a low-level call. For protocol details, use [references/CDP_QUICK_REF.md](references/CDP_QUICK_REF.md).

## Recovery

| Signal | Response |
|---|---|
| Chrome is not running | Spawn with `launch:true`, or ask the user to start Chrome |
| Authentication is required | Ask the user to log in, then send `continue` to the worker |
| Worker reports failure | Inspect full history, remove it, correct the packet, and spawn a replacement only if needed |
| Worker is unresponsive | `abort` → `inspect` → redirect or `kill` |