majiayu000 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