shadcn/improve: Audit With Your Best Model, Execute With a Cheap One

shadcn shipped a skill that refuses to touch your code. The shadcn/improve repository is trending with roughly 10,400 GitHub stars (~10,357 on GitHub’s API as of 11 November 2026) and about 333 stars gained in a single day in mid-November 2026. The README pitch: use your most capable model for the part where intelligence compounds — understanding the codebase, judging what is worth doing, writing the spec — and hand execution to cheaper models.

That pattern sits at the intersection of agent skills, token economics for coding agents, and model routing posts. It is not another harness like Herdr; it is a plan factory you install beside Claude Code, Cursor, or Codex.

TL;DR

Why plans instead of patches

Autonomous agents that edit production repos directly accumulate scope creep, false-positive fixes, and unreviewed diffs. shadcn’s README draws a hard line: the skill is an advisor, not an implementer.

The workflow diagram in the README is explicit:

• You run /improve with an expensive model.
• Selected findings become markdown files under plans/.
• Another agent (or /improve execute) implements inside an isolated git worktree.
• Humans merge.

That mirrors how senior engineers already work — design review before implementation — but encoded as machine-checkable plan structure.

Install and first session

npx skills add shadcn/improve

Open your agent in the repository root and run /improve, or /improve quick for a cheaper pass. The skill recons the repo: stack, conventions, build and test commands, and optional intent docs such as DESIGN.md, PRODUCT.md, or ADRs under docs/adr/.

It then fans out parallel subagents across nine audit categories: correctness, security, performance, test coverage, tech debt, dependencies and migrations, developer experience, documentation, and direction (feature suggestions with evidence).

Results land in a prioritized table (impact, effort, confidence). You reply with which rows to plan — for example, “plan 1, 3, and 5.”

What makes a plan executable

The README stresses three properties so a weaker executor can succeed without the advisor session in context.

Self-contained context. Exact paths, excerpts of current code, conventions, and verified commands are inlined. No “as discussed above.”

Verification gates. Every step ends with a command and expected output. Done criteria are meant to be mechanical.

Hard boundaries. Out-of-scope lists and STOP conditions — “if X, stop and report” — instead of improvisation when reality diverges.

Each plan stamps the git commit it was written against so executors run a drift check before editing.

That is stronger spec discipline than most ad-hoc “fix the N+1” prompts, and it pairs naturally with Worktrunk worktrees for physical isolation.

Commands worth knowing

The README’s shadcn/ui example table shows real rows — shadow config duplicated between files, O(n²) icon migration — plus rejected findings with reasons so they do not reappear next run.

Vet step and false positives

Subagents over-report. The advisor re-reads every cited file:line before you see a finding. False positives drop; wrong attributions get corrected; rejections are recorded.

That is the same human lesson from AI usage fragile codebase threads: raw model output is noisy; a second pass with evidence rules matters.

Execute and reconcile

/improve execute spawns a cheaper executor in a disposable worktree, reruns done criteria, checks scope, and returns a verdict: approve, send back (max two rounds), or block and refine the plan.

/improve reconcile is backlog hygiene — verify landed fixes, rewrite blocked plans, refresh drifted specs.

For teams that live in GitHub Issues, --issues copies the self-contained plan body into tickets so any agent can pick them up — similar intent to benjitaylor/skills Stageshow demos, but for refactors not UI.

Security and secrets handling

Hard rules: never reproduce secret values in plans — locations and credential types only, with rotation recommended. The skill also refuses commands that mutate your working tree during audit (read-only analysis).

Still run improve on repos you are authorized to assess. Publishing audit output from third-party code without disclosure remains unethical, even when the skill is MIT.

How this compares to other skill packs

Improve is narrower and therefore easier to adopt on a mature codebase you already trust shadcn’s judgment on.

Honest limits

Plans are not merges. If your team skips human review, you have only moved risk from live edits to live executors.

