chrome-mcp-ui-audit

A reusable Claude Code / Claude Agent skill for running thorough UI/QA audits of web apps through the Chrome DevTools MCP server.

It encodes the non-obvious parts of driving Chrome DevTools MCP for QA — the tool-parameter gotchas, modal/focus traps, and accessibility/term/network inspection techniques — that are easy to rediscover the hard way.

Why this skill

Driving a real browser via Chrome DevTools MCP for QA has sharp edges that aren't in the docs. This skill captures them so an agent gets them right the first time:

• evaluate_script needs a function parameter ("() => { ... }"), not expression
• press_key uses Enter (not Return); take_screenshot uses filePath (not filename)
• Clicks target the uid from take_snapshot (the a11y tree), not CSS selectors
• Nav links don't fire while a modal/panel is open — close it first
• Escape via press_key is focus-dependent; verify with take_snapshot, or dispatch a KeyboardEvent
• DOM term-detection must exclude <script> or SSR payloads (e.g. Next.js __next_f) cause false hits

It also includes ready-to-paste evaluate_script snippets for WCAG contrast sampling, accessible-name checks, legacy-term detection, and bad-URL scanning, plus a self-contained HTML + 3× SVG report spec (severity chart, heatmap, flow map).

Contents

skills/
  chrome-mcp-ui-audit/
    SKILL.md            # the skill (workflow, constraints, gotchas, report spec)
    audit-snippets.js   # copy-paste evaluate_script helpers (read-only)

Install

Copy the skill folder into your agent's skills directory:

# Claude Code (project-level)
cp -r skills/chrome-mcp-ui-audit /path/to/your-project/.claude/skills/

# Claude Code (global)
cp -r skills/chrome-mcp-ui-audit ~/.claude/skills/

The skill auto-loads when a session involves a Chrome DevTools MCP UI/QA audit.

Requirements

• An agent harness that supports skills (e.g. Claude Code)
• The Chrome DevTools MCP server connected to the session
• A Chromium-based browser reachable via remote debugging

Customizing

audit-snippets.js ships with placeholder values you should adapt:

• oldTermDetector → replace the OLD array with your project's legacy terms
• badUrlCheck → add language-prefix / i18n conditions if relevant

The constraints table in SKILL.md (budget caps, admin write-protection, report-test labels) is a sensible default for auditing a live production app — tune it to your project's rules.

License

MIT