UX Review Skill

A multi-agent UX review system that browses live web applications with Playwright CLI and produces a prioritized, actionable report for solo developers and small teams.

Prerequisites

Playwright CLI must be installed. If not available, run:

npm install -g @playwright/cli@latest playwright-cli install-browser playwright-cli install --skills

Verify with playwright-cli --help .

Inputs

The user provides:

• Target URL (required) — The application's entry point (landing page, login, dashboard, etc.)

• Key user flows (optional) — Specific paths to test, e.g. "sign up → create project → invite team"

• Target audience (optional) — Who uses this app and what they expect

• Focus areas (optional) — Which review dimensions matter most (see Agent Roster below)

• Context file (optional) — A markdown file with app description, known issues, constraints

If the user doesn't provide optional inputs, use reasonable defaults and note assumptions.

Agent Roster

Each agent has a specialized lens. All agents use Playwright CLI to interact with the live app.

Agent Focus Reference

1 First Impression Landing page clarity, value prop, CTAs, trust signals, load perception agents/first-impression.md

2 Information Architecture Navigation, page hierarchy, naming, discoverability, mental models agents/information-architecture.md

3 User Flow Task completion paths, friction, dead ends, error recovery, onboarding agents/user-flow.md

4 Visual Design Spacing, typography, color, component consistency, responsive hints agents/visual-design.md

5 Accessibility WCAG compliance, keyboard nav, ARIA, contrast, form labels, error states agents/accessibility.md

6 Copy & Microcopy Button labels, error messages, empty states, onboarding text, tone agents/copy-review.md

7 Synthesizer Reads all agent reports → produces prioritized action plan agents/synthesizer.md

Workflow

Phase 1: Setup

• Confirm the target URL and any user-provided context

• Ensure Playwright CLI is installed (playwright-cli --help )

• Open a browser session: playwright-cli open <url>

• Take an initial screenshot to confirm the page loaded: playwright-cli screenshot --filename=landing.png

• Capture a snapshot for structural analysis: playwright-cli snapshot --filename=landing-snapshot.txt

• Create the workspace directory for outputs

Phase 2: Discovery (Main Agent)

Before spawning review agents, do a quick site crawl to understand scope:

• Capture the landing page snapshot

• Identify primary navigation links from the snapshot

• Visit 3-5 key pages (follow nav links) and snapshot each

• Build a simple sitemap of discovered pages

• Save discovery results to workspace/discovery.md

This discovery output is shared with all review agents as context.

Phase 3: Parallel Review (Sub-agents)

Spawn agents 1-6 in parallel. Each agent receives:

• The target URL

• The discovery file (workspace/discovery.md )

• Their specific agent instructions (from agents/*.md )

• The Playwright CLI reference (references/playwright-guide.md )

• The heuristics reference (references/heuristics.md )

• An output directory for their findings

Each agent:

• Opens the app in its own Playwright CLI session (-s=<agent-name> )

• Navigates through relevant pages

• Takes snapshots and screenshots as evidence

• Writes findings to their output file

If sub-agents are not available, run each review sequentially in the main loop.

Phase 4: Synthesis

After all reviews complete, the Synthesizer agent:

• Reads all 6 agent reports

• Deduplicates overlapping findings

• Categorizes by severity (Critical / High / Medium / Low)

• Ranks by impact-vs-effort (essential for solo devs)

• Produces the final report

Phase 5: Output

Generate the final deliverable as a markdown report following the template in references/report-template.md .

Save to the workspace and present to the user.

Playwright CLI Quick Reference for Agents

Each agent should use a named session to avoid conflicts:

Agent opens its own session

playwright-cli -s=first-impression open <url>

Navigate

playwright-cli -s=first-impression goto <url>

Capture page structure (element refs, text, layout)

playwright-cli -s=first-impression snapshot --filename=<name>.txt

Take visual screenshot

playwright-cli -s=first-impression screenshot --filename=<name>.png

Interact with elements (using refs from snapshot)

playwright-cli -s=first-impression click <ref> playwright-cli -s=first-impression type <text> playwright-cli -s=first-impression fill <ref> <text>

Check navigation

playwright-cli -s=first-impression tab-list

Close when done

playwright-cli -s=first-impression close

Read references/playwright-guide.md for the full command reference.

Output Structure

workspace/ ├── discovery.md # Site structure from Phase 2 ├── screenshots/ # Visual evidence │ ├── landing.png │ ├── nav-*.png │ └── ... ├── agents/ │ ├── first-impression.md │ ├── information-architecture.md │ ├── user-flow.md │ ├── visual-design.md │ ├── accessibility.md │ └── copy-review.md └── ux-review-report.md # Final synthesized report

Coordinator Responsibilities

• Handle Playwright CLI installation if needed

• Run the discovery phase to build shared context

• Spawn review agents in parallel (or sequentially if no sub-agents)

• Ensure each agent uses its own named session (-s=<name> )

• Collect all agent reports

• Run the synthesizer to produce the final report

• Clean up browser sessions: playwright-cli close-all

• Present the final report to the user

Customization

The user can customize the review by:

• Skipping agents: "Skip accessibility, focus on user flows and copy"

• Adding competitor URLs: Include comparison analysis

• Specifying user stories: "Test the checkout flow specifically"

• Setting priorities: "I care most about conversion, less about accessibility"

• Providing context: "This is a B2B SaaS for project managers"

Adapt the agent roster and instructions accordingly.