Executor quality still matters. A vague plan fails even with worktrees. Budget time for review-plan.

Not a scanner replacement. Security findings here are model-judged, not a substitute for Codex Security or SARIF pipelines.

Cost shifts, does not disappear. Deep audits on monorepos still burn top-tier tokens; you save on execution, not on thinking.

Worked session shape (from the README)

The repository documents a full loop you can copy on a mature TypeScript monorepo such as shadcn/ui itself.

Step 1 — Recon without writes. The skill maps package boundaries, import graphs, test entrypoints, and lint commands. Those commands become verification gates copied verbatim into every plan so executors cannot invent fake npm test scripts.

Step 2 — Parallel audit fan-out. Nine category subagents return file:line citations. You should expect duplicates and overlaps; the vet pass is what collapses noise before you see a table.

Step 3 — Human or lead selection. Reply with numeric rows to plan. This is the product decision: tech debt versus security versus perf. The skill does not auto-prioritize business risk.

Step 4 — Plan files land in plans/. Each includes dependency edges in the index so executors know whether plan 003 assumes plan 001 merged first.

Step 5 — Execute in worktree. /improve execute 001 uses a cheaper model. You still read the diff. The README’s tech-lead metaphor is accurate: approve, send back twice, or block.

Step 6 — Reconcile next morning. /improve reconcile catches drift when someone fixed a bug manually on main while plan 002 was open.

That loop is longer than a single /fix prompt, but it scales when you run multiple agents on one repo without losing audit trail.

Composes with DESIGN.md and ADRs

Improve explicitly ingests DESIGN.md, PRODUCT.md, CONTEXT.md, and docs/adr/ when present. Decided tradeoffs should not re-surface as fresh findings.

If your team already ships DESIGN.md templates for agent UI work, pointing improve at the same repo gives you consistent vocabulary between design docs and refactor plans — especially valuable for Solid Glass / shadcn UI agent interfaces.

What developers should ask before adopting

Will our executors follow STOP conditions? Small models ignore boundaries when plans are vague. Run review-plan on the first three exports.

Do we have worktree hygiene? Improve assumes git worktrees for execution. Pair with Worktrunk or manual git worktree discipline.

Are we okay with plans in-repo? plans/ may contain security observations. Treat it like an internal audit folder; do not commit client secrets into plan excerpts.

How does this interact with CI? Improve is not a drop-in GitHub Action. Keep deterministic linters and Codex Security scans on pull requests; use improve for quarterly deep passes or branch-wide refactors.

Who owns merges? The skill declines on-the-spot implementation requests and points to plan files — enforce the same rule culturally so junior engineers do not bypass the advisor.

Model routing economics in plain numbers

Exact prices change weekly, but the pattern is stable: a single Opus-class audit on a large frontend monorepo can cost more than ten Haiku or Flash-class executor runs if plans are tight. Improve makes that split explicit instead of hoping one model does both jobs well.

Teams already practice informal versions of this — “senior staff writes RFC, junior implements” — but RFCs often lack verification gates. Improve’s plan template forces commands and expected output, which is what makes cheaper executors viable. Read that alongside output token inflation when you negotiate harness budgets. If your org caps premium model calls per day, schedule /improve quick on feature branches and reserve full audits for release candidates. Store approved plans in an internal wiki if you do not want plans/ committed to main.

On first install, run improve against a throwaway fork or a service repo you know well. Calibrate how aggressive the nine audit tracks are before you point the skill at production payment code. Save one exemplary plan file as a template for your own verification gate style.

Related on explainx.ai

• What are agent skills?
• npx skills install guide
• Worktrunk worktrees for parallel agents
• Herdr terminal runtime for agents
• Token inflation and model pricing
• Claude Fable vs Opus routing
• Solid Glass design system for agent UIs

Official

• github.com/shadcn/improve
• skills/ improve directory in the repo

Command list and star counts reflect the public README as of November 11, 2026.