Browser

Browser Automation Skill

This skill provides browser automation capabilities through direct execution of MCP tools. You will execute MCP tools directly based on task-specific instructions from specialization modules.

When to Use This Skill

Activate when the user requests:

• Web browsing or navigation
• Data extraction or web scraping
• Form filling or automation
• E-commerce operations (Amazon, Google Shopping, Walmart)
• Testing or quality assurance
• Screenshot capture and analysis
• Multi-tab workflows

How This Skill Works

1. Detect task type from user request (keywords, intent analysis)
2. Route to specialization module (ECOMMERCE.md, FORMS.md, SCRAPER.md, QA.md, SCREENSHOT_ANALYSIS.md)
3. Follow module instructions to invoke MCP tools directly
4. Preserve tab context for multi-turn workflows
5. Return results with tab metadata for future operations

Task Type Detection

Analyze user request to determine which specialization module to use:

E-Commerce Tasks → ECOMMERCE.md

Trigger keywords: "amazon", "shopping", "price", "product", "reviews", "buy", "purchase", "compare prices", "best deal", "rufus", "cart", "google shopping", "walmart"

Example requests:

• "Search Amazon for wireless headphones under $100"
• "Compare prices for this product on Amazon and Walmart"
• "Find the best value poly strapping kit"
• "What are the reviews saying about this product?"
• "Ask Rufus AI about laptop recommendations"

Action: Follow .claude/skills/browser/ECOMMERCE.md for step-by-step tool invocation instructions

Form Automation → FORMS.md

Trigger keywords: "form", "fill", "submit", "input", "field", "validation", "signup", "register", "contact form"

Example requests:

• "Fill out the contact form on example.com"
• "Discover all forms on this page"
• "Submit the registration form with test data"
• "Analyze the form fields and validation rules"

Action: Follow .claude/skills/browser/FORMS.md - CRITICAL: Never auto-submit without user approval

Web Scraping → SCRAPER.md

Trigger keywords: "scrape", "extract", "data", "table", "pagination", "export", "collect", "gather", "crawl", "pages 1-10"

Example requests:

• "Extract all product data from this page"
• "Scrape the table and export to CSV"
• "Collect data from pages 1-5 with pagination"
• "Get all article titles from this site"

Action: Follow .claude/skills/browser/SCRAPER.md for extraction and export patterns

QA Testing → QA.md

Trigger keywords: "test", "qa", "accessibility", "performance", "audit", "wcag", "a11y", "validate", "check", "analyze", "keyboard navigation"

Example requests:

• "Audit this page for accessibility issues"
• "Run a performance test on example.com"
• "Check WCAG 2.1 compliance"
• "Test keyboard navigation"

Action: Follow .claude/skills/browser/QA.md for testing workflows and report generation

Screenshot Analysis → SCREENSHOT_ANALYSIS.md

Trigger keywords: "screenshot", "analyze screenshot", "visual", "layout", "design consistency", "contrast", "color analysis", "compare screenshots"

Example requests:

• "Analyze these screenshots for accessibility issues"
• "Check the color contrast in this screenshot"
• "Compare design consistency across these screenshots"
• "Generate a visual audit report"

Action: Follow .claude/skills/browser/SCREENSHOT_ANALYSIS.md for analysis workflows

Macro Learning → MACRO_LEARNING.md

Trigger keywords: "learn", "automate this", "create macro", "record", "capture", "demonstrate", "teach you", "how to automate", "save this workflow", "reusable"

Example requests:

• "Can you learn how to do this workflow?"
• "I want to automate this process"
• "Let me show you how to search this site"
• "Create a macro for adding items to cart"
• "Learn how I navigate this form"

Action: Follow .claude/skills/browser/MACRO_LEARNING.md for capturing user demonstrations and creating reusable macros

Generic Browser Operations → Direct Execution

Trigger keywords: "navigate", "go to", "open", "screenshot", "tab", "browse", "visit"

Example requests:

• "Navigate to example.com"
• "Take a screenshot of this page"
• "Create a new tab"
• "List all open tabs"

Action: Use direct MCP tool invocation (see Quick Reference below)

Specialization Module Structure

Each specialization module (ECOMMERCE.md, FORMS.md, etc.) provides:

1. When to use - Trigger keywords and task types
2. Available macros - Site-specific and universal macros for this domain
3. Execution workflows - Step-by-step MCP tool invocation instructions
4. Safety protocols - Critical rules (e.g., never auto-submit forms)
5. Token conservation - Domain-specific tips
6. Troubleshooting - Common errors and solutions

Your role: Read the appropriate module and follow its instructions to invoke MCP tools.

Execution Patterns

Pattern 1: Macro-First Execution

ALWAYS follow this pattern for browser automation tasks:

1. Check site-specific macros first:

   Extract domain from URL (e.g., "amazon.com" from "https://www.amazon.com/...")
   
   Call: mcp__browser__browser_list_macros({
     site: "amazon.com",
     category: "search"  // optional filter
   })
   
   If macro found → Use macro (go to step 3)
   If not found → Check universal macros (go to step 2)
   

2. Check universal macros:

   Call: mcp__browser__browser_list_macros({
     site: "*",
     category: "extraction"  // or relevant category
   })
   
   If macro found → Use macro (go to step 3)
   If not found → Use direct MCP tools (go to step 4)
   

3. Execute macro:

   Call: mcp__browser__browser_execute_macro({
     id: "{macro_id}",
     params: { /* macro-specific parameters */ },
     tabTarget: tabId  // if operating on existing tab
   })
   
   Return result with tab metadata
   

4. Fall back to direct MCP tools:

   Use browser_click, browser_type, browser_get_visible_text, etc.
   Follow token conservation rules (see below)
   

Pattern 2: Tab Creation and Labeling

Always create and label tabs for organized multi-turn workflows:

1. Create tab:
   Call: mcp__browser__browser_create_tab({ url: "https://example.com" })
   Store tabId from result.content.tabId

2. Label tab:
   Call: mcp__browser__browser_set_tab_label({
     tabTarget: tabId,
     label: "descriptive-name"  // e.g., "amazon-search", "form-filling", "scraping-products"
   })

3. Store tab context for future operations:
   amazonTab = 123
   walmartTab = 456

Pattern 3: Multi-Turn Workflow

Preserve tab context across conversation turns:

Turn 1 - User: "Search Amazon for headphones"
You:
  1. Create tab (tabId = 123), label "amazon-search"
  2. Execute search macro or navigate + search
  3. Return results with tab metadata: { tabId: 123, label: "amazon-search", ... }
  4. STORE: amazonTab = 123

Turn 2 - User: "Get more details on the first result"
You:
  1. Use stored tab ID: tabTarget = 123
  2. Execute detail macro or click + extract
  3. Return results with same tab metadata

Pattern 4: Cleanup Before Operations

Always clean interruptions first (cookie consents, modals, popups):

Before main operation:
  1. Check for cleanup macros:
     Call: mcp__browser__browser_list_macros({ site: "*", search: "cookie" })

  2. Execute cleanup:
     Call: mcp__browser__browser_execute_macro({
       id: "smart_cookie_consent",
       tabTarget: tabId
     })

     Call: mcp__browser__browser_execute_macro({
       id: "dismiss_interruptions",
       tabTarget: tabId
     })

  3. Then proceed with main operation

Token Conservation Rules

CRITICAL: Always minimize token usage when executing browser automation.

Rule 1: Avoid browser_snapshot

Problem: Returns massive ARIA tree (10,000+ tokens)

Solution: Use targeted alternatives

❌ DON'T:
Call: mcp__browser__browser_snapshot({ tabTarget: tabId })

✅ DO:
Call: mcp__browser__browser_get_visible_text({
  maxLength: 3000,
  tabTarget: tabId
})

OR use specific queries:
Call: mcp__browser__browser_query_dom({
  selector: "button, a, input",
  limit: 20,
  tabTarget: tabId
})

Rule 2: Use Specialized Macros

Problem: Generic extraction returns too much data

Solution: Use targeted macros

❌ DON'T:
Call: mcp__browser__browser_get_visible_text({ maxLength: 10000 })

✅ DO:
Call: mcp__browser__browser_execute_macro({
  id: "get_interactive_elements",  // Returns only buttons, links, inputs
  tabTarget: tabId
})

OR:
Call: mcp__browser__browser_execute_macro({
  id: "extract_table_data",  // Returns only table data
  tabTarget: tabId
})

Rule 3: Always Truncate Text Extraction

Problem: Full page text wastes tokens

Solution: Always set maxLength

❌ DON'T:
Call: mcp__browser__browser_get_visible_text({ tabTarget: tabId })

✅ DO:
Call: mcp__browser__browser_get_visible_text({
  maxLength: 3000,  // or 5000 for longer pages
  tabTarget: tabId
})

Rule 4: Limit DOM Queries

Problem: Returning 100+ elements wastes tokens

Solution: Always set limit

❌ DON'T:
Call: mcp__browser__browser_query_dom({
  selector: "div",
  tabTarget: tabId
})

✅ DO:
Call: mcp__browser__browser_query_dom({
  selector: "button.primary, a.cta",  // Specific selector
  limit: 10,  // Reasonable limit
  tabTarget: tabId
})

Rule 5: Use Macros for Cleanup

Problem: Manual popup dismissal requires multiple steps

Solution: Use cleanup macros

✅ Efficient:
Call: mcp__browser__browser_execute_macro({
  id: "smart_cookie_consent",
  tabTarget: tabId
})

