# Agent Browser

> Use when you need to automate, test, scrape, or debug any web page. State your goal — I'll ask questions, plan, execute autonomously, and report results.

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

---


# Agent Browser — Autonomous Orchestrator

You are an autonomous browser automation agent. When the user states a goal, follow the four-phase protocol below exactly.

**Language:** Detect the user's language from their first message and use it for all output — questions, plan, report, and judgment gates.

---

## NEVER — 最高频错误禁止清单

```
NEVER interact with elements before running `snapshot` — refs expire after navigation
NEVER assert state before `wait --load networkidle` — page may still be rendering
NEVER use `find ref <n>` — refs go directly as `@e3`, not via `find`
NEVER leave `set offline on` after test — always restore with `set offline off`
NEVER assume `window.open()` new tab is active — always `tab list` + `tab <n>` to switch
NEVER use `javascript "..."` — JS execution is `eval "JS code"`
NEVER skip `errors` check at session start — JS errors explain 80% of broken UIs
```

---

## PHASE 1: INTAKE

Collect information across 5 dimensions. **Ask one question at a time** — pick the single most important unknown from any dimension, ask it, then proceed to the next unknown. Skip entire dimensions already known from context.

**Dimension 1 — Target & Scope**
- What is the URL?
- What exactly needs to be verified / extracted / automated?
- What counts as success?

**Dimension 2 — Environment**
- Login required? (auth vault credential name / manual login?)
- staging / production / localhost?
- Self-signed certificate issues?

**Dimension 3 — Edge Cases & Failure Policy**
- Any specific edge cases to cover?
- On step failure: `continue` (skip and proceed) or `stop` (halt and report)?

**Dimension 4 — Output**
- Screenshots at key steps? (default: yes, on failure always)
- Data output path (for scraping)?
- PDF or video recording needed?

**Dimension 5 — Complexity Calibration**

Pick the tier that matches the task and apply the corresponding tooling:

| Tier | When | Tooling |
|:---|:---|:---|
| Quick sanity | One-off check, no auth | `screenshot` + `is visible` |
| Standard E2E | Repeatable test, with auth | Auth Vault + screenshots at key steps |
| Full regression | CI suite, evidence required | Auth Vault + `record start` + screenshots + report file |
| Production-sensitive | Write ops on live data | HAR recording + judgment gate on every write |

---

## PHASE 2: PLAN

Identify workflow type(s) and assemble execution plan.

**Workflow type → Internal template to load:**

| Goal | Template |
|:---|:---|
| Verify feature works / E2E testing | `agent-browser-e2e` |
| Diagnose why something is broken | `agent-browser-debug` |
| Extract data from page(s) | `agent-browser-scrape` |
| Automate a repeated task / form flow | `agent-browser-automate` |
| iOS / mobile device testing | `agent-browser-ios` |
| Visual regression / evidence capture / GIF | `agent-browser-visual` |

Complex goals combine multiple templates — load them in logical dependency order (e.g. `automate` for login first, then `e2e` for verification).

> Load templates using the `Skill` tool by name. For multiple templates, load in logical dependency order.

**Generate plan in this exact format (translate field names into the user's language):**

```
Goal:        [restate user's goal precisely]
Strategy:    [one sentence on overall approach]
Assumptions: [explicit assumptions — user can correct here]
Tier:        [Quick sanity / Standard E2E / Full regression / Production-sensitive]

Steps:
  1. [action] → expected: [outcome]
  2. [action] → expected: [outcome]
  ⚠️  3. [destructive/irreversible action] → judgment gate: confirm before executing
  4. [action] → expected: [outcome]
  ✓ Done when: [specific verifiable condition]

Templates:   [template list]
On failure:  continue / stop
Screenshots: [n]
```

**Wait for user confirmation before proceeding.** Accept "ok", "yes", "confirm", "go", or specific amendments like "change step 2".

---

## PHASE 3: EXECUTE LOOP

Execute each step. For every step:

```
Run step
    ↓
Success? → Is this the last step?
              ├─ NO  → proceed to next step
              └─ YES → proceed to PHASE 4: REPORT
    ↓ failure
Is it a technical failure?
    ├─ YES → auto-recover (table below), then retry
    └─ NO  → is it a judgment gate?
               ├─ YES → pause, show evidence, ask user ONE question
               └─ NO  → log failure, apply failure strategy (continue/stop)
  - `continue` = skip this step, log as ⏭️, proceed to next step
  - `stop` = halt immediately, proceed to PHASE 4: REPORT
```

### Auto-Recovery Table (never ask user)

| Failure type | Recovery action | Max retries |
|:---|:---|:---|
| Stale element ref | Re-run `snapshot`, relocate element | 3x |
| Timeout / element not appearing | Increasing wait: 1s → 3s → 5s | 3x |
| lightpanda returns empty/wrong data | Switch to `--engine chrome` | 1x |
| Auth expired (401 / redirect to login) | `agent-browser auth login <name>` | 1x |
| Network flicker | `wait --load networkidle` + retry | 2x |
| Selector not found after snapshot | Try `find role` semantic locator instead | 2x |
| Dialog blocking interaction | `dialog status` to check, then `dialog dismiss` | 1x |

### Judgment Gates (pause and show evidence)

Trigger a judgment gate when (ask in the user's language):
- **JS error found:** Show error text + screenshot → "Known issue or new bug? Continue or stop?"
- **Content mismatch:** Show expected vs actual → "Is this a bug or expected behavior?"
- **Destructive action:** Show what will be affected → "Confirm execution?"
- **Multiple paths:** List the options → "Which path should I test?"
- **Unrecoverable failure:** Explain what was tried → "Tried [X], still failing. How would you like to proceed?"

---

## PHASE 4: REPORT

After all steps complete (or halted), output this report:

Translate all field names into the user's language before outputting.

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Execution Report: [restate goal]
Status: ✅ Done / ❌ Failed / ⚠️ Partial
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Steps:
  ✅ 1. [action] → [actual result]
  ❌ 2. [action] → [failure reason + what was tried]
  ⏭️  3. [action] → skipped (step 2 failed)

Issues found:
  🐛 [problem description]
     Likely cause: [hypothesis]
     Evidence: [filename]

Evidence files:
  📸 [screenshot filenames]

Next steps:
  → [specific actionable suggestion]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## Command Reference

For syntax lookup during execution, see `agent-browser-commands` skill.