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

There’s a quiet waste in how most people use a frontier model: they point the smartest, most expensive model at a codebase and then have it do everything — the deep thinking and the mechanical edits. Understanding the architecture and deciding what’s worth fixing is where that intelligence pays off. Renaming a symbol across forty files is not.

shadcn/improve splits those apart. It uses your most capable model for the part where intelligence compounds — mapping the repo, judging what matters, writing the spec — and produces plans detailed enough that a cheaper, faster model can execute them without supervision. The slogan for the skill is blunt: the plan is the product.

Note

improve is an Agent Skill, so the same install and commands work identically across Claude Code, Cursor, and Codex (and any other Agent Skills-compatible host). The plans it writes are plain Markdown, so any agent — or human — can pick them up. Released June 2026, MIT-licensed, by shadcn.

What you’ll walk away with

• The expensive-thinking / cheap-execution model and why it saves tokens
• How to install improve in any agent
• The recon → audit → vet → prioritize pipeline it runs
• The full /improve command reference
• What makes its plans executable by weaker models — and the guardrails that keep it read-only

Install

npx skills add shadcn/improve

That’s the whole setup — it works in any agent that supports the Agent Skills format. Once installed, you drive everything through the /improve command.

How it works

1. Recon. It maps the repo: stack, conventions, and the exact build/test/lint commands. Those commands become the verification gates baked into every plan. It also ingests design docs it finds — ADRs, PRDs, CONTEXT.md, DESIGN.md, PRODUCT.md — so the audit is grounded in your intent, not just your code.

2. Audit. It fans out parallel subagents across nine categories: correctness, security, performance, test coverage, tech debt, dependencies & migrations, DX, docs, and direction.

3. Vet. Before showing you anything, the advisor re-reads every cited location to eliminate false positives — so the findings table isn’t padded with hallucinated line numbers.

4. Prioritize. Results are ordered by leverage: impact ÷ effort, weighted by confidence. You get a findings table, you reply with the ones you want planned (“plan 1, 3 and 5”), and each becomes a self-contained file in plans/ plus an index with the recommended order.

Command reference

/improve                     # full audit → prioritized findings → plans
/improve quick               # cheap pass: hotspots and top findings only
/improve deep                # exhaustive: every package, every category
/improve security            # focused audit (also: perf, tests, bugs, ...)
/improve branch              # audit only what the current branch changes
/improve next                # feature suggestions -- where to take the project
/improve plan <description>  # skip the audit, spec one specific thing
/improve review-plan <file>  # critique and tighten an existing plan
/improve execute <plan>      # dispatch a cheaper executor, review its work
/improve reconcile           # refresh the backlog: verify, unblock, retire
/improve ... --issues        # also publish plans as GitHub issues

A typical session: run /improve (or /improve quick on a large repo), skim the findings, pick a few to plan, then either /improve execute 001 to hand the first plan to a cheaper executor or hand the plans/ files to a separate agent or teammate. Next session, /improve reconcile verifies what shipped, refreshes what drifted, and retires what’s stale.

Tip

/improve branch is the underrated one. Before you open a PR, run it to audit only what your branch changed. It’s a fast, focused self-review against the same nine categories — without auditing the whole repo every time.

Why the plans are executable

A plan is only useful to a cheap model if it leaves nothing to guess. improve enforces three properties:

• Self-contained. All context is inlined — exact file paths, current-state code excerpts, the repo conventions to follow. The executor never has to go discover anything.
• Verification gates. Every step ends with a command and its expected output, so the executor knows when it’s actually done rather than declaring victory early.
• Hard boundaries. Explicit out-of-scope lists and STOP conditions keep a weaker model from wandering off the task into a refactor nobody asked for.

This is the same discipline that makes a /goal run terminate cleanly — a clear spec with checkable gates — applied to handoffs between models.

Guardrails

Caution

improve is deliberately read-only on your source. It:

• never modifies source code — it writes only to plans/;
• never mutates the working tree — the analysis is read-only;
• never reproduces secret values it encounters;
• declines to implement — ask it to write the code and it points you back to the plan instead.

That separation is the point: the advisor advises, a separate (cheaper) executor ships. Keep a human reviewing the diff the executor produces.

When to reach for it

• Inheriting an unfamiliar codebase and you want a prioritized map before touching anything.
• You have frontier-model budget for thinking but want to run execution on a cheaper tier.
• Pre-PR self-review (/improve branch).
• Deciding where to take the project next (/improve next) rather than just fixing what’s there.

Where to go next

Impeccable: design vocabulary for AI The design-quality counterpart -- a skill that audits and polishes frontend instead of architecture.

Installing and managing skills How npx skills add works, and how to keep skills updated across tools.

The /goal command Hand a self-contained plan to an autonomous run with a verifiable finish line.

Grill Me & Grill With Docs The alignment counterpart -- the agent interviews you until you and it agree, before any plan or code.