What is the ux-heuristics skill?
ux-heuristics is a skill in the aAAaqwq/AGI-Super-Team repository. It guides an AI coding agent through a usability audit using Krug's three laws, the Trunk Test, Nielsen's ten heuristics and a 0 to 4 severity scale, then rates the interface from 0 to 10 with specific fixes.
The skill opens with a blunt premise: users do not read, they scan. They do not choose the best option, they satisfice. They do not work out how things function, they muddle through. Everything else in the file follows from that.
Its metadata credits the author as wondelai and lists version 1.3.0. The skill triggers on phrases such as usability audit, UX review, users are confused, heuristic evaluation, form usability and navigation problems.
How the audit is scored
The agent rates an interface from 0 to 10 against the principles in the file, always gives the current score, and lists the specific improvements needed to reach 10. Each issue also gets a severity from 0 to 4.
| Severity | Meaning | Priority |
|---|---|---|
| 0 | Not a problem, only a disagreement | Ignore |
| 1 | Cosmetic | Fix if time |
| 2 | Minor, causes delay or frustration | Schedule fix |
| 3 | Major, significant task failure | Fix soon |
| 4 | Catastrophic, prevents task completion | Fix immediately |
Ratings weigh three factors together: how often the problem occurs, how severe it is when it does, and whether it is a one-time or ongoing problem.
Krug's laws and the Trunk Test
Three laws come from Krug: Don't Make Me Think, It Doesn't Matter How Many Clicks, and Get Rid of Half the Words. The fourth tool is the Trunk Test, six questions a user should answer after landing on any random page.
Each concept comes with product-application tables, copy patterns and an ethical boundary. For example, plain language must never hide unfavorable terms, and extra steps must never bury cancellation flows.
Who the ux-heuristics skill is for
Best for
- Reviewing a design or a live page for usability issues before launch, with a score and a ranked list of fixes.
- Form and navigation problems, since the common mistakes table covers missing inline validation, unclear required fields and absent you-are-here cues.
- Teams that want a shared vocabulary. Pair it with design-auditor for visual checks and UX copy for the words.
Not for
- Visual design fixes, which the skill hands to refactoring-ui, or conversion audits, which it hands to cro-methodology. For the latter see also page CRO.
- Replacing real user testing. It is a heuristic review, and it lists usability testing as one of its own triggers.
- A full accessibility review. A WCAG checklist reference is included, but use a dedicated accessibility audit for depth.
Use it with UiChemy
A usability audit produces findings, not pages. If your site is built with UiChemy, use Composer, the AI visual editor, to apply fixes such as clearer labels inside Elementor or Gutenberg. Click Get Started on uichemy.com.
How to install UX Heuristics Skill: Nielsen, Krug and Severity Ratings
git clone https://github.com/aAAaqwq/AGI-Super-Team.gitClone the repository
Run
git clone https://github.com/aAAaqwq/AGI-Super-Team.git. The skill sits in skills/ux-heuristics.Copy the skill folder
Copy skills/ux-heuristics, with its references subfolder, into the folder your agent loads skills from. For Claude Code the README says skills install to .claude/skills.
Know what the repository installer does
The README's installer sets up a whole agent team, with roles, specialists and adapters. It is not a per-skill install, so this page lists the copy route.
Keep the reference files
SKILL.md links to files in references, such as the audit template and the Nielsen detail file, so keep the folder intact.
Check that it loaded
Ask your agent to run a usability audit on a signup form. It should return a score out of 10, name issues against Nielsen's heuristics, and give each a severity from 0 to 4.
Key features
- 0 to 10 scoringRates an interface against the principles, gives the current score and names the improvements needed to reach 10 out of 10.
- Krug's three lawsDon't Make Me Think, It Doesn't Matter How Many Clicks, and Get Rid of Half the Words, each with key insights and copy patterns.
- Trunk TestSix questions about the site, the page, major sections, the options at this level, the position in the hierarchy and search.
- Nielsen's ten heuristicsCovers system status, real-world match, user control, consistency, error prevention, recognition over recall, flexibility, minimalist design, error recovery, and help.
- Severity scaleFive levels from not a problem to catastrophic, rated on frequency, impact and persistence.
- Common mistakes tableLists mystery meat navigation, too many choices, no you-are-here indicator, no inline validation, unclear required fields, walls of text and jargon, each with a fix.
- Before and after copyExamples such as turning a long password notice into: Enter your password to continue.
- Ethical boundariesEach concept ends with a note on how to avoid using it to hide terms, trap users or mislead.
- Seven reference filesAn audit template, cultural UX, dark patterns, heuristic conflicts, Krug principles, Nielsen heuristics and a WCAG checklist.
Frequently asked questions
What does the ux-heuristics skill do?
It guides an AI coding agent through a usability review using Krug's laws, the Trunk Test, Nielsen's ten heuristics and a 0 to 4 severity scale. The agent rates the interface from 0 to 10 and lists specific improvements to reach a full score.
How do I install ux-heuristics?
Clone aAAaqwq/AGI-Super-Team and copy the skills/ux-heuristics folder, including references, into your agent's skills folder. The repository's own installer sets up a full agent team rather than one skill, so the manual copy is the narrower option.
Which heuristics does it use?
Nielsen's ten: visibility of system status, match with the real world, user control and freedom, consistency and standards, error prevention, recognition rather than recall, flexibility and efficiency, minimalist design, error recovery, and help and documentation.
What is the Trunk Test?
It asks whether a user dropped on any random page can answer six questions: what site this is, what page this is, the major sections, the options at this level, where they sit in the hierarchy, and how to search.
Can I use it with agents other than Claude Code?
The README says the repository supports Claude Code, Codex, OpenClaw, Hermes and other local agent frameworks through adapters, and that skills follow the agentskills.io standard. Whether a given tool loads this skill folder depends on how it reads skills.
How does the severity rating work?
Each issue gets a rating from 0 for not a problem to 4 for catastrophic. The rating considers frequency, impact and persistence. Rating 1 is cosmetic, 2 is minor, and 3 is major, with suggested priorities from fix if time to fix immediately.
Does it replace user testing?
No. It is a heuristic evaluation, an expert-style review against known principles. The skill names usability testing and cognitive walkthroughs among its triggers, so use it to find likely problems and still observe real users.
What license does ux-heuristics use?
The AGI-Super-Team repository is MIT licensed, and the skill's frontmatter also lists MIT. Check the license file in the repository before you copy the skill into anything you plan to redistribute to others.