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
- mshadmanrahman/claude-for-designerstheir own version, first seen Sep 29, 2026
- henrique-simoes/Istaratheir own version, first seen Sep 27, 2026
- miovrag/claude-skillstheir own version, first seen Jun 12, 2026
- launchapp-dev/animus-clitheir own version, first seen Mar 15, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- launchapp-dev/animus-cli★ 39same name
- mshadmanrahman/claude-for-designers★ 32same name
- henrique-simoes/Istara★ 15same name
- miovrag/claude-skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
- accessibility-reviewSkill
- competitive-analysisSkill
- design-fundamentalsSkill
- inclusive-designSkill
- persona-builderSkill
- ux-usability-studySkill
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
- Distinctive: line 30
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 …
- Distinctive: line 37
Before inspecting anything, pin down:
- Distinctive: line 48
If the user has screenshots, a prototype link, or a live URL, work from that.
- Distinctive: line 61
Show system status: Keep people informed about what's happening through timely, visible feedback — loading states, confirmations, progress.
- Distinctive: line 72
Favor recognition over recall: Keep options, actions, and information visible so people don't have to remember things across steps.
- Distinctive: line 76
Keep it minimal: Every extra element competes for attention.
- Distinctive: line 80
Provide help and documentation: When needed, help should be easy to find, task-focused, and concrete.
- Distinctive: line 96
Do two passes. First pass: get a feel for the flow and overall structure.
- Distinctive: line 142
Always show the *reasoning* for a rating, not just the label — "Serious: on the primary signup path (high frequency), users can't tell the …
“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.
Files
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:
- Show system status. Keep people informed about what's happening through timely, visible feedback — loading states, confirmations, progress.
- Match the real world. Speak the user's language and follow real-world conventions rather than internal jargon or system-oriented terms.
- Give control and freedom. Provide clear exits, undo, and a way back out of mistakes without feeling trapped.
- 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.
- Prevent errors. Design so the slip can't happen in the first place — constraints, good defaults, confirmation on destructive actions.
- Favor recognition over recall. Keep options, actions, and information visible so people don't have to remember things across steps.
- Be flexible and efficient. Let novices succeed while giving experts accelerators (shortcuts, saved states) to go faster.
- Keep it minimal. Every extra element competes for attention; remove or downplay what isn't needed so the essential stands out.
- Help users recover from errors. Error messages should be in plain language, say what went wrong, and offer a way to fix it.
- 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 testingLead 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.
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
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.

