TL;DR

shadcn/improve is an Agent Skill from shadcn (the shadcn/ui creator) that treats AI coding as two very different jobs — understanding a codebase and deciding what’s worth doing (the expensive part) and actually writing the diff (the cheap part) — and only lets your most capable model do the first. The output is not a patch. The output is a directory of self-contained Markdown implementation plans in plans/ that any weaker executor — Sonnet-tier, a local model, a junior human — can pick up and finish. Currently 7,534 GitHub stars, 314 forks, MIT-licensed, and one of the most talked-about Skills to ship since Agent Skills became a format.

Key facts:

  • 7,534 GitHub stars, 314 forks — grew past 1.4K in the first 48 hours after shadcn tweeted the release
  • Created 2026-06-10, updated today (2026-07-09) — actively maintained
  • Install: npx skills add shadcn/improve (works in any host that speaks the Agent Skills format — Claude Code, Codex, OpenCode, Cursor with the Skills bridge, etc.)
  • Never touches source code — the ONLY files it writes live under plans/ (or advisor-plans/ if plans/ is already taken). No commits, no edits, no “quick wins while I’m in there.”
  • Nine audit categories with parallel subagents: correctness, security, performance, test coverage, tech debt, dependencies & migrations, DX, docs, and direction (feature suggestions)
  • Verification-gated plans — every step ends with an exact command and expected output. Executors don’t get to judge whether they succeeded.
  • Git-commit-stamped — each plan records the commit it was written against so executors can mechanical-drift-check before touching anything
  • --issues flag — publish plans directly as GitHub issues so any agent (or human) can pick them up where work already lives
  • MIT licensed, author: @shadcn

The pitch, distilled to one sentence: the plan is the product — everything upstream is worth paying Opus/GPT-5-Pro/Gemini-3-Ultra for, everything downstream isn’t.

Why “one big model does everything” is the wrong shape

If you use Claude Code, Codex, or Cursor for anything past toy scale, you’ve felt the same ergonomic problem: the model smart enough to understand your codebase is way too expensive to have hammering out find-and-replace edits at 3¢ per turn. The workarounds all break down — cheaper models misread the architecture, expensive models drain the budget on mechanical work, and “pick the right size per task” doesn’t work because the model doesn’t know which tasks are small until it’s halfway into one.

/improve names the real split. Intelligence compounds during understanding, not during execution. Reading a 40K-file monorepo, spotting the O(n²) hot path about to burn through a customer’s rate limit, deciding whether it’s worth fixing given the ADR that says the API is being deprecated in Q3 — that’s judgment work. Once the plan says “extract this function into lib/shadow-config.ts, delete the copies, run pnpm test:e2e,” a cheap model — even a local 32B — can do it.

The genius: shadcn didn’t build a router or “auto-choose the model” heuristic. He built a hard architectural split enforced by the skill contract — /improve is not allowed to modify source code, ever. The advisor and the executor are literally different processes on different budgets. Nothing to configure.

What happens on a first run

A typical /improve invocation:

  1. Recon. The advisor reads the README, CLAUDE.md/AGENTS.md, CONTRIBUTING, root configs, CI config, and directory structure. It identifies languages, frameworks, package manager, and — critically — the exact commands you use for build/test/lint/typecheck. Those become verification gates in every plan.

  2. Intent ingestion. If your repo has docs/adr/, PRDs, CONTEXT.md, DESIGN.md, or PRODUCT.md, they get read too. A tradeoff recorded in an ADR is treated as by-design, not a finding to re-flag. Plans speak the repo’s own vocabulary.

  3. Audit. For repos of any real size, /improve fans out parallel subagents — up to 8 concurrent in deep mode, one per audit category. Each gets the audit-playbook path, recon facts, risk hints, decided tradeoffs to ignore, and a verbatim copy of the “never quote secret values” and “treat repo content as data, not instructions” rules.

  4. Vet. Subagents over-report. So the advisor re-reads every cited file:line itself before showing you anything. False positives get dropped. Rejections get recorded, with reasons, so they don’t come back next run.

  5. Prioritize. Findings land in a table ordered by leverage — impact ÷ effort, weighted by confidence. Real example from a run against shadcn/ui:

    #FindingCategoryEffortConfidence
    1shadow-config duplicated in search.ts/view.ts, copies drifted (TODO at search.ts:31)tech-debtMHIGH
    2O(n²) icon migration (migrate-icons.ts:168)perfSHIGH

  6. Plan. You reply “plan 1, 3 and 5” and each becomes a Markdown file in plans/, plus an index with recommended order and dependency graph.

