Frontend-review Skill — the steering brain
You drive a front-end conventions review. The actual analysis lives in the
frontend-review subagent (.claude/agents/frontend-review.md) — this skill
decides what scope and how deep, spawns the agent (fanning out for 5+ files),
collates findings into one severity-rated report, and then offers to comment
them on the PR or fix the safe ones. Keep the analysis logic in the agent; keep
orchestration here.
This is the front-end-conventions member of the code-cleaning family. It deliberately
mirrors .claude/skills/a11y/SKILL.md (diff-scoped, 3-level severity, the same
report format, an offer-to-fix step) and the red-team skill/agent split (depth
ladder, spawn-and-collate) — just for Nuxt UI 4 / crouton component conventions
instead of accessibility or bugs.
Why a separate skill (not folded into /review)
/review is a broad correctness/security/dead-code pass and only carries a handful
of Nuxt UI bullets as honor-system reminders. This skill is the dedicated,
diff-scoped, severity-rated, fixable, CI-gated front-end-conventions layer — it owns
the full convention checklist, the v3→v4 rename autofix, and the per-PR gate. Exactly
like /a11y and /red-team sit beside /review rather than inside it.
What it does not do: visual/layout taste ("this should be a card") — that's the
human /ui-proposal sign-off; accessibility — that's /a11y; security — that's
/red-team. Conventions only.
1. Resolve { depth, scope, comment, fix } from the request
Scope (mirrors the review skill's modes):
| Invocation | What it reviews | scope passed to agent |
|---|
/frontend-review | All uncommitted .vue changes (staged + unstaged) | "diff" |
/frontend-review last N | .vue files in the last N commits | "diff" (vs HEAD~N) |
/frontend-review --scope <pkg> | A whole package's .vue | packages/<pkg> (or apps/<pkg>) |
/frontend-review --file <path> | A single .vue file | that path |
Depth (mirrors red-team's ladder):
| The user said… | depth |
|---|
/frontend-review (bare), a PR/diff context, quick | quick (static, diff-scoped) |
/frontend-review --scope <pkg> / standard | standard (full static sweep of the scope) |
/frontend-review deep / "check against real Nuxt UI" | deep (static + cross-check the real @nuxt/ui component set) |
Defaults: a bare /frontend-review on a working tree → quick + "diff". A
--scope/--file with no depth → standard. Only go deep when explicitly asked.
Flags: --comment → post findings as inline PR comments. --fix → apply the safe
remediations (v3→v4 renames, redundant-overlay-UCard unwraps) to the working tree.
Both can combine with any scope/depth.
2. Severity map (reuse the review skill's 3 levels + format)
| Level | Meaning | Sources |
|---|
| 🔴 Critical | A hard, documented convention break — blocks the CI gate | v3 component name (UDropdown/UDivider/UToggle/UNotification); UCard inside UModal/USlideover/UDrawer; Options API in a .vue; overlay clearly missing the #content="{ close }" pattern |
| 🟡 Warning | Likely off-convention; advisory | raw <button>/<input>/<select>/<textarea>/internal <a> where a Nuxt UI / crouton component applies; hand-rolled overlay markup; hardcoded brand/semantic color |
| 🔵 Note | Polish | bare export default {} nit; one-off hardcoded color; minor drift |
Same emoji + report format as /review and /a11y, so a mixed code-cleaning pass
reads consistently.
3. Gather the scope
Uncommitted (/frontend-review, --scope, --file):
git diff --name-only --diff-filter=d | grep -E '\.vue$' # unstaged
git diff --cached --name-only --diff-filter=d | grep -E '\.vue$' # staged
Recent commits (/frontend-review last N):
git diff --name-only HEAD~N..HEAD | grep -E '\.vue$'
If --scope is set, Glob packages/<pkg>/**/*.vue (or apps/<pkg>/**/*.vue).
If the diff has no .vue files, say so and stop — this skill only reviews templates.
4. Spawn the subagent
Spawn frontend-review via the Agent tool with { scope, depth, fix } in the prompt.
- < 5 files → one subagent (or just do the static pass inline if it's a single
small file — agent overhead isn't worth it for one
--file).
- 5+ files → fan out: split the files into groups (by directory —
components/, pages/, layouts/), spawn one frontend-review subagent per group
with its file subset as scope, and launch them in parallel (multiple Agent
calls in one message). Same parallelization rule as /review. The agents are
synchronous — you hold their results when they return; never report "running in
the background".
Pass fix through only when the user asked for --fix (so a plain review run never
touches files).
5. Collate & report
Merge the agents' findings, de-dupe anything the same rule flagged twice, and print
the review skill's report format:
## Frontend Review Summary
| Severity | Count |
|----------|-------|
| 🔴 Critical | X |
| 🟡 Warning | Y |
| 🔵 Note | Z |
### 🔴 Critical
#### [Short title]
**File:** `path/to/file.vue:42`
**Rule:** `v3-name` (or overlay-ucard / overlay-content-slot / options-api / raw-html / hardcoded-color)
**Issue:** [Which convention is broken — "uses the v3 `UDropdown`; v4 is `UDropdownMenu`"]
**Fix:** [The exact rename/component to use]
--- (repeat for 🟡 / 🔵)
If nothing found:
## Frontend Review: clean ✅
Reviewed N templates, no convention issues found.
Mark each finding confirmed (a deterministic signal backs it) vs suspected (a
reasoned smell), mirroring red-team/a11y — don't present a reasoned raw-<button>
call as a confirmed violation.
6. --comment — inline PR comments
When --comment is set and the work is on a PR, post each finding as an inline
review comment on the offending file:line, dovetailing with the existing
🎯 Preview feedback / ♿ A11y machinery:
mcp__github__pull_request_read to resolve the PR for the current branch and its
head SHA.- For each finding,
mcp__github__add_comment_to_pending_review with the file path
and line, body = the finding (lead with the 🔴/🟡/🔵 + rule, then Issue/Fix).
Prefix the body with a 🧩 Frontend tag so it's distinguishable from
🎯 Preview feedback, ♿ A11y, and code-review comments.
mcp__github__pull_request_review_write to submit the pending review as COMMENT
(never auto-REQUEST_CHANGES / APPROVE).
If there's no PR (local-only), skip inline comments and just print the report — say so
rather than erroring.
7. --fix — apply safe remediations
When --fix is set, the agent applies (or you apply, for a small inline run) only
the safe, deterministic rewrites — the same set the agent doc lists:
- v3 → v4 name rename (
UDropdown→UDropdownMenu, UDivider→USeparator,
UToggle→USwitch, UNotification→UToast) — checking props still map; report
anything ambiguous instead of guessing.
- Redundant
UCard inside an overlay (pure wrapper, no card props) → unwrap into the
#content slot's <div class="p-6">.
Then pnpm typecheck the affected app(s)/package — never leave the tree red:
pnpm -r --filter './apps/*' typecheck # or the specific package's typecheck
Anything needing real judgment (raw <button>→UButton behaviour, an
Options→<script setup> migration, a color→token swap) is reported, not auto-fixed.
8. Offer to fix (when not already --fix)
After printing the report (and any --comments), close with the review skill's offer:
Want me to fix any of these? (all / critical only / pick by number)
If the user says "all" or "critical only", apply the safe remediations directly — no
per-fix confirmation — then pnpm typecheck. Findings that aren't in the safe set get
called out as "needs a human decision" with the reason (e.g. "raw <button>→UButton
needs prop/slot judgment").
Relationship to the other entry points
/review carries a few Nuxt UI v4 bullets as honor-system reminders;
/frontend-review is the dedicated, diff-scoped, severity-rated, fixable layer
that owns the full convention checklist + the v3→v4 autofix.- It sits beside
/a11y (accessibility), /ui-proposal (human design-look
sign-off), /review (general code review), and /red-team (security) —
same spawn-and-collate shape, different lens. Reach for /frontend-review when you
specifically want "are we on Nuxt UI 4 / crouton components, correctly", with the
option to comment or fix.
- CI runs the same engine automatically (mirroring the red-team/a11y workflows):
.github/workflows/frontend-review.yml runs the subagent at depth=quick on a PR
diff — posts a sticky <!-- frontend-review --> comment and fails the check on a
🔴 finding (diff-scoped, so never on the pre-existing backlog). /frontend-review
is the on-demand brain and human entry point for the same machinery. The workflow
MUST follow the Claude-action workflow standard in .claude/agents/CLAUDE.md —
notably the --allowedTools grant, without which the gate fails open (#834/#1036).