Your First UX Review Agent: A 30-Minute Hello World for Designers

The point of this guide

Most “AI for designers” tutorials explain things. This one gets you to a working agent you can run on a real screen in 30 minutes.

By the end you will have a /ux-review slash command that:

• Reads a URL, a screenshot, or a Figma link
• Applies a first-time-user heuristic review
• Checks for accessibility issues, copy clarity, and visual hierarchy
• Returns a prioritized list of the top 5 fixes
• Works in any project, forever, for free

---

Step 1: Create the skill folder (1 minute)

Open your terminal. Run:

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

This creates a folder where your skill lives. The ~/.claude/skills/ path is global. Skills in there work in any project on your machine.

Verify it worked:

ls ~/.claude/skills/

You should see ux-review in the list.

---

Step 2: Create the SKILL.md file (1 minute)

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

Open the file in any editor. Cursor, VS Code, TextEdit, nano. Whatever you have.

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

An empty file opens. You are about to fill it.

---

Step 3: Paste the starter skill (2 minutes)

Copy this whole block into the file and save. Do not tweak it yet. We will customize in Step 5.

---
name: ux-review
description: Review a screen (URL, screenshot, or Figma link) for first-time user
  friction, accessibility issues, and copy clarity. Returns the top 5 fixes ranked
  by impact. 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.
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 you find.

### 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 20 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.

Save the file. Your skill exists.

---

Step 4: Invoke the skill for the first time (2 minutes)

Open Claude Code in any project. Any folder will do. Run:

/ux-review

Claude should respond asking what screen to review. If it does not, the skill is not loaded. Run:

/help

and check that ux-review appears in the list. If it does not, verify the file path:

cat ~/.claude/skills/ux-review/SKILL.md

You should see the full content you pasted. If it is empty, the save did not go through. Re-paste and save.

---

Step 5: Run your first real review (5 minutes)

Pick a screen you know well. The fastest paths:

• Your own product’s onboarding page
• A competitor’s pricing page
• Any screen you screenshotted recently

Invoke the skill:

/ux-review

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

Or with a screenshot:

/ux-review

Review this screenshot: ~/Desktop/onboarding.png

Claude will:

1. Fetch the URL or read the screenshot
2. Apply the rubric
3. Return 5 ranked issues with fixes

Read the output.

---

Step 6: Refine the skill (10 minutes)

The first run will reveal the skill’s weaknesses. This is normal. Your job is to tighten the rules.

Common adjustments after the first run

“It gave me obvious fixes I already knew.” Add a rule: “Do not surface issues that are more than 3 months old and obvious. Focus on things a senior designer would miss on a first read.”

“It flagged too many nice-to-haves.” Tighten the severity definitions: “Only include Blocking or High severity in the top 5. If there are not 5 at that severity, return fewer.”

“It suggested animations or decorative fixes.” Strengthen the “Never do” block: “Never recommend motion, gradients, illustrations, or styling fixes as a top-5 issue unless they are directly causing comprehension failure.”

“It did not understand my product.” Add product context: “This is a [product description]. The primary user is a [persona]. The primary goal of this screen is [goal]. Review with that context.”

How to refine

Open ~/.claude/skills/ux-review/SKILL.md and add or change the lines that matter. Save. Rerun the skill on the same screen. Compare outputs.

Do this 2 or 3 times. After the third iteration, the skill will consistently return output you want.

---

Step 7: Run it on something new (5 minutes)

Pick a second screen. Something you are less familiar with. Run the same skill.

Watch what happens:

1. No setup time
2. No re-explaining the rubric
3. Consistent output format
4. Fast

That gap between the first run and the second run is the real payoff. Your 30 minutes of setup now pays off every time you use the skill for the rest of the project’s life.

---

Checklist: you are done when

If you checked all 5, you have a working UX review agent. Congrats. This is the concrete shift from executor to orchestrator. You just built your first repeatable review workflow.

---

What this unlocks next

Once you trust the /ux-review skill, three things become obvious:

1. You can run reviews faster than anyone who reviews manually. A review that took you 2 hours now takes 10 minutes of running plus 15 minutes of judgment. That is 5x throughput on a common senior-designer task.
2. You can run reviews in parallel. Instead of one review with six lenses, you can run six skills with one lens each and combine results. See Parallel Review System.
3. You can audit your own work. Drop a link to your latest prototype into the skill. Pretend someone else made it. Find what you were too close to see.

---

If something stops working, check the UX review section of Common failure modes.

---

What to build next

1. Ship this skill. Use it for a week on real work. Keep refining.
2. Build the complement: a Multi-lens Review Pack with 4 specialized reviewer skills (first-time user, accessibility, heuristic, edge cases).
3. Learn the context layer: Context Is the Product teaches how to structure a project so your agents work more reliably.
4. Bring the taste rules: pair this skill with the Taste Stack so reviews are judged against your specific design standards, not a generic rubric.

Exercise

Run your ux-review skill on a stranger's product and keep one fix

15 min

1. Point the skill at a product you did not design

   Pick a pricing page, onboarding flow, or settings screen from a product you use but did not build. Copy the URL. In Claude Code, run /ux-review and paste: “Review this page: https://[the-url]”. Read the five ranked issues.

   • The output has exactly five issues, not twelve
   • Every issue names a specific element or line, not “the page feels cluttered”
   • At least one issue is something you would not have caught on your own first read

2. File one of the fixes as a real note

   Take the single highest-severity issue from the report. Write a one-paragraph version of it in your own words, as if you were sending it to the team that ships that product. Save it. You just completed a full review loop from invoke to deliverable using a skill that did not exist 30 minutes ago.

   • The paragraph is short, specific, and quotes the exact element
   • You can explain why you kept that one issue and dropped the other four
   • Running the skill again next week on a different screen takes no setup, only a URL