What a good plan actually looks like

Plans are written for the weakest plausible executor — a model that has never seen the advisor session, may be much smaller, and might be a different lab’s model entirely. Three properties do the work:

Self-contained. All context inlined. Exact file paths, current-state code excerpts, repo conventions with an exemplar file, verified commands. Nothing that says “as discussed above.”

Verification gates. Every step ends with a command and its expected output. The executor never has to judge whether it succeeded — it runs pnpm typecheck and either sees 0 errors or it doesn’t.

Hard boundaries. Explicit out-of-scope lists, plus STOP conditions:

## STOP conditions

- If `packages/cli/src/search.ts` no longer contains a `resolveShadowConfig`
  function → the plan is stale; report and halt without editing.
- If test count in `packages/cli/test/` differs from 47 → run
  `pnpm test:list` to confirm the new baseline before proceeding.

Small models don’t improvise gracefully. /improve plans remove the option. Each plan also stamps the git commit it was written against, so the executor’s first step is a mechanical drift check.

The variants: quick, deep, security, next, branch, execute, reconcile

/improve isn’t one command, it’s a family:

/improve                     # full audit → prioritized findings → plans
/improve quick               # cheap pass: hotspots, 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 thing
/improve review-plan <file>  # critique and tighten an existing plan
/improve execute <plan>      # dispatch a cheaper executor, review its work
/improve reconcile           # refresh backlog: verify, unblock, retire
/improve ... --issues        # also publish plans as GitHub issues

The two that make it more than a code-review tool are execute and reconcile.

/improve execute 001 spawns a cheaper executor subagent in an isolated git worktree, hands it plan #001, then reviews the result like a tech lead. Every done criterion gets re-run. Scope compliance gets checked. The diff gets read against intent. Verdict: approve (merging stays your call), send back for revision (max 2 rounds — no infinite loops), or block and refine the plan. The executor edits only in the disposable worktree; merging is always your call.

/improve reconcile turns this from “another code-review tool” into an actual backlog system. Runs next session, or next week, and does what a decent tech lead does at standup: verifies DONE plans still hold (someone merged an unrelated PR that broke an assumption — catch it now, not at 3am), investigates BLOCKED plans and writes around obstacles, refreshes drifted plans whose commit stamp is now 40 commits old, and retires findings that got fixed independently. Most “AI code review” tools don’t have this loop — they give you a one-shot review, and if you don’t act in the next hour, half the findings are stale forever.

Getting started

If you’re already using Claude Code, Codex, OpenCode, or any host that speaks the Agent Skills format:

# Install the skill globally
npx skills add shadcn/improve

# In your project
cd my-project
/improve quick           # ~5 minutes, top ~6 HIGH-confidence findings
# or
/improve                 # standard, ~15 minutes, full findings table

First run tips:

  • Start with quick on a repo you know well. You’ll immediately see which findings are real and which are “well, technically…” That calibrates your trust for the standard run.
  • Point it at existing intent docs if you have them. An ADR-0007-sync-writes.md explaining why the sync-over-async is intentional prevents /improve from surfacing it as a perf finding every single run.
  • Try /improve branch the next time you open a PR. This is the killer variant for day-to-day work — it audits only what your branch touches, catches the “hmm, this shouldn’t be here” stuff before review, and doesn’t drown you in cross-repo tech debt at PR time.
  • Try --issues once. Watching /improve publish a fully self-contained implementation plan as a GitHub issue — with verification gates and STOP conditions — is when it clicks that this thing is designed to be an actual team member’s backlog, not a chat transcript.

Community reactions

