Web App UX Auditor Skill

A portable Agent Skill by Ajnas NB for auditing and improving web app UI/UX flows across React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Angular, Solid, Remix, Astro, and plain HTML/CSS/JavaScript.

Use it when you want an AI coding agent to inspect a web app, map real user flows, find UX friction, and propose or implement improvements with evidence instead of generic "make it cleaner" advice.

What it helps with

• Navigation, information architecture, route state, browser back/forward, deep links, and re-entry flows.
• First visit, onboarding, sign-in/sign-up, dashboards, search, checkout, settings, and conversion flows.
• Forms, validation, autofill, password-manager support, empty/loading/error/offline states.
• Accessibility: semantic HTML, labels, landmarks, keyboard access, focus management, dialogs, contrast, reduced motion, and screen reader announcements.
• Responsive behavior across mobile, tablet, desktop, zoomed text, long strings, and RTL/localized content.
• Performance as UX: Core Web Vitals, LCP, INP, CLS, route transitions, hydration, bundles, and perceived latency.
• Ethical retention through saved progress, useful reminders, trust, and repeated value.
• Static code triage with a bundled Python scanner.

Install globally

npx web-app-ux-auditor-skill --global

An interactive terminal may omit the mode and choose from a prompt. Scripts, CI, and other noninteractive shells must pass --global and/or --project; a no-argument noninteractive run fails without writing files.

The interactive installer asks where to install:

1. Global current user: Claude Code, Codex, and shared Agent Skills.
2. Current project: local skills plus adapter files for popular coding agents.
3. Both global and current project.
4. Custom project path.

Global install copies the skill for the current user into:

• ~/.claude/skills/web-app-ux-auditor
• ~/.agents/skills/web-app-ux-auditor
• ~/.codex/skills/web-app-ux-auditor

Restart your agent app after installing.

Use it

Claude Code:

/web-app-ux-auditor

Codex:

$web-app-ux-auditor

Example prompts:

/web-app-ux-auditor audit the signup and dashboard flow in this Next.js app

$web-app-ux-auditor review this checkout flow for accessibility, keyboard UX, and Core Web Vitals

Install into one project

npx web-app-ux-auditor-skill --project .

Project install copies the canonical skill into .claude/skills/ and .agents/skills/, then writes adapter rule files for common coding agents:

• Cursor
• Windsurf
• GitHub Copilot
• Gemini
• Continue
• Cline
• Roo Code
• Kiro
• Trae
• OpenCode

Copy only the skill folders and skip adapter files:

npx web-app-ux-auditor-skill --project . --no-adapters

Skip prompts with an explicit global destination:

npx web-app-ux-auditor-skill --global --yes

Select global destinations explicitly:

npx web-app-ux-auditor-skill --global --targets claude,agents,codex-legacy

Project installs require an existing real directory. The installer rejects unknown options, missing values, ambiguous managed markers, and destination paths that traverse symbolic links, junctions, or reparse points. Adapter updates preserve user content and insert or replace only the block delimited by <!-- web-app-ux-auditor:start --> and <!-- web-app-ux-auditor:end -->. In particular, .opencode/AGENTS.md is never replaced as a whole file.

Static scanner

The skill includes a Python scanner for static web UX signals:

python scripts/web_ux_static_scan.py /path/to/web-app

The scanner detects review signals such as non-semantic click targets, missing image alt text, placeholder-label risks, missing button types, focus-outline removal, dialog risks, and mobile viewport issues.

Linked files and directories are skipped; resolved scan inputs must remain inside the selected root.

It is a triage tool, not a replacement for expert review. Confirm every finding in code, browser, screenshots, accessibility tooling, performance traces, or tests before changing behavior.

Package layout

web-app-ux-auditor/
  SKILL.md
  agents/openai.yaml
  references/web-ux-audit-reference.md
  scripts/web_ux_static_scan.py
  skills/web-app-ux-auditor/
  .codex-plugin/plugin.json
  .claude-plugin/plugin.json
  bin/install.js
  package.json

The root SKILL.md supports direct skill installation. The skills/web-app-ux-auditor/ copy supports plugin-style discovery.

Publish to GitHub

gh auth login
gh repo create AjnasNB/web-app-ux-auditor-skill --public --source . --remote origin --push

If the repo already exists:

git remote add origin https://github.com/AjnasNB/web-app-ux-auditor-skill.git
git push -u origin main

Download from npm

Install and run without keeping the package:

npx web-app-ux-auditor-skill --global

Install the CLI globally:

npm install -g web-app-ux-auditor-skill
web-app-ux-auditor --global

Publish to npm

Log in once:

npm adduser

Check the package:

npm ci
npm run release:check

Publish:

npm publish --access public

After publishing, users download and install it with:

npx web-app-ux-auditor-skill --global

Or install the CLI globally:

npm install -g web-app-ux-auditor-skill
web-app-ux-auditor --global

See SECURITY.md for vulnerability reporting. The repository-only RELEASING.md contains the maintainer checklist and is intentionally excluded from the npm tarball.

License

MIT