agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons…

安装

npx skills add EliasOulkadi/shokunin

收录说明

来自 EliasOulkadi/shokunin（112 stars），仓库最近更新 2026-10-05。尚未人工实测。

SKILL.md 原文

# agent-browser

Fast browser automation CLI for AI agents. Chrome/Chromium via CDP with
accessibility-tree snapshots and compact `@eN` element refs.

Install: `npm i -g agent-browser && agent-browser install`

## Workflow

### Step 1: Navigate to a page

```bash
agent-browser goto "https://example.com"
agent-browser wait @e3                           # wait for element to appear
agent-browser html                                # get current DOM snapshot
```

The `goto` command navigates to a URL and waits for the page to load. Use `wait` to ensure specific elements are present before interacting. Always snapshot with `html` after navigation to get fresh `@eN` refs.

### Step 2: Interact with elements

```bash
agent-browser click @e5                           # click element by accessibility ref
agent-browser type @e7 "hello world"              # type into input
agent-browser select @e9 "option-value"           # select dropdown option
agent-browser check @e12                          # toggle checkbox/radio
agent-browser hover @e15                          # hover over element
agent-browser press Enter                         # press keyboard key
agent-browser scroll down 500                     # scroll page by pixels
agent-browser drag @e5 @e20                       # drag element to target
agent-browser upload @e8 "C:\path\to\file.pdf"   # file input upload
```

All interactions use accessibility-tree element references (`@eN`). These are stable within a single page snapshot but invalidate after navigation or DOM mutations.

### Step 3: Extract data or capture evidence

```bash
agent-browser screenshot page.png                 # full-page screenshot
agent-browser screenshot --element @e5 el.png     # element screenshot
agent-browser screenshot --full-page false vp.png # viewport-only screenshot
agent-browser text                                 # visible text content
agent-browser html                                 # full HTML source
agent-browser pdf output.pdf                       # generate PDF
agent-browser console                              # browser console logs
agent-browser network                              # network request log
agent-browser eval "document.querySelector('.price').innerText"  # run JS
agent-browser performance                          # Core Web Vitals metrics
agent-browser accessibility                        # accessibility tree dump
```

### Step 4: Fill and submit forms

```bash
agent-browser goto "https://example.com/login"
agent-browser type @e3 "user@example.com"          # email field
agent-browser type @e5 "password123"               # password field
agent-browser click @e7                            # submit button
agent-browser wait @e10                            # wait for post-login element
agent-browser screenshot logged-in.png             # verify success
```

For complex multi-step forms, screenshot after each step for debugging. Use `agent-browser html` between steps to get updated element refs if the DOM changes.

### Step 5: Handle authentication

```bash
agent-browser vault set example.com "user:pass"    # store encrypted credentials
agent-browser vault get example.com                # retrieve credentials
agent-browser auth login "https://example.com"     # automated OAuth/login flow
agent-browser session save mysession               # save cookies + localStorage
agent-browser session load mysession               # restore session state
agent-browser session list                          # list saved sessions
```

Credentials are encrypted at rest. Sessions persist cookies, localStorage, and IndexedDB across runs. Use sessions to skip repeated login flows.

### Step 6: Verify and debug

```bash
agent-browser console --errors                     # only error-level logs
agent-browser console --since 30s                  # recent console output
agent-browser network --status 4xx,5xx             # failed requests
agent-browser network --host api.example.com       # filter by host
agent-browser cookies                               # inspect cookies
agent-browser eval "document.title"                # run JS in page context
agent-browser performance                          # Core Web Vitals metrics
```

## Common Workflow Patterns

### Navigate and interact

```
agent-browser goto <url>
agent-browser click @e<ref>               # click element by accessibility ref
agent-browser type @e<ref> "text"         # type into element
agent-browser select @e<ref> "option"     # select from dropdown
```

### Extract data

```
agent-browser screenshot <path>           # full page screenshot
agent-browser html                        # get current page HTML
agent-browser text                        # get visible text content
agent-browser pdf <path>                  # generate PDF
```

### Browser state

```
agent-browser console                     # get browser console logs
agent-browser network                     # get network requests
agent-browser cookies                     # get/set cookies
agent-browser session save <name>         # save session state
agent-browser session load <name>         # restore session
```

### Authentication

```
agent-browser vault set <site> <creds>    # store encrypted credentials
agent-browser vault get <site>            # retrieve and auto-fill
agent-browser auth login <url>            # automated login flow
```

## Load specialized workflows

```bash
agent-browser skills get core              # base workflow (always load first)
agent-browser skills get core --full       # full command reference
agent-browser skills get electron          # Electron desktop apps (VS Code, Slack, Discord, Figma)
agent-browser skills get slack             # Slack workspace automation
agent-browser skills get dogfood           # Exploratory testing / QA / bug hunts
agent-browser skills get vercel-sandbox    # Inside Vercel Sandbox microVMs
agent-browser skills get agentcore         # AWS Bedrock AgentCore cloud browsers
agent-browser skills list                  # all available workflows
```