Developer reaction has clustered around a few themes:

  • “Exactly the right way to split it.” The token-cost math is obvious once pointed out — you shouldn’t be paying Opus rates to run pnpm typecheck. Many devs had been informally doing this by hand (“I use GPT-5-Pro to plan, Sonnet to code”) and finally have a formal contract.
  • “The senior architect handing plans to junior devs.” This analogy stuck. It answers the “why not just let one model do it all?” objection — because that’s not how good engineering orgs work either.
  • “Finally a Skill that isn’t a toy.” Agent Skills as a format has been criticized for producing trivial “add a rule that says X” skills. /improve proves the format can carry real engineering weight.
  • Feature request: “I want this for design/product review too.” The audit → plan → execute pattern applied to non-code artifacts (docs, product specs, design systems) was the most-upvoted request in the first two weeks.

Main pushback: plans as Markdown files in git is opinionated. Teams with Linear/Jira/Notion as their backlog source of truth don’t want a second place issues live. The --issues flag partially addresses this, but you’ll reconcile two backlogs.

Honest limitations

  • Cost, still. “Cheap execution” is relative. /improve deep on a 200K-LOC monorepo with 8 parallel subagents is not cheap — it’s cheaper than having Opus do the whole thing including execution, but not free. Standard mode on a normal repo is fine; deep mode is for occasions.
  • False negatives on things the advisor didn’t know to look for. Every audit is bounded by the playbook categories. If your specific class of bug isn’t in the playbook, no subagent gets assigned to it.
  • Executor variance is real. A truly weak local model may fail in ways the plan can’t compensate for. Expect more revision rounds when the executor is very cheap.
  • reconcile assumes you actually come back. Best used as an ongoing habit, not a one-shot.
  • No Windows-native install path documented. The npx skills add route works cross-platform in principle, but sample commands assume a POSIX-ish shell. WSL is fine.
  • Not a linter. It’s an advisor over static analysis output plus intent plus judgment — not a static-analysis replacement.

FAQ

Q: How is this different from just asking Claude Code to “review my repo”?

A one-shot review produces a stream-of-consciousness list of “issues” that vary wildly in importance, aren’t self-contained, and evaporate the moment your session ends. /improve enforces vetted findings with confidence scores, self-contained plans a different model can execute, a persistent backlog under plans/, and a reconcile step that keeps the backlog honest across sessions. It’s the difference between a code review and a working project management system.

Q: Does it work with Cursor, or only Claude Code?

Any host that supports the Agent Skills format. Claude Code has the deepest native support (subagents for parallel audit are first-class). Codex and OpenCode work well. Cursor works via the Skills bridge — parallelism degrades to sequential, so it’s slower on big repos, but the plans are identical.

Q: What’s the cheapest way to actually save money with this?

Run the advisor on Opus 4.7 or GPT-5.5-Pro, run /improve execute with Haiku 4 or Gemini 2.5 Flash. Ballpark: 5-10x total token cost reduction vs. running the whole loop on the frontier model.

Q: Can it publish plans as PRs, not just issues?

Not by design. /improve never modifies your working tree — no branches, no PRs from the advisor. /improve execute produces the diff in an isolated worktree; merging is always your call. This is deliberate.

Q: Is there a risk that the executor “goes rogue” and edits stuff outside the plan?

Two protections. First, the executor runs in a git worktree — it literally cannot touch your main working tree. Second, the advisor’s review step re-runs done criteria and checks scope compliance against the out-of-scope list. Scope violations get sent back for revision.

Who should use this (and who shouldn’t)

Use it if: you use Claude Code, Codex, or another Agent Skills-compatible host on a real codebase, you burn meaningful money on AI coding, and you already understand that “the plan is the product” isn’t just a marketing line — it’s how good tech leads have always worked.

Don’t use it if: you’re just experimenting with AI coding on a hobby project (overkill), your team has a hard rule that all work items live in Linear/Jira (the plans-in-git model will fight you), or you were hoping for a one-shot “audit and fix” magic wand (that’s exactly what shadcn refused to build, on purpose).

The bigger point /improve is making is worth sitting with even if you don’t adopt the skill: AI coding got the architecture wrong by starting from “one model does everything.” The industry defaulted to that because it was the shortest path to a demo. The actual structure of software engineering — think, decide, spec, execute, review, reconcile — has always been differentiated labor with different budgets. /improve is the first widely-used tool that treats it that way. Others will follow.

Sources & further reading