website-debug

name

website-debug

description

Frontend website debugging toolkit using Chrome DevTools Protocol with Playwright/WebKit fallbacks. Use this skill when: (1) Debugging CSS, HTML, or JavaScript issues on a webpage, (2) Taking screenshots to verify visual changes, (3) Inspecting DOM structure or console errors, (4) Testing responsive layouts, (5) Extracting selectors for automation, (6) Self-debugging frontend work Claude has created, (7) User says "debug this page", "check my site", "why doesn't this look right", or "fix the frontend". Supports Chrome (primary) and Safari/WebKit (via Playwright). Designed for agent-driven debugging loops.

Website Debugging Skill

Lightweight, token-efficient browser debugging toolkit for frontend development. Uses CLI scripts instead of MCP servers to minimize context usage (~300 tokens vs 13k-18k).

Quick Start

Use the slash commands for easiest access:

• /debug-page <url> - Start debugging session
• /screenshot - Take screenshot
• /pick-element - Interactive element selection
• /test-responsive - Test at all breakpoints
• /verify-changes - Verify after making changes

Or use scripts directly:

# Start browser
node scripts/browser-start.js
node scripts/browser-start.js --profile  # Preserve logins
node scripts/browser-start.js --webkit   # Safari/WebKit

# Navigate
node scripts/browser-nav.js https://localhost:3000

# Debug
node scripts/browser-screenshot.js
node scripts/browser-eval.js 'document.title'
node scripts/browser-pick.js "Select element"
node scripts/browser-console.js --errors
node scripts/browser-network.js --failures

Core Tools Reference

Script	Purpose	Output
browser-start.js	Launch Chrome/WebKit with debug port	Status message
browser-nav.js <url>	Navigate to URL	Confirmation
browser-screenshot.js	Capture viewport	File path (PNG)
browser-eval.js '<js>'	Run JS in page	Result or error
browser-pick.js "<msg>"	Interactive selector	CSS selectors
browser-console.js	Get console output	Logs/errors
browser-network.js	Network activity	Request/response data
browser-dom.js "<sel>"	Get DOM snapshot	HTML fragment
browser-close.js	Close browser	Confirmation

Self-Debugging Workflow

When debugging frontend code Claude has written or modified:

1. Visual Verification Loop

# After making CSS/HTML changes, verify visually
node scripts/browser-screenshot.js
# Claude reads the screenshot, identifies issues, iterates

2. Console Error Detection

# Check for JavaScript errors after changes
node scripts/browser-console.js --errors
# Fix any errors found, re-verify

3. Responsive Testing

# Test at different viewport sizes
node scripts/browser-resize.js 375 667   # iPhone SE
node scripts/browser-screenshot.js
node scripts/browser-resize.js 768 1024  # iPad
node scripts/browser-screenshot.js
node scripts/browser-resize.js 1920 1080 # Desktop
node scripts/browser-screenshot.js

4. Element Inspection

# When user reports "X looks wrong", have them select it
node scripts/browser-pick.js "Click on the element that looks wrong"
# Returns detailed info including computed styles

Browser Engine Selection

Chrome (Default)

Primary engine. Uses Chrome DevTools Protocol on port 9222.

• Best debugging experience
• Full DevTools compatibility
• Use --profile to preserve logins

WebKit/Safari

Fallback via Playwright's WebKit build. Closest to Safari behavior on macOS.

node scripts/browser-start.js --webkit

• Use for Safari-specific testing
• Layout verification
• WebKit-specific bugs

When to Use Each

Scenario	Engine
General debugging	Chrome
Safari layout issues	WebKit
Testing with logins	Chrome --profile
Cross-browser comparison	Both
CI/headless testing	Chrome or WebKit

Advanced Usage

Detailed Documentation

For complex scenarios, load the appropriate reference:

• CSS Debugging: See references/css-debug.md
• JavaScript Errors: See references/js-debug.md
• Self-Debugging: See references/self-debug.md

Composable Output

All scripts output to files when practical, enabling:

# Capture multiple screenshots for comparison
node scripts/browser-screenshot.js --output=/tmp/before.png
# ... make changes ...
node scripts/browser-screenshot.js --output=/tmp/after.png

# Save DOM snapshot for analysis
node scripts/browser-dom.js "body" > /tmp/page-structure.html

# Export console log for review
node scripts/browser-console.js > /tmp/console-log.txt

Chaining Commands

# Navigate and screenshot in one command
node scripts/browser-nav.js https://example.com && node scripts/browser-screenshot.js

# Full page audit
node scripts/browser-nav.js $URL && \
  node scripts/browser-console.js --errors > /tmp/errors.txt && \
  node scripts/browser-screenshot.js

Setup Requirements

Chrome

Chrome must be launchable from command line. The start script handles this automatically.

WebKit (Optional)

For Safari testing, ensure Playwright is installed:

npm install -g playwright
npx playwright install webkit

Dependencies

Scripts require Node.js and puppeteer-core:

npm install -g puppeteer-core

Troubleshooting

"Cannot connect to browser"

Browser may not be running or wrong port:

node scripts/browser-start.js  # Restart browser

"Permission denied"

Scripts may need execute permission:

chmod +x ./scripts/*.js

Chrome already running

Kill existing instances first:

killall "Google Chrome" 2>/dev/null
node scripts/browser-start.js

WebKit not found

Install Playwright browsers:

npx playwright install webkit