## Error Handling

| Error | Cause | Fix |
|-------|-------|-----|
| Element `@eN` not found | Element removed from DOM or re-rendered | Re-run `agent-browser html` to get fresh refs and retry |
| Element `@eN` not interactable | Element hidden, covered, or disabled | Use `agent-browser html` to check visibility; scroll into view first |
| Page load timeout | Network slow, infinite spinner, or redirect loop | Increase timeout with `--timeout 30000`; check `agent-browser console` for JS errors |
| Navigation failed | Invalid URL, DNS failure, or certificate error | Verify URL format; check network with `agent-browser network` |
| Authentication failed | Expired session, changed credentials, CAPTCHA | Re-login manually with `agent-browser session save`; update vault credentials |
| Browser not found | Chrome/Chromium not installed | Run `agent-browser install` to download compatible Chromium |
| Port already in use | Another instance of agent-browser running | Kill existing process or use `--port <alt>` to pick a different CDP port |
| Screenshot black/empty | Page not fully rendered or GPU issue | Wait for visible element first; try `--full-page false` for viewport only |
| Stale element reference | DOM mutated between snapshot and interaction | Always re-snapshot with `agent-browser html` before interacting |
| Rate limiting / bot detection | Site detects automation | Use `agent-browser session load` with real browser fingerprint; add delays between actions |

## Anti-Patterns

| Pattern | Problem | Fix |
|---------|---------|-----|
| Hardcoding `@eN` refs across pages | Refs change on every navigation | Always snapshot after navigation, never reuse stale refs |
| Clicking without waiting | Element may not be ready | Use `agent-browser wait @eN` before interacting |
| Blindly typing into any field | May type into wrong or readonly field | Verify element type from snapshot, use proper `type`/`select`/`check` |
| Ignoring console errors | Hidden JS failures break interactions | Always check `agent-browser console --errors` after issues |
| Forgetting to save session | Re-authentication needed on every run | `agent-browser session save` after manual login |
| Running without headless mode check | Visual inspection needed for debugging | Use `--headless false` when debugging; screenshot after each step |
| Bulk-extracting without rate limits | Triggering bot protection and IP bans | Add `--delay 500` between actions; respect robots.txt |
| Using XPath or CSS selectors directly | Fragile, breaks on minor DOM changes | Prefer accessibility-tree `@eN` refs; fall back to text content matching |

## Troubleshooting Quick Reference

| Issue | First Command to Run |
|-------|---------------------|
| Element not found | `agent-browser html` |
| Page not loading | `agent-browser console` |
| Auth failing | `agent-browser session load <name>` |
| Weird layout | `agent-browser screenshot debug.png` |
| Network errors | `agent-browser network --status 4xx,5xx` |
| Performance issues | `agent-browser performance` |
| Blank page after goto | `agent-browser console --errors; agent-browser eval "document.readyState"` |
| Click does nothing | `agent-browser html` (check element type, visibility, disabled state) |

## Why agent-browser

- Fast native Rust CLI, not a Node.js wrapper
- Works with any AI agent (Cursor, Claude Code, Codex, Continue, Windsurf, etc.)
- Chrome/Chromium via CDP with no Playwright or Puppeteer dependency
- Accessibility-tree snapshots with element refs for reliable interaction
- Sessions, authentication vault, state persistence, video recording

## Checklist

- [ ] Page loaded and rendered without errors before interacting
- [ ] Selectors use stable attributes (data-testid, aria-label) not dynamic classes
- [ ] Screenshots taken at each meaningful step for debugging
- [ ] Timeout set per-action (default 30s) to avoid indefinite hangs
- [ ] Browser context closed in finally block to prevent orphan processes

## Sources

- Accessibility Tree specification (w3.org/TR/accname-1.2)
- agent-browser CLI (npm: agent-browser)
- Vercel Sandbox microVMs (vercel.com/docs/sandbox)
- AWS Bedrock AgentCore (docs.aws.amazon.com/bedrock)
- Electron CDP support (electronjs.org/docs/latest/api/debugger)

同类技能

• api-and-interface-designGuides stable API and interface design. Use when designing APIs, module boundaries, or any public interface.…
• design-taste-frontendtasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curat…
• understand-chatUse when you need to ask questions about a codebase or understand code using a knowledge graph
• artifacts-builderSuite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web te…
• open-code-review-delegateDelegation mode for open-code-review (OCR). Instead of OCR calling an LLM endpoint, this skill instructs the…
• cognee-cliUse when the user wants to drive cognee from the terminal with cognee-cli — remember/recall/forget/improve m…