Chrome DevTools Agent Skill

Browser automation via executable Puppeteer scripts. All scripts output JSON for easy parsing.

Quick Start

CRITICAL: Always check pwd before running scripts.

Installation

Step 1: Install System Dependencies (Linux/WSL only)

On Linux/WSL, Chrome requires system libraries. Install them first:

bash

pwd  # Should show current working directory
cd .claude/skills/chrome-devtools/scripts
./install-deps.sh  # Auto-detects OS and installs required libs

Supports: Ubuntu, Debian, Fedora, RHEL, CentOS, Arch, Manjaro

macOS/Windows: Skip this step (dependencies bundled with Chrome)

Step 2: Install Node Dependencies

bash

npm install  # Installs puppeteer, debug, yargs

Step 3: Install ImageMagick (Optional, Recommended)

ImageMagick enables automatic screenshot compression to keep files under 5MB:

macOS:

bash

brew install imagemagick

Ubuntu/Debian/WSL:

bash

sudo apt-get install imagemagick

Verify:

bash

magick -version  # or: convert -version

Without ImageMagick, screenshots >5MB will not be compressed (may fail to load in Gemini/Claude).

Test

bash

node navigate.js --url https://example.com
# Output: {"success": true, "url": "https://example.com", "title": "Example Domain"}

Available Scripts

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

CRITICAL: Always check pwd before running scripts.

Script Usage

./scripts/README.md

Core Automation

navigate.js - Navigate to URLs
screenshot.js - Capture screenshots (full page or element)
click.js - Click elements
fill.js - Fill form fields
evaluate.js - Execute JavaScript in page context

Analysis & Monitoring

snapshot.js - Extract interactive elements with metadata
console.js - Monitor console messages/errors
network.js - Track HTTP requests/responses
performance.js - Measure Core Web Vitals + record traces

Usage Patterns

Single Command

bash

pwd  # Should show current working directory
cd .claude/skills/chrome-devtools/scripts
node screenshot.js --url https://example.com --output ./docs/screenshots/page.png

Important: Always save screenshots to ./docs/screenshots directory.

Automatic Image Compression

Screenshots are automatically compressed if they exceed 5MB to ensure compatibility with Gemini API and Claude Code (which have 5MB limits). This uses ImageMagick internally:

bash

# Default: auto-compress if >5MB
node screenshot.js --url https://example.com --output page.png

# Custom size threshold (e.g., 3MB)
node screenshot.js --url https://example.com --output page.png --max-size 3

# Disable compression
node screenshot.js --url https://example.com --output page.png --no-compress

Compression behavior:

PNG: Resizes to 90% + quality 85 (or 75% + quality 70 if still too large)
JPEG: Quality 80 + progressive encoding (or quality 60 if still too large)
Other formats: Converted to JPEG with compression
Requires ImageMagick installed (see imagemagick skill)

Output includes compression info:

json

{
  "success": true,
  "output": "/path/to/page.png",
  "compressed": true,
  "originalSize": 8388608,
  "size": 3145728,
  "compressionRatio": "62.50%",
  "url": "https://example.com"
}

Chain Commands (reuse browser)

bash

# Keep browser open with --close false
node navigate.js --url https://example.com/login --close false
node fill.js --selector "#email" --value "user@example.com" --close false
node fill.js --selector "#password" --value "secret" --close false
node click.js --selector "button[type=submit]"

Parse JSON Output

bash

# Extract specific fields with jq
node performance.js --url https://example.com | jq '.vitals.LCP'

# Save to file
node network.js --url https://example.com --output /tmp/requests.json

Execution Protocol

Working Directory Verification

BEFORE executing any script:

Check current working directory with pwd
Verify in .claude/skills/chrome-devtools/scripts/ directory
If wrong directory, cd to correct location
Use absolute paths for all output files

Example:

bash

pwd  # Should show: .../chrome-devtools/scripts
# If wrong:
cd .claude/skills/chrome-devtools/scripts

Output Validation

AFTER screenshot/capture operations:

Verify file created with ls -lh <output-path>
Read screenshot using Read tool to confirm content
Check JSON output for success:true
Report file size and compression status

Example:

bash

node screenshot.js --url https://example.com --output ./docs/screenshots/page.png
ls -lh ./docs/screenshots/page.png  # Verify file exists
# Then use Read tool to visually inspect

Restart working directory to the project root.

Error Recovery

If script fails:

Check error message for selector issues
Use snapshot.js to discover correct selectors
Try XPath selector if CSS selector fails
Verify element is visible and interactive

Example:

bash

# CSS selector fails
node click.js --url https://example.com --selector ".btn-submit"
# Error: waiting for selector ".btn-submit" failed

