ui-audit — Claude Code skill: what it does, how to install
Evaluates user interfaces against core UX guidelines from Making UX Decisions. Spots hierarchy flaws, navigation issues, and accessibility oversights.
npx skills add tommygeoco/ui-audit --skill ui-audit -a claude-codeWhat ui-audit does
This skill injects structured decision trees and reference files directly into the coding agent. It draws on Tommy Geoco's framework to review component states, visual styles, and user flows. The tool inspects layouts by weighing organizational constraints against user familiarity and empirical findings.
Audit outputs follow a strict JSON schema. Mandatory sections cover visual hierarchy, styling consistency, and core accessibility targets like keyboard focus and contrast ratios. Conditional sections trigger for complex inputs, onboarding tours, or multi-step navigation.
To rank fixes effectively, the model demands clear product priorities: speed, waste reduction, high accuracy, or novelty. Without knowing these strategic bets, the agent cannot weigh UI trade-offs accurately.
What it helps with
- audit component layouts for contrast, touch targets, and keyboard navigation
- spot defects in typography scale, spacing consistency, and visual hierarchy
- select suitable UI patterns for progressive disclosure and form wizards
- generate structured JSON audit logs detailing prioritized interface fixes
Example prompts for the agent
- Run an accessibility and visual hierarchy audit on the checkout flow component.
- Audit this settings screen and return the findings using the JSON report format.
- Recommend the best pattern to reduce cognitive load in this multi-step onboarding wizard.
How to install ui-audit
1Skills CLI (Vercel)
npx skills add tommygeoco/ui-audit --skill ui-audit -a claude-code2Manually: put the files in place
~/.claude/skills/ui-audit/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ui-audit/
1Skills CLI (Vercel)
npx skills add tommygeoco/ui-audit --skill ui-audit -a codex2Manually: put the files in place
.agents/skills/ui-audit/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add tommygeoco/ui-audit --skill ui-audit -a cursor2Manually: put the files in place
.cursor/skills/ui-audit/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install tommygeoco/ui-audit ui-audit2Manually: put the files in place
.github/skills/ui-audit/SKILL.md1Skills CLI (Vercel)
npx skills add tommygeoco/ui-audit --skill ui-audit -a gemini-cli2Platform CLI
gemini skills install https://github.com/tommygeoco/ui-auditManually: put the files in place
.devin/skills/ui-audit/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add tommygeoco/ui-audit --skill ui-audit -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ui-audit
How to install ui-audit in Claude Code?
Run npx skills add tommygeoco/ui-audit --skill ui-audit -a claude-code. The skill writes its reference files to ~/.claude/skills/ui-audit/SKILL.md.
What does ui-audit do?
It instructs your AI assistant to evaluate screens against UX checklists and design patterns. The audit flags layout defects, accessibility gaps, and component styling issues.
What sections are required in every audit report?
Every generated audit must include Visual Hierarchy, Visual Style, and Accessibility reviews. Navigation, onboarding, and form validations appear only when relevant to the analyzed screen.
