Browser Runtime Debugging Toolkit

Overview

UI/CSS/DOM layout issues often have root causes that only manifest at runtime — dynamically generated DOM structures, CSS specificity conflicts, layout calculation anomalies. Static code analysis (Read/Grep) and console-based debugging (console.log) have a fundamental limitation: they cannot observe the rendered DOM tree, computed CSS properties, or box model geometry.

This skill provides a scene-to-tool decision table and usage guides for each tool. Referenced by PDCA hosts via frontmatter dependencies (invoked after a prerequisite check when browser-reproducible scenarios are detected). Hosts are SoT for that edge.

Prerequisites

Step 1: Check MCP Availability

Before using browser debugging tools, check if chrome-devtools-mcp (sometimes called chrome-devtools-connect) is available:

Step 2: If MCP Is Missing — Adaptive Choice

When chrome-devtools-mcp is not available, present the user with three options:

Option A: Auto-install (Recommended)

The AI runs the installation command directly for the detected platform:

After installation, restart the AI tool to load the MCP server.

Option B: Manual Install

Provide the exact commands (same as Option A) for the user to copy-paste and run themselves. Wait for user confirmation before proceeding.

Option C: Skip — Use Manual DevTools

Fallback: guide the user to open browser DevTools manually (F12) and inspect elements by hand. Slower than MCP but requires no setup.

Step 3: Environment Prerequisites

• Node.js LTS + npm (required by chrome-devtools-mcp)
• Chrome browser (stable version; Google Chrome or Chrome for Testing)

Step 4: Verify Installation

After install/enable, verify the MCP is loaded:

Scene → Tool Decision Table

Default channel: ego-browser (external skill, macOS only) — runtime-check it first; it is a runtime-local dependency, not declared in frontmatter dependencies, so upstream workflows like solve-workflow stay free of any external-plugin requirement. If ego-browser is unavailable (not installed / non-macOS) or fails mid-task (error, cannot reach the page, raw cdp() too low-level for the need), degrade along the chain below and tell the user which channel you are on — never silently fall back. The fallback columns point to chrome-devtools-mcp (MCP server, see Prerequisites) and the external web-access skill's CDP Proxy (same weak-reference rule: verify availability, abort with an install hint if missing). Non-macOS substitutes for the ego-browser row: playwright-mcp (MCP, a11y-tree snapshots) → agent-browser (CLI).

Tool Usage Guides

chrome-devtools-mcp (MCP Server)

Type: MCP server (Chrome DevTools Protocol) / Availability: Environment-dependent (see Prerequisites)

When to use: Real-time inspection of page DOM, CSS, network, and console — AI operates DevTools directly without manual context switching.

Core capabilities: DOM inspection (querySelector, computed styles, element attributes), CSS debugging (matched rules, override chain, box model), Console (execute JS, read output), Network (request/response inspection), Screenshot (page or element capture).

Usage pattern: When MCP is available, connect to the browser in the workflow's analysis stage → reproduce the problem and inspect runtime state (DOM structure, computed styles, console, network) → compare expected vs actual to anchor root cause; in the verification stage, validate that the fix works.

Note: If MCP is not installed, see the Prerequisites section above for adaptive setup options (auto-install / manual / skip).

playwright / webapp-testing (Skill)

Type: Skill (browser automation) / Availability: OpenCode built-in playwright; user skill webapp-testing

When to use: Automated interaction reproduction (click, type, navigate), screenshot comparison, end-to-end verification.

Difference from chrome-devtools-mcp: Playwright focuses on automated operations (script-driven, batch verification); chrome-devtools-mcp focuses on real-time inspection (interactive debugging, instant feedback).

visual-qa (Skill)

Type: Skill (visual quality assurance) / Availability: shared/opencode skill

When to use: Screenshot comparison, design review, visual regression verification. Especially suited for before/after fix comparison scenarios.

Framework DevTools (Browser Extensions)

