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:

1. Target URL (required) — The application's entry point (landing page, login, dashboard, etc.)
2. Key user flows (optional) — Specific paths to test, e.g. "sign up → create project → invite team"
3. Target audience (optional) — Who uses this app and what they expect
4. Focus areas (optional) — Which review dimensions matter most (see Agent Roster below)
5. 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

1. Confirm the target URL and any user-provided context
2. Ensure Playwright CLI is installed (playwright-cli --help)
3. Open a browser session: playwright-cli open <url>
4. Take an initial screenshot to confirm the page loaded: playwright-cli screenshot --filename=landing.png
5. Capture a snapshot for structural analysis: playwright-cli snapshot --filename=landing-snapshot.txt
6. Create the workspace directory for outputs

Phase 2: Discovery (Main Agent)

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

1. Capture the landing page snapshot
2. Identify primary navigation links from the snapshot
3. Visit 3-5 key pages (follow nav links) and snapshot each
4. Build a simple sitemap of discovered pages
5. 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:

1. Opens the app in its own Playwright CLI session (-s=<agent-name>)
2. Navigates through relevant pages
3. Takes snapshots and screenshots as evidence
4. 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:

1. Reads all 6 agent reports
2. Deduplicates overlapping findings
3. Categorizes by severity (Critical / High / Medium / Low)
4. Ranks by impact-vs-effort (essential for solo devs)
5. 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

1. Handle Playwright CLI installation if needed
2. Run the discovery phase to build shared context
3. Spawn review agents in parallel (or sequentially if no sub-agents)
4. Ensure each agent uses its own named session (-s=<name>)
5. Collect all agent reports
6. Run the synthesizer to produce the final report
7. Clean up browser sessions: playwright-cli close-all
8. 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.