# Discover correct selector
node snapshot.js --url https://example.com | jq '.elements[] | select(.tagName=="BUTTON")'

# Try XPath
node click.js --url https://example.com --selector "//button[contains(text(),'Submit')]"

Common Mistakes

❌ Wrong working directory → output files go to wrong location ❌ Skipping output validation → silent failures ❌ Using complex CSS selectors without testing → selector errors ❌ Not checking element visibility → timeout errors

✅ Always verify pwd before running scripts ✅ Always validate output after screenshots ✅ Use snapshot.js to discover selectors ✅ Test selectors with simple commands first

Common Workflows

Web Scraping

bash

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'

Performance Testing

bash

PERF=$(node performance.js --url https://example.com)
LCP=$(echo $PERF | jq '.vitals.LCP')
if (( $(echo "$LCP < 2500" | bc -l) )); then
  echo "✓ LCP passed: ${LCP}ms"
else
  echo "✗ LCP failed: ${LCP}ms"
fi

Form Automation

bash

node fill.js --url https://example.com --selector "#search" --value "query" --close false
node click.js --selector "button[type=submit]"

Error Monitoring

bash

node console.js --url https://example.com --types error,warn --duration 5000 | jq '.messageCount'

Script Options

All scripts support:

--headless false - Show browser window
--close false - Keep browser open for chaining
--timeout 30000 - Set timeout (milliseconds)
--wait-until networkidle2 - Wait strategy

See ./scripts/README.md for complete options.

Output Format

All scripts output JSON to stdout:

json

{
  "success": true,
  "url": "https://example.com",
  ... // script-specific data
}

Errors go to stderr:

json

{
  "success": false,
  "error": "Error message"
}

Finding Elements

Use snapshot.js to discover selectors:

bash

node snapshot.js --url https://example.com | jq '.elements[] | {tagName, text, selector}'

Troubleshooting

Common Errors

"Cannot find package 'puppeteer'"

Run: npm install in the scripts directory

"error while loading shared libraries: libnss3.so" (Linux/WSL)

Missing system dependencies
Fix: Run ./install-deps.sh in scripts directory
Manual install: sudo apt-get install -y libnss3 libnspr4 libasound2t64 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1

"Failed to launch the browser process"

Check system dependencies installed (Linux/WSL)
Verify Chrome downloaded: ls ~/.cache/puppeteer
Try: npm rebuild then npm install

Chrome not found

Puppeteer auto-downloads Chrome during npm install
If failed, manually trigger: npx puppeteer browsers install chrome

Script Issues

Element not found

Get snapshot first to find correct selector: node snapshot.js --url <url>

Script hangs

Increase timeout: --timeout 60000
Change wait strategy: --wait-until load or --wait-until domcontentloaded

Blank screenshot

Wait for page load: --wait-until networkidle2
Increase timeout: --timeout 30000

Permission denied on scripts

Make executable: chmod +x *.sh

Screenshot too large (>5MB)

Install ImageMagick for automatic compression
Manually set lower threshold: --max-size 3
Use JPEG format instead of PNG: --format jpeg --quality 80
Capture specific element instead of full page: --selector .main-content

Compression not working

Verify ImageMagick installed: magick -version or convert -version
Check file was actually compressed in output JSON: "compressed": true
For very large pages, use --selector to capture only needed area

Reference Documentation

Detailed guides available in ./references/:

CDP Domains Reference - 47 Chrome DevTools Protocol domains
Puppeteer Quick Reference - Complete Puppeteer API patterns
Performance Analysis Guide - Core Web Vitals optimization

Advanced Usage

Custom Scripts

Create custom scripts using shared library:

javascript

import { getBrowser, getPage, closeBrowser, outputJSON } from './lib/browser.js';
// Your automation logic

Direct CDP Access

javascript

const client = await page.createCDPSession();
await client.send('Emulation.setCPUThrottlingRate', { rate: 4 });

See reference documentation for advanced patterns and complete API coverage.

chrome devtools

Chrome DevTools Agent Skill

Quick Start

Installation

Step 1: Install System Dependencies (Linux/WSL only)

Step 2: Install Node Dependencies

Step 3: Install ImageMagick (Optional, Recommended)

Test

Available Scripts

Script Usage

Core Automation

Analysis & Monitoring

Usage Patterns

Single Command

Automatic Image Compression

Chain Commands (reuse browser)

Parse JSON Output

Execution Protocol

Working Directory Verification

Output Validation

Error Recovery

Common Mistakes

Common Workflows

Web Scraping

Performance Testing

Form Automation

Error Monitoring

Script Options

Output Format

Finding Elements

Troubleshooting

Common Errors

Script Issues

Reference Documentation

Advanced Usage

Custom Scripts

Direct CDP Access

External Resources