UX Review Agent Starter (SKILL.md)

The paste-ready SKILL.md for a first UX review agent. Covers 6 heuristic lenses, returns the top 5 ranked fixes, and installs in 30 seconds. Pairs with the Your First UX Review Agent guide.

All Templates

What this is

A ready-to-paste SKILL.md for a first UX review agent. Invoke /ux-review in any project to audit a screen against 6 heuristic lenses (first-time user clarity, visual hierarchy, accessibility, copy, information density, trust and feedback) and return the top 5 ranked fixes.

This is the companion template to the Your First UX Review Agent guide. Install this, read the guide, and you have your first working orchestration loop in 30 minutes.

How to install

Step 1: Create the skill folder

mkdir -p ~/.claude/skills/ux-review

Step 2: Create the SKILL.md file

touch ~/.claude/skills/ux-review/SKILL.md
open ~/.claude/skills/ux-review/SKILL.md

Step 3: Paste the full SKILL.md below

Copy the whole block under “The full SKILL.md” into the file and save.

Step 4: Invoke it

In Claude Code (CLI or extension), run:

/ux-review

Review this page: https://[your-url]

Or with a screenshot:

/ux-review

Review this screenshot: ~/Desktop/onboarding.png

The full SKILL.md

---
name: ux-review
description: Review a screen (URL, screenshot, or Figma link) for first-time user
  friction, accessibility issues, copy clarity, visual hierarchy, information
  density, and trust signals. Returns the top 5 fixes ranked by severity. Use
  any time you want an honest review of a specific screen or flow.
---

## What to do

I will give you a screen to review. It could be:

- a URL (for example https://example.com/pricing)
- a local screenshot path (for example ~/Desktop/onboarding.png)
- a Figma link
- a description of a screen if no visual is available

You will:

1. Read or view the screen carefully. If it is a URL, fetch it. If it is a
   screenshot, read the image.
2. Apply the rubric below as a first-time user would.
3. Return the top 5 issues, ranked by severity.
4. For each issue include: what is wrong, why it matters, and the specific fix.

## Review rubric

Review the screen against these 6 dimensions. For each, note any issues.

### 1. First-time user clarity
- Can a first-time user tell what this product does in 3 seconds?
- Is the primary action obvious?
- Is there a clear next step?
- Are there more than 2 competing calls to action?

### 2. Visual hierarchy
- Is the most important element the most visually prominent?
- Do secondary actions compete with the primary action?
- Is there a clear reading order (top to bottom or left to right)?

### 3. Accessibility
- Is contrast sufficient (text against background, icons against containers)?
- Is interactive content at least 44px tall on mobile?
- Is every interactive element keyboard-reachable?
- Is every image or icon given a meaningful label or alt text?
- Are form fields labeled clearly?

### 4. Copy clarity
- Is the headline a specific statement or a vague tease?
- Do buttons name the action ("Save changes") or use empty verbs ("Submit",
  "Continue", "Get started")?
- Is any copy buzzwordy ("revolutionize", "seamless", "unlock", "empower")?
- Are error messages actionable?

### 5. Information density
- Is there too much on the screen to scan quickly?
- Is there too little to act confidently?
- Are primary actions above the fold?

### 6. Trust and feedback
- Does the user know what will happen when they click?
- Are destructive actions clearly marked?
- Is there feedback after an action (loading, success, error)?

## Output format

Return the top 5 issues in this exact format:

### Issue 1: [Short name of the issue]
- **What**: [One sentence describing the problem]
- **Why it matters**: [One sentence explaining the user impact]
- **Fix**: [One or two sentences with the specific change]
- **Severity**: [Blocking / High / Medium / Low]

Repeat for Issues 2–5.

After the 5 issues, add one final line:

> **First priority**: Fix [Issue number and name] first. Ship nothing else until
> that is addressed.

## Never do

- Do not return more than 5 issues. Rank ruthlessly. Top 5 only.
- Do not generalize ("the page could be clearer"). Be specific: what line, what
  element, what fix.
- Do not suggest adding animation, gradients, or 3D as a fix. Those are almost
  never the issue.
- Do not rewrite copy without being asked. Suggest the direction, then offer to
  rewrite if I want.
- Do not skip accessibility issues to focus on polish. Accessibility is never
  lower priority.

## Hard cap

If you wrote more than 5 issues, delete the lowest-severity ones before
returning. 5 is the ceiling, no exceptions.

How to customize for your project

Add product context

If your product has a specific domain or user, add it at the top of the skill so the review is grounded.

## Project context
This product is a [one-sentence description].
The primary customer is [persona].
The primary goal of most screens is [goal].
Review with that context in mind.

Reference your project’s CLAUDE.md

To have the review check against your specific brand and component rules, add:

## Also check against
Before returning findings, read the project's CLAUDE.md at ./CLAUDE.md
and surface any direct violations (brand colors, typography, banned patterns).

Raise or lower the severity floor

If you want only Blocking and High issues returned, tighten the hard cap:

## Hard cap
Only include issues at Blocking or High severity. If fewer than 5 exist at
that severity, return fewer. Do not pad with Medium or Low issues.

Add project-specific rubric items

Pull rubric items from your team’s existing review checklists. Any criterion you already use in design reviews belongs in the skill.

What this pairs with