eliaalberti/ux-audit-skill

🔍 UX Audit Skill Heuristic UX audits from screenshots

Point it at screenshots of a user journey. Get severity-rated findings, heuristic citations, annotated screenshots, and a structured report. Graded against 16 named UX frameworks, not vibes. One skill, runs in both Claude Code and Codex.

  

Example output: a two-screen journey audited and annotated by severity (red = critical, orange = major, amber = minor, green = positive).

What You Get • Why It Works • Frameworks • Installation • Usage • Severity • FAQ

---

What You Get

You give the skill screenshots of a flow and one line about what the user is trying to do. It returns:

• Severity-rated findings on Nielsen’s 0 to 4 scale, anchored to the user’s actual goal
• Heuristic citations on every finding (“Nielsen #5”, “WCAG 1.4.3”, “Hick’s Law”), never generic “make it pop” feedback
• Annotated screenshots with numbered, colour-coded markers
• Recommended fixes with effort estimates (S/M/L)
• A structured Markdown report with an executive summary, screen-by-screen findings, journey-level analysis, and what already works

It’s a heuristic evaluation, the kind a senior designer does, run by an agent that has actually looked at your screens.

---

What Are Agent Skills?

A skill is a folder with a SKILL.md file. The agent reads it and follows the instructions when a task matches. No plugin, no code to wire up. This one bundles a small Python script for the annotation step.

The same skill folder works in both tools. They read skills from different directories:

Both tools auto-invoke the skill when you ask for a UX audit. In Claude Code you can also call it explicitly as /ux-audit.

---

Why It Works

Most AI design feedback is bad for predictable reasons. This skill is built to avoid each one:

The core idea: the quality of the feedback depends on what you evaluate against. Generic “review this design” prompts produce generic output. Evaluating a journey against established heuristic frameworks, with citations, produces the kind of review you’d pay a consultant for.

Under the hood it runs four passes over your screens: a goal walk (where does the journey break for the stated user), a framework sweep (all 16 below), a named-checks pass (stable IDs so audits are comparable over time), and a journey-level pass (cross-screen consistency, memory load, Peak-End, and a Fogg behaviour-model read of the key conversion action).

---

The Frameworks

Findings are graded against 16 canonical frameworks, grouped by what they catch:

Each framework’s reference list and citation format lives in SKILL.md. Sources are linked at the bottom of every report.

---

Installation

Prerequisites

• Claude Code or Codex
• Python 3 with Pillow (for the annotation step): pip3 install --user pillow

1. Get the files

git clone https://github.com/EliaAlberti/ux-audit-skill.git
cd ux-audit-skill

2. Install into your tool

Claude Code:

mkdir -p ~/.claude/skills/ux-audit
cp -r SKILL.md scripts ~/.claude/skills/ux-audit/

Codex:

mkdir -p ~/.codex/skills/ux-audit
cp -r SKILL.md scripts ~/.codex/skills/ux-audit/

Prefer to edit in place? Symlink instead of copy: ln -s "$(pwd)" ~/.claude/skills/ux-audit

It’s a standard SKILL.md skill, so any Agent Skills manager that installs from a GitHub repo works too.

3. Restart

Skills are discovered at startup. Restart Claude Code or start a new Codex session, then ask for a UX audit.

---

Usage

Ask in plain language, or run /ux-audit in Claude Code. Point it at a folder of screenshots or attach them.

You: /ux-audit ./screenshots

Agent: I see 2 screenshots (sign-up, verify email). Before I start, two things:
       What's the product, and what is the user trying to do in this flow?

You: A SaaS app, a first-time visitor signing up for the free trial.

Agent: Got it. Platform, mobile web? And should I run the full framework
       sweep or focus on specific concerns?

You: Mobile web, full sweep.

Agent: Done. 0 critical, 3 major, 4 minor.
       Report + annotated screens saved to ./ux-audit-2026-01-15-saas-signup/

       Top 3 fixes:
       1. Field labels are placeholder-only, so they vanish on typing (WCAG 3.3.2)
       2. Password helper text fails contrast, the one rule users need is invisible (WCAG 1.4.3)
       3. The verify screen dead-ends, no resend / change-email / help if the link never arrives

       Want me to open issues for the three majors?

See a full example

A complete worked example, a two-screen journey (sign-up → verify email), lives in examples/:

• examples/report.md, the full audit report, including cross-screen findings
• examples/assets/, both annotated screens
• examples/make-example-mockup.py, regenerates both screens, so you can reproduce the whole thing

---

How Severity Works

Findings are rated on Nielsen’s 0 to 4 scale, weighted by impact on the stated goal × how many users hit it × how often. Anchoring to the goal is why the skill asks what the user is trying to do before it starts.

Annotated screenshots use the same colour scale.

---

What It Can’t See

Honest limits. A static screenshot can’t show behaviour, so the skill never guesses at it, these are listed in every report under “not assessable” rather than invented:

• Focus order and focus visibility
• Keyboard navigation and screen-reader semantics
• Motion, animation, transitions
• Latency and loading states
• Live interactive states not captured in the screenshots

For those, pair this with live/code-level accessibility testing.

---

FAQ

---

Contributing

Issues and PRs welcome, especially new named checks, framework refinements, and the annotation fallback. See CONTRIBUTING.md.

---

Credits

Created by Elia Alberti. The frameworks are the work of their original authors (Nielsen, Shneiderman, Gerhardt-Powals, Bastien & Scapin, Fogg, Cialdini, Norman, Tognazzini, the W3C, and others); each report links its sources.

---

License

MIT. See LICENSE.