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:
- Visual Verification Loop
After making CSS/HTML changes, verify visually
node scripts/browser-screenshot.js
Claude reads the screenshot, identifies issues, iterates
- Console Error Detection
Check for JavaScript errors after changes
node scripts/browser-console.js --errors
Fix any errors found, re-verify
- 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
- 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