Framework DevTools are browser extensions that AI cannot operate directly. Guide the user to install and inspect manually.

Three channels, three postures — choose by signal

Pick the channel by what the debug session needs, not by habit. The three overlap in basic interaction (click / fill / evaluate / screenshot) but differ sharply in posture:

Default: ego-browser first. Start every browser debugging / control session on the ego-browser channel (runtime-check availability first). It is the only channel that bundles full interaction + page JS + raw CDP + inherited login state + isolated task space + human-AI handoff, so one channel covers the whole observe → reproduce → verify loop. Degrade only when it is unavailable (not installed / non-macOS) or fails for the need at hand:

ego-browser (macOS, default — runtime-checked)
  ├─ unavailable or failed?
  │   ├─ non-macOS → playwright-mcp (MCP, a11y snapshots) → agent-browser (CLI)
  │   ├─ need purpose-built panels (perf trace / network waterfall / computed style),
  │   │  where raw cdp() is too low-level or fails → chrome-devtools-mcp
  │   ├─ need lightweight login-state control or curl-parallel sub-agents → web-access CDP Proxy
  │   └─ nothing available → guide user to manual DevTools (F12)
  └─ still tell the user which channel you are on (never silently fall back)

Two specialist exceptions where the fallback may be the better first pick even when ego-browser works: performance traces (chrome-devtools-mcp's purpose-built Performance tooling beats raw cdp('Performance.*')) and unattended CI regression (Playwright / webapp-testing — no user browser exists in CI). Pure information retrieval (search / scraping / anti-scrape platforms) is not a debugging task — that belongs to effective-web-research + web-access, not this skill.

For the web-access curl API cheat sheet, the ego-browser heredoc recipes, and debugging recipes per channel, see reference.md.

Workflow Integration

Referenced by PDCA hosts via frontmatter dependencies (missing → host aborts). Also discovered by debug-workflow and similar workflow skills through environment capability exploration. Delegated to by hybrid-debug for runtime evidence in hybrid app (WebView/WKWebView/Electron + H5) debugging, and by runtime-evidence-debug for UI/CSS/DOM instrumentation in general debugging:

1. Analysis stage: Browser-reproducible problems (UI/CSS/DOM as typical scenes) → prioritize browser tools to reproduce the problem and inspect runtime state
2. Before console.log debugging: For UI issues, inspect with browser DevTools first (more efficient than console.log), then fall back to logging if still unresolved
3. Verification stage: After fix, use browser tools to verify that the fix works (before/after runtime-state comparison)

Progressive enhancement: This skill does not replace the host workflow's core process. When loaded as a strong dependency it is guaranteed by the host prerequisite check; in other workflows (e.g., debug-workflow), when browser tools are unavailable, the original process executes unchanged.

Quick Reference

Scene detection: Can this problem be reproduced in a browser? (UI/CSS/DOM issues are the typical scenes)
Signal keywords: style, layout, render, display, visibility, position, size, color, animation
→ Yes → Prioritize browser tools to reproduce and inspect (this skill's decision table guides selection)
→ No → Follow original static analysis / console.log debugging process

Tool selection (default + degradation — full table in "Three channels" section):
1. ego-browser (macOS, runtime-checked) — DEFAULT: full interaction / js() / raw cdp() / login state / task space / handoff
2. unavailable or failed → non-macOS: playwright-mcp → agent-browser
3. → purpose-built panels (perf / network / computed style): chrome-devtools-mcp
4. → lightweight login-state control, curl-parallel: web-access CDP Proxy
5. Unattended CI / batch E2E → playwright / webapp-testing (specialist exception)
6. Visual comparison / design review → visual-qa
7. No browser tooling → guide user to manual DevTools

MCP prerequisite check:
→ MCP missing? Present adaptive choice: A=auto-install / B=manual / C=skip
→ See Prerequisites section for platform-specific commands