Call: mcp__browser__browser_execute_macro({
  id: "dismiss_interruptions",
  tabTarget: tabId
})

Tab Context Preservation

Pattern: Create tabs → store IDs → reuse in follow-ups

Tab Creation Workflow

1. User requests browser operation
2. Create tab with descriptive URL
3. Label tab with meaningful name
4. Execute operation
5. Return result with tab metadata
6. Store tab ID for future use

Tab Metadata Format

Always return tab metadata with results:

{
  "tabId": 123,
  "tabLabel": "amazon-search",
  "url": "https://www.amazon.com/s?k=headphones",
  "timestamp": "2025-12-22T11:58:10Z",
  "data": { /* operation results */ }
}

Multi-Tab Scenarios

Scenario 1: Parallel Comparison

User: "Compare prices on Amazon and Walmart"

You:
1. Create Amazon tab (amazonTab = 123)
2. Create Walmart tab (walmartTab = 456)
3. Execute searches in both tabs (use tabTarget parameter)
4. Return results: { amazonTab: 123, walmartTab: 456, comparison: [...] }
5. Store both tab IDs

Follow-up: "Get more details on the Amazon result"
Use tabTarget = 123 (amazonTab)

Scenario 2: Sequential Workflow

User: "Fill out the contact form on example.com"

You:
1. Create tab (formTab = 123)
2. Discover forms (following FORMS.md)
3. Fill fields
4. Generate preview (DO NOT submit)
5. Return preview with tab metadata
6. Store formTab = 123

Follow-up: "Submit the form"
Use tabTarget = 123 (formTab)
Call: mcp__browser__browser_submit_form (ONLY after user approval)

Tab Management Commands

List attached tabs:

Call: mcp__browser__browser_list_attached_tabs()
Returns: Array of { tabId, label, url }

Attach to existing tab:

Call: mcp__browser__browser_attach_tab({ tabId: 123 })
OR
Call: mcp__browser__browser_attach_tab({ autoOpenUrl: "https://example.com" })

Close tab:

Call: mcp__browser__browser_close_tab({ tabId: 123 })

Available Macro Categories

91+ macros organized by category and site:

Universal Macros (40+)

• extraction: get_interactive_elements, extract_table_data, extract_main_content
• form: discover_forms, fill_form_fields, validate_form
• navigation: smart_scroll, wait_for_element, check_page_loaded
• util: smart_cookie_consent, dismiss_interruptions, close_modal
• interaction: safe_click, type_with_validation, select_dropdown

Site-Specific Macros (51)

• Amazon (17 macros): Search, product details, reviews, Rufus AI, cart operations
• Google Shopping (12 macros): Product search, comparison, price tracking
• Walmart (5 macros): Search, product details, reviews
• Upwork (4 macros): Job search, proposal submission
• Fidelity (4 macros): Account navigation, portfolio analysis
• OpenGameArt (3 macros): Asset search, license filtering
• CoinTracker (3 macros): Portfolio tracking, transaction import
• Google (3 macros): Search, results extraction

See detailed documentation:

• .claude/skills/browser/MACROS.md - Universal macros
• .claude/skills/browser/AMAZON_MACROS.md - Amazon-specific
• .claude/skills/browser/GOOGLE_SHOPPING_MACROS.md - Google Shopping
• .claude/skills/browser/WALMART_MACROS.md - Walmart
• (+ 5 more site-specific docs)

Error Handling

Common Errors and Solutions

Error: "No attached tabs"

Solution:
1. List attached tabs: mcp__browser__browser_list_attached_tabs()
2. If none, create and attach: mcp__browser__browser_attach_tab({ autoOpenUrl: "https://example.com" })
3. Retry operation with tabTarget

Error: "Tab not found (ID: 123)"

Solution:
1. List attached tabs to verify tab still exists
2. If tab closed, create new tab
3. Update stored tab ID

Error: "Macro not found"

Solution:
1. List available macros: mcp__browser__browser_list_macros({ site: "domain.com" })
2. Check spelling of macro ID
3. Fall back to direct MCP tools if macro doesn't exist

Error: "Navigation timeout"

Solution:
1. Retry navigation with increased wait time
2. Check if site is accessible
3. Use browser_wait({ time: 5 }) before retrying

Error: "Element not found"

Solution:
1. Use browser_query_dom to verify element exists
2. Try alternative selectors (ID, class, text content)
3. Check if element is in iframe or shadow DOM
4. Wait for dynamic content: browser_wait({ time: 2 })

Error: "Cannot read property of undefined"

Solution:
1. Verify return structure from MCP tool
2. Check that result.content exists before accessing properties
3. Add null checks: tabId = result?.content?.tabId || null

Quick Reference

Generic Browser Operations

Navigate to URL:

Call: mcp__browser__browser_navigate({
  url: "https://example.com",
  tabTarget: tabId  // optional
})

Take screenshot:

Call: mcp__browser__browser_screenshot({
  tabTarget: tabId  // optional
})

Get visible text:

Call: mcp__browser__browser_get_visible_text({
  maxLength: 3000,
  tabTarget: tabId  // optional
})

Click element:

Call: mcp__browser__browser_click({
  element: "Submit button",
  ref: "element-reference-from-snapshot",
  tabTarget: tabId  // optional
})

Type text:

Call: mcp__browser__browser_type({
  element: "Search input",
  ref: "element-reference-from-snapshot",
  text: "query text",
  submit: false,  // or true to press Enter
  tabTarget: tabId  // optional
})

Query DOM:

Call: mcp__browser__browser_query_dom({
  selector: "button.primary",
  limit: 10,
  tabTarget: tabId  // optional
})

Execute macro:

Call: mcp__browser__browser_execute_macro({
  id: "macro_id",
  params: { /* macro-specific */ },
  tabTarget: tabId  // optional
})

Tab Management

Create tab:

Call: mcp__browser__browser_create_tab({
  url: "https://example.com"  // optional
})
Store: tabId = result.content.tabId

Label tab:

Call: mcp__browser__browser_set_tab_label({
  tabTarget: tabId,
  label: "descriptive-name"
})

List tabs:

Call: mcp__browser__browser_list_attached_tabs()

Close tab:

Call: mcp__browser__browser_close_tab({
  tabId: tabId
})

Macro Discovery

List all macros for site:

Call: mcp__browser__browser_list_macros({
  site: "amazon.com"  // or "*" for universal
})

Search macros by category:

Call: mcp__browser__browser_list_macros({
  site: "amazon.com",
  category: "search"  // or "extraction", "form", etc.
})

Search macros by keyword:

Call: mcp__browser__browser_list_macros({
  site: "*",
  search: "cookie"  // finds "smart_cookie_consent"
})

Execution Workflow Summary

1. User makes browser automation request
2. Detect task type (keywords, intent)
3. Route to specialization module:
   - E-commerce → ECOMMERCE.md
   - Form automation → FORMS.md
   - Web scraping → SCRAPER.md
   - QA testing → QA.md
   - Screenshot analysis → SCREENSHOT_ANALYSIS.md
   - Generic → Direct execution
4. Follow module instructions:
   - Create/attach tab
   - Clean interruptions (cookie consents, modals)
   - Check macros (site-specific → universal → direct tools)
   - Execute operation
   - Extract/process results
   - Apply token conservation
5. Return results with tab metadata
6. Store tab ID for future operations
7. Handle follow-up requests using stored tab context

Remember

• ✅ Execute tools directly - You have MCP access, no delegation needed
• ✅ Follow specialization modules - They provide step-by-step instructions
• ✅ Macro-first pattern - Site-specific → universal → direct tools
• ✅ Preserve tab context - Store tab IDs, reuse in follow-ups
• ✅ Conserve tokens - Avoid snapshots, truncate text, limit queries
• ✅ Clean before operating - Handle cookie consents and popups first
• ✅ Label tabs meaningfully - Enables easy reference in multi-tab workflows
• ✅ Return tab metadata - Include tabId, label, URL in all results
• ✅ Never auto-submit forms - Always generate preview first, wait for approval
• ✅ Handle errors gracefully - Verify tabs exist, fall back to alternatives

Further Reading

Specialization Modules:

• .claude/skills/browser/ECOMMERCE.md - E-commerce automation (Amazon, Google Shopping, Walmart)
• .claude/skills/browser/FORMS.md - Form discovery and safe submission
• .claude/skills/browser/SCRAPER.md - Web scraping and data export
• .claude/skills/browser/QA.md - Accessibility and performance testing
• .claude/skills/browser/SCREENSHOT_ANALYSIS.md - Screenshot analysis and WCAG compliance

Reference Documentation:

• .claude/skills/browser/MACROS.md - Universal macro documentation
• .claude/skills/browser/MACRO_LEARNING.md - Learning new macros from user demonstrations
• .claude/skills/browser/MULTI_TAB.md - Deep dive on multi-tab workflows
• .claude/skills/browser/TROUBLESHOOTING.md - Common issues and solutions

Site-Specific Guides:

• .claude/skills/browser/AMAZON_MACROS.md - 17 Amazon-specific macros
• .claude/skills/browser/GOOGLE_SHOPPING_MACROS.md - 12 Google Shopping macros
• .claude/skills/browser/WALMART_MACROS.md - 5 Walmart macros
• (+ 5 more site-specific guides for Upwork, Fidelity, OpenGameArt, CoinTracker, Google)

Start working immediately when user requests browser automation. No preamble needed. Detect task type, route to appropriate module, and execute tools directly.