Chrome DevTools Agent Skill

Browser automation via Puppeteer scripts with persistent sessions. All scripts output JSON.

⚠️ MUST READ References

IMPORTANT: You MUST read these reference files for complete protocol. Do NOT skip.

•⚠️ MUST READ references/devtools-patterns.md — ARIA, screenshots, console, custom scripts
•⚠️ MUST READ references/cdp-domains.md — CDP domain reference
•⚠️ MUST READ references/puppeteer-reference.md — Puppeteer API reference
•⚠️ MUST READ references/performance-guide.md — Performance analysis guide
•⚠️ MUST READ scripts/README.md — Script options reference

Choosing Your Approach

Scenario	Approach
Source-available sites	Read source code first, write selectors directly
Unknown layouts	Use `aria-snapshot.js` for semantic discovery
Visual inspection	Take screenshots to verify rendering
Debug issues	Collect console logs, analyze with session storage

Quick Start

bash

cd .claude/skills/chrome-devtools/scripts
npm install
node navigate.js --url https://example.com
# Headless on Linux/WSL/CI; headed on macOS/Windows
# Linux/WSL: Run ./install-deps.sh first for Chrome system libraries

Session Persistence

Browser state persists via .browser-session.json. Scripts disconnect but keep browser running.

bash

node navigate.js --url https://example.com/login
node fill.js --selector "#email" --value "user@example.com"
node click.js --selector "button[type=submit]"
node navigate.js --url about:blank --close true   # Close when done

Available Scripts

All in .claude/skills/chrome-devtools/scripts/:

Script	Purpose
`navigate.js`	Navigate to URLs
`screenshot.js`	Capture screenshots (auto-compress >5MB)
`click.js`	Click elements
`fill.js`	Fill form fields
`evaluate.js`	Execute JS in page context
`snapshot.js`	Extract interactive elements (JSON)
`aria-snapshot.js`	Get ARIA accessibility tree (YAML with refs)
`select-ref.js`	Interact with elements by ARIA ref
`console.js`	Monitor console messages/errors
`network.js`	Track HTTP requests/responses
`performance.js`	Measure Core Web Vitals

Script Options (All scripts)

•--headless false - Show browser window
•--close true - Close browser completely
•--timeout 30000 - Set timeout (ms)
•--wait-until networkidle2 - Wait strategy

Common Patterns

bash

# Web scraping
node evaluate.js --url https://example.com --script "
  Array.from(document.querySelectorAll('.item')).map(el => ({
    title: el.querySelector('h2')?.textContent, link: el.querySelector('a')?.href
  }))" | jq '.result'

# Form automation
node fill.js --selector "#search" --value "query"
node click.js --selector "button[type=submit]"

# Performance
node performance.js --url https://example.com | jq '.vitals'

Local HTML Files

Never use file://. Serve via local server: npx serve ./dist -p 3000 &

Troubleshooting

Error	Solution
`Cannot find package 'puppeteer'`	Run `npm install` in scripts directory
`libnss3.so` missing (Linux)	Run `./install-deps.sh`
Element not found	Use `snapshot.js` to find correct selector
Script hangs	Use `--timeout 60000` or `--wait-until load`
Screenshot >5MB	Auto-compressed; use `--max-size 3` for lower
Session stale	Delete `.browser-session.json` and retry

IMPORTANT Task Planning Notes

•Always plan and break many small todo tasks
•Always add a final review todo task to review the works done at the end to find any fix or enhancement needed