agentleFS
JoaoMonteiro100JoaoMonteiro100/ux-design-skills/skills/heuristic-evaluation/SKILL.md

heuristic-evaluation

Skill0 starsChanged 4 months agoMITView on GitHub

Runs an expert usability inspection (heuristic evaluation) of a digital product — reviewing screens, flows, or a whole interface against established usability principles, logging issues with a consistent severity rating, and producing a prioritized findings report with recommendations. Use this whenever the user wants to audit, review, critique, or evaluate the usability of an interface without recruiting users; wants a "heuristic evaluation", "UX audit", "usability review", "expert review", or "cognitive walkthrough"; wants to find usability problems in a design, prototype, or live product themselves; or asks which usability principles a screen violates. This is expert-based inspection with NO participants — if the user instead wants to test with real users, that is moderated usability testing, a different method.

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 9 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill to run an evaluation end to end, or to help with any one piece of it (pick a heuristic set, write up an issue, rate …

    line 30
  2. Distinctive:

    Before inspecting anything, pin down:

    line 37
  3. Distinctive:

    If the user has screenshots, a prototype link, or a live URL, work from that.

    line 48
  4. Distinctive:

    Show system status: Keep people informed about what's happening through timely, visible feedback — loading states, confirmations, progress.

    line 61
  5. Distinctive:

    Favor recognition over recall: Keep options, actions, and information visible so people don't have to remember things across steps.

    line 72
  6. Distinctive:

    Keep it minimal: Every extra element competes for attention.

    line 76
  7. Distinctive:

    Provide help and documentation: When needed, help should be easy to find, task-focused, and concrete.

    line 80
  8. Distinctive:

    Do two passes. First pass: get a feel for the flow and overall structure.

    line 96
  9. Distinctive:

    Always show the *reasoning* for a rating, not just the label — "Serious: on the primary signup path (high frequency), users can't tell the …

    line 142

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Heuristic Evaluation (Expert UX Audit)

A heuristic evaluation is a structured way for one or more people to inspect an interface against a set of usability principles ("heuristics") and surface the problems a designer would want to fix. It's fast, cheap, and needs no participants — which is its strength and its limit. It reliably catches the generic, recognizable problems (unclear labels, missing feedback, inconsistent patterns, dead ends), but it does not tell you what real users actually do, where they get genuinely stuck, or whether they succeed. Say this plainly to the user when relevant: a heuristic evaluation complements usability testing with real users, it doesn't replace it.

Use this skill to run an evaluation end to end, or to help with any one piece of it (pick a heuristic set, write up an issue, rate severity, structure a report).

How to run an evaluation

1. Set up the evaluation

Before inspecting anything, pin down:

  • What's being evaluated — the whole product, one flow (e.g. onboarding, checkout), or a specific screen. A focused scope produces sharper findings.
  • Who the users are and what they're trying to do. Usability is relative to a user and a goal. "Is this clear?" only has an answer once you know clear to whom, doing what. Even a rough persona and top tasks sharpen every judgment.
  • The context of use — device, environment, expertise level, frequency of use. An expert tool used daily forgives density that a consumer app can't.
  • Which heuristics you'll evaluate against (see below).

If the user has screenshots, a prototype link, or a live URL, work from that. If they don't, don't fabricate findings about an interface you can't see — instead, give them the heuristic set and issue-logging structure so they can walk their own product, and offer to do the first pass together from screenshots or a recording.

2. Choose a heuristic set

Heuristics are the lens. The most widely used general-purpose set in the field is Jakob Nielsen's ten usability heuristics; evaluate against these unless the product calls for something more specialized. Expressed in plain terms, a good interface should:

  1. Show system status. Keep people informed about what's happening through timely, visible feedback — loading states, confirmations, progress.
  2. Match the real world. Speak the user's language and follow real-world conventions rather than internal jargon or system-oriented terms.
  3. Give control and freedom. Provide clear exits, undo, and a way back out of mistakes without feeling trapped.
  4. Be consistent and follow standards. The same thing should look and behave the same way; follow platform and industry conventions so people don't have to relearn.
  5. Prevent errors. Design so the slip can't happen in the first place — constraints, good defaults, confirmation on destructive actions.
  6. Favor recognition over recall. Keep options, actions, and information visible so people don't have to remember things across steps.
  7. Be flexible and efficient. Let novices succeed while giving experts accelerators (shortcuts, saved states) to go faster.
  8. Keep it minimal. Every extra element competes for attention; remove or downplay what isn't needed so the essential stands out.
  9. Help users recover from errors. Error messages should be in plain language, say what went wrong, and offer a way to fix it.
  10. Provide help and documentation. When needed, help should be easy to find, task-focused, and concrete.

For specialized products, supplement with domain-appropriate heuristics — e.g. form-design principles for data-entry-heavy tools, accessibility guidelines (contrast, keyboard operability, labels) for any product that must be inclusive, or content-clarity checks for information-dense screens. Name the supplementary lens you're adding and why.

3. Inspect systematically

Walk the interface deliberately, not randomly:

  • Go screen by screen and flow by flow, in the order a user would meet them. Include the unglamorous states: empty states, loading, errors, edge cases, the very first use.
  • Do two passes. First pass: get a feel for the flow and overall structure. Second pass: inspect each element closely against every heuristic. Single-pass evaluations miss issues that only make sense once you know where the flow goes.
  • For each screen, ask of every heuristic: is this honored or violated here?
  • Capture the problem where you see it, with enough specificity that someone could find the exact spot and understand the issue without you narrating it.

4. Log each issue consistently

Freeform notes don't aggregate. Record each issue with the same fields so the findings can be sorted, counted, and prioritized:

  • Location — the screen/flow/element where it occurs.
  • The problem — what's wrong, described concretely (what a user would experience), not just "confusing."
  • Heuristic(s) violated — which principle(s) it breaks; an issue can break more than one.
  • Severity — see below.
  • Recommendation — a concrete direction to fix it (even tentative).
  • Optionally an evidence note or screenshot reference.

A lightweight tagging system on top of heuristics helps teams triage at a glance — for example tagging each issue by the type of fix it implies (clarity, consistency, efficiency, visual/UI, error-handling, accessibility). Define whatever tags fit the product and use them consistently; the value is a shared vocabulary the team can filter on, not the specific labels.

5. Rate severity

Severity is what turns a long list into a plan. Rate each issue by combining:

  • Impact — how badly it hurts the user when hit (blocks the task entirely? causes errors? slows them down? merely cosmetic?).
  • Frequency — how many users will hit it and how often (on a core path everyone travels, or a rare edge case?).
  • Persistence — is it a one-time hurdle people learn around, or a repeated irritation?

A simple, defensible scale:

  • Critical — blocks task completion or causes data loss; fix before release.
  • Serious — causes real difficulty, errors, or frustration on a common path; high priority.
  • Minor — slows or annoys but users get through; fix when convenient.
  • Cosmetic — polish; fix if time allows.

Always show the reasoning for a rating, not just the label — "Serious: on the primary signup path (high frequency), users can't tell the form submitted, so some will submit twice." That reasoning is what lets a PM trust and act on it.

6. Write the findings report

Structure the report so a busy team can act on it:

# Heuristic Evaluation: [product / flow]
## Overview
  What was evaluated, against which heuristics, on what device/version, scope and limits
## Summary
  Headline: how many issues by severity, the 2–3 biggest risks, overall read
## Findings (most to least severe)
  For each issue: location, problem, heuristic(s), severity + reasoning,
  recommendation, screenshot/evidence
## Recommendations, prioritized
  What to fix first, grouped by effort/impact where possible
## Method & limitations
  Expert inspection, no users involved; note this complements user testing

Lead with severity, keep each finding self-contained, and make recommendations concrete. A finding a developer can act on without a meeting is worth ten vague observations.

Producing the deliverables

Generate a ready-to-use findings report (default Markdown; offer .docx or a .xlsx issue log if the user wants to hand it around or track fixes — a spreadsheet with one row per issue and columns for location/heuristic/severity/ recommendation/status is the natural format for triage). Use clearly marked [placeholders] for anything you can't observe, and never invent findings about an interface you haven't actually seen.

Pairs well with

  • accessibility-review — run alongside for the a11y dimension; together they cover usability and accessibility.
  • ux-usability-study — expert inspection is fast and cheap; user testing tells you what people actually do. Use both.
  • design-fundamentals — the underlying principles behind many heuristic findings.

Sources & scope

Nielsen's ten heuristics are an established framework you can name and reference freely. Evaluating the user's own product — their screens, notes, prior findings — is exactly the intended use. Two cautions about other people's material: don't reproduce a third party's copyrighted text (e.g. a paid inspection template), and when you invent an illustrative example, use fictional findings rather than another organization's confidential evaluation.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.