website-debug
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.
When & Why to Use This Skill
This Claude skill is a lightweight, token-efficient frontend debugging toolkit designed for real-time website troubleshooting and visual verification. It leverages the Chrome DevTools Protocol and Playwright to enable deep inspection of DOM structures, capture high-resolution screenshots, analyze JavaScript console errors, and test responsive layouts across both Chrome and WebKit engines. By utilizing optimized CLI scripts instead of heavy MCP servers, it significantly reduces context window usage while providing Claude with the 'eyes' and tools necessary to fix complex CSS, HTML, and JS issues autonomously.
Use Cases
- Visual Regression Testing: Capture and compare screenshots before and after code changes to ensure UI consistency and verify that visual fixes are applied correctly.
- Cross-Browser Compatibility Checks: Toggle between Chrome and WebKit (Safari) engines to identify and resolve rendering bugs specific to different browser environments.
- Automated Error Diagnosis: Programmatically extract JavaScript console logs and network failure data to pinpoint the root cause of functional regressions or loading issues.
- Responsive Design Validation: Use automated resizing scripts to test website layouts across multiple breakpoints (mobile, tablet, desktop) and verify media query behavior.
- Interactive Element Inspection: Utilize the element picker and DOM snapshot tools to retrieve precise CSS selectors and computed styles for targeted UI modifications.
| name | website-debug |
|---|---|
| description | > |
| Use this skill when | (1) Debugging CSS, HTML, or JavaScript issues on a webpage, (2) Taking screenshots |
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
--profileto 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