agent-browser
Browser automation for web testing, form filling, screenshots, and data extraction. Ref-based workflow with best practices for reliable automation.
What this skill does
# Browser Automation with agent-browser Automate browser interactions using a ref-based workflow. Navigate, snapshot, interact, repeat. ## Installation ```shell npm install -g agent-browser agent-browser install # Download Chromium agent-browser install --with-deps # Linux: install system deps ``` ## Quick Start ```shell agent-browser open <url> # Navigate to page agent-browser snapshot -i # Get interactive elements with refs agent-browser click @e1 # Click element by ref agent-browser fill @e2 "text" # Fill input by ref agent-browser close # Close browser ``` ## Core Workflow 1. **Navigate**: `agent-browser open <url>` 2. **Snapshot**: `agent-browser snapshot -i` (returns elements with refs like `@e1`, `@e2`) 3. **Interact**: Use refs from the snapshot 4. **Re-snapshot**: After navigation or significant DOM changes --- ## Command Reference ### Navigation ```shell agent-browser open <url> # Navigate to URL agent-browser back # Go back agent-browser forward # Go forward agent-browser reload # Reload page agent-browser close # Close browser ``` ### Snapshot (Page Analysis) ```shell agent-browser snapshot # Full accessibility tree agent-browser snapshot -i # Interactive elements only (recommended) agent-browser snapshot -c # Compact output agent-browser snapshot -d 3 # Limit depth to 3 agent-browser snapshot -s "#main" # Scope to selector (large pages) ``` ### Interactions (Use @refs) ```shell agent-browser click @e1 # Click agent-browser dblclick @e1 # Double-click agent-browser fill @e2 "text" # Clear and type agent-browser type @e2 "text" # Type without clearing agent-browser press Enter # Press key agent-browser press Control+a # Key combination agent-browser hover @e1 # Hover agent-browser check @e1 # Check checkbox agent-browser uncheck @e1 # Uncheck checkbox agent-browser select @e1 "value" # Select dropdown option agent-browser scroll down 500 # Scroll page agent-browser scrollintoview @e1 # Scroll element into view agent-browser drag @e1 @e2 # Drag from source to target agent-browser upload @e1 file.pdf # Upload file to input ``` ### Get Information ```shell agent-browser get text @e1 # Get element text agent-browser get value @e1 # Get input value agent-browser get html @e1 # Get element HTML agent-browser get attr @e1 href # Get attribute value agent-browser get title # Get page title agent-browser get url # Get current URL ``` ### State Checking (Assertions) ```shell agent-browser is visible @e1 # Check if visible agent-browser is enabled @e1 # Check if enabled agent-browser is checked @e1 # Check if checked ``` ### Screenshots ```shell agent-browser screenshot # Screenshot to stdout agent-browser screenshot path.png # Save to file agent-browser screenshot --full # Full page screenshot ``` ### Wait ```shell agent-browser wait @e1 # Wait for element agent-browser wait 2000 # Wait milliseconds (avoid) agent-browser wait --text "Done" # Wait for text to appear agent-browser wait --load networkidle # Wait for network idle ``` ### Semantic Locators (Alternative to Refs) ```shell agent-browser find role button click --name "Submit" agent-browser find text "Sign In" click agent-browser find label "Email" fill "[email protected]" ``` ### Sessions (Parallel Browsers) ```shell agent-browser --session test1 open site-a.com agent-browser --session test2 open site-b.com agent-browser session list ``` ### State Management ```shell agent-browser state save auth.json # Save auth/cookies agent-browser state load auth.json # Restore state ``` ### Debugging ```shell agent-browser open example.com --headed # Show browser window agent-browser console # View console messages agent-browser errors # View page errors ``` ### Viewport & Emulation ```shell agent-browser set viewport 1920 1080 # Set viewport size agent-browser set device "iPhone 14" # Emulate device agent-browser set media dark # Emulate dark mode agent-browser set geo 37.7749 -122.4194 # Set geolocation agent-browser set offline on # Enable offline mode agent-browser set offline off # Disable offline mode ``` ### Storage & Cookies ```shell agent-browser cookies # List all cookies agent-browser cookies set name value # Set cookie agent-browser cookies clear # Clear all cookies agent-browser storage local # List localStorage agent-browser storage local get key # Get localStorage item agent-browser storage local set key val # Set localStorage item agent-browser storage session # List sessionStorage ``` ### Network Interception ```shell agent-browser network requests # List network requests agent-browser network route "**/api/*" # Intercept matching URLs agent-browser network route "**/api/*" --abort # Block requests agent-browser network route "**/api/*" --body '{"mock":true}' # Mock response ``` ### Headers & Auth ```shell agent-browser open api.example.com --headers '{"Authorization": "Bearer token"}' agent-browser set headers '{"X-Custom": "value"}' ``` ### JSON Output ```shell agent-browser snapshot -i --json # Machine-readable output agent-browser get text @e1 --json # For programmatic parsing ``` --- ## Best Practices ### Snapshots - MUST: Re-snapshot after any navigation or DOM mutation - MUST: Use `snapshot -i` (interactive only) to reduce noise - MUST: Re-snapshot after clicks that trigger page changes - NEVER: Cache refs across page navigations—refs are invalidated - NEVER: Assume refs persist after form submissions or route changes ### Selectors - SHOULD: Prefer `@refs` from snapshot over semantic locators - MUST: Fall back to semantic locators when refs are unstable (dynamic content) - NEVER: Use brittle CSS selectors or XPath directly - SHOULD: Use `find role` + `--name` for buttons/links when refs fail ### Waits - MUST: Wait for `networkidle` after form submissions - MUST: Use `wait --text "..."` or `wait @ref` for dynamic content - NEVER: Use fixed `wait 2000`—flaky and slow - SHOULD: Set reasonable timeouts; fail fast on missing elements ### Forms - MUST: Use `fill` (clears first) for inputs, not `type` - MUST: Verify submission with `wait --text` or `wait --url` - SHOULD: Snapshot after each step in multi-page flows - MUST: Handle validation errors—check for error text after submit ### State & Auth - MUST: Save auth state after login for reuse (`state save`) - MUST: Load state before navigating to authenticated pages - NEVER: Commit auth state files to version control - SHOULD: Use separate state files per environment (dev/staging/prod) ### Screenshots - MUST: Use `screenshot --full` for pages with scroll - SHOULD: Take screenshots before and after critical actions - MUST: Use explicit file paths in CI/CD pipelines ### Sessions - SHOULD: Use named sessions for parallel browser testing - MUST: Close sessions explicitly when done - NEVER: Mix refs across different sessions ### Error Handling - MUST: Check `errors` output when interactions fail silently - SHOULD: Use `console` to debug JavaScript issues - MUST: Re-snapshot and retry once before failing - SHOULD: Use `--headed` mode when debugging complex flows ### Performance - MUST: Close browser when done (`close`) - SHOULD: Reuse sessions for multiple tests on same domain - NEVER: Open new browser for each small interaction - SHOULD: Use `snapshot -c` (compact) for large pages - SHOULD: Use `snapshot -s "#scope"` to limit snapshot to relevant DOM ### Assertions - MUST: Use `is visible` before interacting with dynamic elements - MUST: Use `is enabled` before clicking buttons that ma
Related in AI Agents
skill-development
IncludedComprehensive meta-skill for creating, managing, validating, auditing, and distributing Claude Code skills and slash commands (unified in v2.1.3+). Provides skill templates, creation workflows, validation patterns, audit checklists, naming conventions, YAML frontmatter guidance, progressive disclosure examples, and best practices lookup. Use when creating new skills, validating existing skills, auditing skill quality, understanding skill architecture, needing skill templates, learning about YAML frontmatter requirements, progressive disclosure patterns, tool restrictions (allowed-tools), skill composition, skill naming conventions, troubleshooting skill activation issues, creating custom slash commands, configuring command frontmatter, using command arguments ($ARGUMENTS, $1, $2), bash execution in commands, file references in commands, command namespacing, plugin commands, MCP slash commands, Skill tool configuration, or deciding between skills vs slash commands. Delegates to docs-management skill for official documentation.
reprompter
IncludedTransform messy prompts into well-structured, effective prompts — single or multi-agent. Use when: "reprompt", "reprompt this", "clean up this prompt", "structure my prompt", rough text needing XML tags and best practices, "reprompter teams", "repromptception", "run with quality", "smart run", "smart agents", multi-agent tasks, audits, parallel work, anything going to agent teams. Don't use when: simple Q&A, pure chat, immediate execution-only tasks. See "Don't Use When" section for details. Outputs: Structured XML/Markdown prompt, quality score (before/after), optional team brief + per-agent sub-prompts, agent team output files. Success criteria: Single mode quality score ≥ 7/10; Repromptception per-agent prompt quality score 8+/10; all required sections present, actionable and specific.
adaptive-compaction
IncludedAdaptive add-on policy and recovery layer that decides WHEN to compact, prune, snapshot, or fork -- replacing fixed-percent auto-compaction across Claude Code, Codex, and MCP-capable hosts. Trigger on auto-compact timing or damage: "when should I compact", "is it safe to compact now or start a fresh session", "auto-compact fires too early/mid-task", "switching to an unrelated task but the window still has space", "context rot", "answers get worse the longer the session runs", "the agent forgot the plan or my decisions after it summarized", "add a layer on top that manages context without changing the agent", raising autoCompactWindow to give the policy room, or installing/tuning a cross-tool compaction policy or PreCompact hook -- even when "compaction" is never said but the problem is context-window pressure or post-summarization memory loss. Do NOT use to summarize a conversation, build RAG, write a summarization prompt (decides WHEN not HOW), or answer max-context-length trivia.
agent-skill-creator
IncludedCreate cross-platform agent skills from workflow descriptions. Activates when users ask to create an agent, automate a repetitive workflow, create a custom skill, or need advanced agent creation. Triggers on phrases like create agent for, automate workflow, create skill for, every day I have to, daily I need to, turn process into agent, need to automate, create a cross-platform skill, validate this skill, export this skill, migrate this skill. Supports single skills, multi-agent suites, transcript processing, template-based creation, interactive configuration, cross-platform export, and spec validation.
llm-wiki
IncludedUse when building or maintaining a persistent personal knowledge base (second brain) in Obsidian where an LLM incrementally ingests sources, updates entity/concept pages, maintains cross-references, and keeps a synthesis current. Triggers include "second brain", "Obsidian wiki", "personal knowledge management", "ingest this paper/article/book", "build a research wiki", "compound knowledge", "Memex", or whenever the user wants knowledge to accumulate across sessions instead of being re-derived by RAG on every query.
skill-master
IncludedAgent Skills authoring, evaluation, and optimization. Create, edit, validate, benchmark, and improve skills following the agentskills.io specification. Use when designing SKILL.md files, structuring skill folders (references, scripts, assets), ingesting external documentation into skills, running trigger evals, benchmarking skill quality, optimizing descriptions, or performing blind A/B comparisons. Keywords: agentskills.io, SKILL.md, skill authoring, eval, benchmark, trigger optimization.