| name | quality-audit |
| description | Stack-aware, read-only quality audit for a JavaScript/TypeScript web repo. Detects the stack (Next.js, React, shadcn, Tailwind v4, Motion) from package.json, runs real verification (lint, typecheck, build, react-doctor), then routes a dimensional review (correctness, Next.js, React performance, web vitals, shadcn/Tailwind, design polish, motion performance, accessibility, security and best practices, components, view transitions) into one P0/P1/P2 report with file:line and a concrete fix per finding. Read-only by default; opt into P0-only fixes on a branch with `mode: fix`. Use for a whole-repo quality, design, accessibility, or performance audit, a pre-ship review, or a scheduled quality scan. For a single file or diff, /code-review covers it; for a one-component design pass, design-engineer applies automatically.
|
| disable-model-invocation | true |
Quality audit
Default "review my repo" is one ad-hoc pass: it finds the obvious and misses systematically, claims checks passed without running them, and starts editing. This skill redirects the audit to detect the stack → run the lenses that stack demands → verify with real commands → triage by ship-impact — and to stay read-only until you explicitly ask for fixes. The dimension checklists are the lens contents; the routing, the honest verification, and the severity triage are the work.
Mode — set before anything
audit (default): report only. No file writes, no commits, no PRs. Tools used: Read, Grep, Glob, and read-only Bash.fix: only when the invocation literally says mode: fix. P0 findings only, on a new branch off main, re-running lint + build after. No drive-by refactors, no P1/P2 fixes.
If the invocation doesn't say mode: fix, you are in audit mode — do not edit.
Step 0 — Orient (let detection pick the lenses)
- Read intent files if present:
CLAUDE.md, AGENTS.md, README.md, CONTRIBUTING.md. They scope what "quality" means here.
- Read
package.json — scripts, packageManager, dependencies.
- Detect the stack and scope the review to what applies:
| Signal | Apply the dimension |
|---|
next in deps | Next.js (App Router, RSC, metadata, cache) |
components.json | shadcn — check its base field for Base UI vs Radix |
Tailwind v4 (tailwindcss@4, @theme in CSS) | Tailwind v4 token discipline |
cacheComponents / experimental.ppr | Cache Components / PPR review |
motion / framer-motion | Motion performance |
vitest / jest / playwright | run tests if fast |
| no React | skip React, RSC, shadcn, component, and VT dimensions |
- Find the design tokens:
app/globals.css, src/index.css, or tailwind.config.*. Read @theme before judging any className.
- Map routes / entrypoints (
app/, pages/, src/routes/).
Step 1 — Verify (run real commands, report honestly)
Use the repo's package manager (from packageManager or the lockfile — pnpm / npm / yarn / bun).
- Run, when the script exists:
lint / format / typecheck; build (apps and libraries with a build step); test only if fast (< 2 min) — otherwise note it as skipped.
- React or Next present → prefer
bun run doctor / bun run doctor:diff (or the repo's equivalent) when those scripts exist; otherwise npx -y react-doctor@latest . --verbose (add --diff for changed-files-vs-main scope). If doctor.config.json or a React Doctor section in CLAUDE.md documents intentional suppressions, do not report those as findings. If the react-doctor skill is installed, follow its triage; if the tool is unavailable or you're offline, say so and move on.
Honesty rule (load-bearing): record each check as pass/fail with the actual error quoted. State explicitly anything you did not run and why (script absent, too slow, offline). Never report a check as passing that you didn't run — a fabricated green check is worse than an admitted gap.
Step 2 — Route the dimensional review
For each applicable dimension: use the specialist skill if it's installed (it carries the depth and stays current); otherwise apply the fallback checklist in references/dimensions.md. Bundled serve skills are always present; the rest may not be — degrade gracefully and note which you actually applied.
Every finding gets: file:line, a one-sentence why, a concrete fix, and a severity — P0 (ship blocker / build error / critical a11y), P1 (should fix), P2 (polish).
| Dimension | Applies when | Depth in (skill) | The check that matters most |
|---|
| Correctness & tooling | always | Step 1 output + react-doctor | every lint/type error ≥ P1; build failure = P0 |
| Next.js | next present | next-best-practices, vercel:nextjs, vercel:next-cache-components | RSC default; await async route APIs; cache discipline |
| React performance | React present | vercel:react-best-practices, react-doctor | fetch waterfalls, bundle bloat, over-serialization |
| Web vitals (code level) | any web UI | core-web-vitals, performance | unsized media; LCP image priority; font-display; third-party script strategy |
| shadcn + Tailwind | components.json / Tailwind | shadcn-tailwind (bundled), shadcn | read @theme first; no px/#hex; render not asChild |
| Design & polish | any UI | design-engineer (bundled), make-interfaces-feel-better, emil-design-eng, web-design-guidelines | concentric radii, tabular-nums, min-h-dvh, focus-visible |
| Motion performance | animations present | fixing-motion-performance, framer-motion-animator, baseline-ui | transform/opacity only on large surfaces; no scroll-driven JS; blur ≤ 8px |
| Accessibility | any UI | fixing-accessibility, wcag-audit-patterns, accessibility | accessible names; keyboard + visible focus; native over role |
| Security & best practices | always | best-practices, npm audit | vulnerable deps and unsanitized HTML sinks = P0; security headers; SRI on CDN scripts |
| Components | component code | building-components | compose over boolean-prop explosion; controlled only when the parent needs it |
| View transitions | VT code only | vercel-react-view-transitions | default="none"; nav-level only; reduced-motion CSS |
| Project rules | always | this repo's CLAUDE.md / .cursor/rules/ / AGENTS.md | apply only rules that actually exist here — assume no template |
For a large repo, the dimensions can be fanned out across subagents — but the default is a single read-through pass; reach for parallelism only when one context can't hold the repo.
Step 3 — Report
# Quality audit — {repo} — {YYYY-MM-DD}
**Stack:** Next.js 15 · shadcn (Base UI) · Tailwind v4 · Motion
**Scope:** whole repo | changed-vs-main
**Mode:** audit | fix
**Verification:** lint ✅ · typecheck ✅ · build ❌ · tests skipped (>2 min) · react-doctor 82/100
## Summary
2–4 sentences: overall health, and the one thing to fix first.
## P0 — ship blockers
| Issue | Location | Why | Fix |
| --- | --- | --- | --- |
## P1 — should fix
| Issue | Location | Why | Fix |
| --- | --- | --- | --- |
## P2 — polish
| Issue | Location | Why | Fix |
| --- | --- | --- | --- |
## UI polish (Before | After)
### {Principle — e.g. Concentric radii}
| Before | After |
| --- | --- |
## Project rule gaps
Only if this repo's own rules (CLAUDE.md / CONTRIBUTING / .cursor/rules) were violated.
## Next step
One sentence.
Omit any section with no findings. Skip dimensions that don't apply and say so ("N/A — no React").
Boundaries
- audit (default): no writes — Read / Grep / Glob / read-only Bash only.
- fix: P0 only; branch from main first; re-run lint + build after; no drive-by refactors.
- For applying fixes to a diff rather than the whole repo, the stock
/code-review --fix (bugs) and /simplify (cleanup) are the right tools; this skill's fix mode is the whole-repo P0 complement, not a diff-level fixer.
- Never invent URLs, credentials, product copy, or verification results.
- Don't migrate UI or animation libraries unless the invocation asks for it; apply rules within the existing stack.
- The read-only default is behavioral, not enforced. For a hard guarantee, gate
Edit/Write with a PreToolUse hook (the forge skill covers hook design).
See also
