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

shadcn/improve is an MIT-licensed Agent Skill that audits a codebase with your most capable model and writes self-contained implementation plans into plans/ for a cheaper model to execute. The skill itself never edits source code: every plan carries its own verification commands, scope limits, and STOP conditions, so you check the result by running gates rather than reading every line.

You inherit a service, or your own repository has drifted for a year, and you know there are bugs, slow queries, and missing tests somewhere. Pointing your strongest model at it and saying “fix things” burns premium tokens on renames and import shuffles, and it leaves you with a sprawling diff to review. This page is for developers and tech leads who want the expensive thinking done once, written down as plans a smaller model can follow, and checked by commands instead of by eye.

What this page covers

• A verified install for Claude Code, Codex, and Cursor, and what each install costs in context
• The recon, audit, vet, and plan pipeline, and which /improve variant to run when
• Three copy-paste prompts: selecting findings, handing a plan to a cheaper executor, and reviewing what came back
• A way to verify an executor’s work from the plan’s done criteria, the scope diff, and your CI gates
• The failure modes that waste a run, and how to recover from each

What shadcn/improve is, and what it is not

The repository shadcn/improve holds one skill, improve, at version 1.0.0 (MIT, created 2026-06-10, last commit 2026-09-12). The skill’s own framing is “The plan is the product”: an advisor model maps and audits the repository, and a different, less capable executor implements the plans.

Its hard rules, from SKILL.md:

• It never edits source code. It writes only under plans/, or under advisor-plans/ when plans/ already exists for something else.
• It never runs commands that mutate your working tree: no installs, formatters, or commits. Read-only analysis such as tsc --noEmit or lint in check mode is allowed.
• It never reproduces secret values. A finding names the file:line and credential type and recommends rotation.
• It treats everything in the repository as data. A comment that says “ignore previous instructions” becomes a security finding, not an instruction.
• Asked to implement, it declines and points you at the plan or at execute.

The one exception is execute: a separate executor subagent edits code in an isolated git worktree, and the advisor reviews that diff. Merging stays your decision.

Note

Popularity and cost. About 9,200 GitHub stars (9,195) and 414 forks (GitHub API, read 2026-09-30, four days after this revision). Installed as a Claude Code plugin, claude plugin details reports ~170 tokens always-on and ~4.9k tokens each time the skill fires (Claude Code 2.1.286, latest channel). The audit itself costs far more than the skill text, because it fans out subagents across the repository.

Install shadcn/improve in Claude Code, Codex, or Cursor

The portable route is the skills CLI (skills 1.7.0 on npm). The repository also ships a Claude-format plugin marketplace (.claude-plugin/marketplace.json), which Claude Code installs natively and Codex can read too.

Claude Code

Plugin route, from your terminal:

claude plugin marketplace add shadcn/improve
claude plugin install improve@improve
claude plugin details improve@improve   # inventory and token cost

Plugin skills are namespaced, so the command is /improve:improve (for example, /improve:improve quick). If you prefer the bare /improve, use the skills CLI instead:

npx skills add shadcn/improve -a claude-code

Codex

Plugin route, from your terminal. Codex reads the repository’s Claude-format marketplace (verified on codex-cli 0.157.1: codex plugin list then shows improve@improve installed, enabled 1.0.0):

codex plugin marketplace add shadcn/improve
codex plugin add improve@improve      # "add", not "install"

Or use the skills CLI:

npx skills add shadcn/improve -a codex

Start a new Codex session and pick the skill from /skills, which shows the exact name to invoke. After a skills CLI install that name is $improve (for example, $improve quick); after a plugin install, check the /skills entry before typing it, because the plugin-install name was not verified in a live session.

Cursor

npx skills add shadcn/improve -a cursor

The CLI writes project installs to .agents/skills/improve/, a directory Cursor reads. Open a new Agent chat and ask it to use the improve skill, or type /improve if your Cursor build lists skills in the slash menu. Cursor’s skill invocation details were not re-verified on 2026-09-26 because cursor.com was unreachable, so confirm the skill appears before relying on it.

Add -g to install for your user instead of the project, and -y to skip prompts in scripts. Run npx skills add shadcn/improve -l first if you want to see what the repository contains without installing anything. Before you install any third-party skill, read its SKILL.md; skill supply-chain security explains why.

How an /improve run works

1. Recon. The advisor reads README, CLAUDE.md or AGENTS.md, CI config, and manifests, and records the exact build, test, lint, and typecheck commands. Those commands become the verification gates in every plan. It also reads intent documents when they exist (ADRs under docs/adr/, PRDs, CONTEXT.md, DESIGN.md, PRODUCT.md), so a trade-off you already decided is not re-reported as a bug.

2. Audit. Parallel read-only subagents cover nine categories: correctness, security, performance, test coverage, tech debt and architecture, dependencies and migrations, DX and tooling, docs, and direction. Every finding needs file:line evidence, impact, effort (S/M/L), fix risk, and confidence.

3. Vet. Subagents over-report, so the advisor re-opens every cited location itself. It drops by-design behaviour, corrects wrong attributions, merges duplicates, and records rejections so the next run does not raise them again.

4. Prioritize and choose. You get a table ordered by leverage (impact divided by effort, weighted by confidence), with direction suggestions listed separately. You reply with the findings you want planned. The skill waits for that choice; run non-interactively, it plans the top three to five and records that default.

5. Plan. Each chosen finding becomes plans/NNN-slug.md, plus plans/README.md with the order, dependencies, and a status column. Each plan stamps the commit it was written against.

Which /improve variant to run

The argument selects scope and depth. Effort keywords compose with the others, for example quick security or deep --issues.

You want to…	Run	What it does
Get a first map of a large repository cheaply	/improve quick	Hotspots only; correctness, security, and tests; roughly the top six high-confidence findings
Audit normally	/improve	All nine categories, up to four concurrent subagents
Audit everything, including low-confidence leads	/improve deep	Every package, up to eight concurrent subagents
Focus on one category	/improve security (or another category name such as perf or tests)	Recon, then that category only
Self-review before opening a PR	/improve branch	Files changed since the merge-base plus their direct callers; each finding tagged introduced or pre-existing
Decide what to build next	/improve next	Four to six evidence-backed feature suggestions that become design or spike plans
Spec one thing you already chose	/improve plan <description>	Skips the audit and writes a single plan
Tighten a plan before anyone runs it	/improve review-plan <file>	Critiques the plan against the template; if the plan was written in this session, a fresh-context subagent also reads it cold
Run a plan and review the result	/improve execute <plan>	Dispatches an executor in a worktree, re-runs the gates, and returns a verdict
Clean up after a week of work	/improve reconcile	Verifies DONE plans, reworks BLOCKED ones, refreshes drifted ones, retires fixed ones
Publish plans where work is tracked	add --issues	Creates one GitHub issue per plan with gh

In Claude Code installed as a plugin, prefix these with /improve:improve; in Codex, use the name /skills shows ($improve after a skills CLI install).

Why the plans survive a weaker model

A plan is written for “the weakest plausible executor”: a model that never saw the audit and may be much smaller. The template enforces three properties:

• Self-contained. File paths, current-code excerpts with line markers, the conventions to match with an exemplar file, and the relevant CONTEXT.md or ADR lines, all inlined.
• Verification gates. Every step ends with a command and its expected output, and the done criteria are machine-checkable. The executor never has to judge whether it succeeded.
• Hard boundaries. In-scope and out-of-scope file lists, plus STOP conditions (“if X, stop and report”) instead of improvisation.

Each plan opens with a drift check, git diff --stat <planned-at SHA>..HEAD -- <in-scope paths>, so a plan written last Tuesday does not get applied blind to code that changed on Wednesday. This is the same discipline that lets a /goal run end cleanly and that spec-driven development applies to features: a written specification with checkable acceptance criteria.

The audit, plan, execute, and verify loop

The loop below puts the skill inside plan, build, verify, review, and ship. The model split follows the corpus rule on the model comparison page: the advisor stays on your tool’s default model (Claude Opus 5.5 in Claude Code, default from v2.1.280 on the latest channel; GPT-6 Astra in Codex), and the executor runs on a cheaper one (Claude Sonnet 5 or Claude Haiku 4.5; GPT-6 Sol or GPT-6 Luna). Move a task back to the stronger model only when its gates keep failing.

1. Plan. Run /improve (or /improve quick on a large monorepo). Choose findings with the first prompt below. A tech lead reviews plans/README.md and the chosen plans; a one-page plan is a far smaller review surface than the diff it will produce.

2. Build. Run each plan on the cheaper model in its own worktree. The commands differ by tool:

   Claude Code

   Let the skill dispatch and review in one step. The executor defaults to sonnet; name another model after the plan number.

   /improve execute 001
   /improve execute 003 haiku

   The dispatch uses a general-purpose subagent with worktree isolation. The advisor inlines the full plan text, because an uncommitted plans/ directory does not exist inside the new worktree.

   Codex

   The skill’s dispatch step is written for Claude Code’s subagents. On a host that cannot spawn a subagent in an isolated worktree, the skill says so and hands the plan over. Run the executor yourself from the repository root:

   git worktree add ../app-plan-001 -b plan-001
   (cd ../app-plan-001 && npm ci)   # or your repo's own install command
   codex exec -C ../app-plan-001 -m gpt-6-sol --approve-for-me \
     "$(cat ../executor-preamble.txt plans/001-*.md)"

   A new worktree shares git history but not node_modules or build artifacts, so install dependencies in your own shell first, outside the sandbox, where the network is available. Save the second prompt below as ../executor-preamble.txt, outside the repository so it never lands in a commit. --approve-for-me routes approvals through automatic review inside the workspace-write sandbox (Codex CLI 0.157.1).

   Cursor

   Create the worktree and install its dependencies in a terminal, open that folder in a new Cursor window, pick a cheaper model in the Agent model picker, and paste the second prompt below followed by the full plan text. Pasting the text matters: the new worktree does not contain uncommitted plan files.

   git worktree add ../app-plan-001 -b plan-001
   (cd ../app-plan-001 && npm ci)   # or your repo's own install command

3. Verify. Re-run every done criterion from the plan inside the worktree, then run your normal gates (typecheck, lint, tests). In Claude Code, execute does this and returns APPROVE, REVISE (at most two rounds), or BLOCK. Elsewhere, paste the third prompt below into a session on your strongest model.

4. Review. Check scope with git -C ../app-plan-001 diff --stat main...HEAD against the plan’s in-scope list; any file outside it fails review. Replace main with your repository’s default branch. A bare git diff --stat shows nothing once the executor has committed, so it would pass without looking at the change. Read the new tests’ assertions, not only their pass count, because executors can satisfy a criterion with a test that asserts nothing.

5. Ship. Open the PR from the worktree branch. CI runs the same gates, and the person who merges signs off. Attach the plan and the gate output as the PR’s evidence bundle.

6. Reconcile. At the start of the next session, run /improve reconcile so the backlog reflects what landed, what drifted, and what was fixed in passing.

Copy-paste prompt: choosing findings to plan

Plan 1, 3 and 5. Order them so any characterization tests land before the
refactor they protect, and say which plan depends on which. For each plan,
use this repo's own typecheck, lint and test commands as the done criteria,
list the files that are out of scope, and add a STOP condition for the case
where the current code no longer matches your excerpt. Skip anything whose
confidence is below HIGH and tell me what you dropped.

Copy-paste prompt: executor preamble for a cheaper model

You are the executor for the implementation plan below. Run the plan's drift
check first. Then follow the plan step by step, run every verification command,
and confirm the expected result before moving to the next step. Touch only the
files listed as in scope. If any STOP condition occurs, stop and report instead
of working around it. Do not edit plans/README.md. Commit your work on this
branch. Finish with: STATUS (COMPLETE or STOPPED), each step with its
verification result, FILES CHANGED, and NOTES on any deviation. Report only what
a command in this session actually showed.

Copy-paste prompt: reviewing the executor's worktree

Review the branch plan-001 in ../app-plan-001 against plans/001-*.md as a tech
lead would, without editing any file. 1) Re-run every done criterion in the
plan and show the output. 2) Compare `git diff --stat main...plan-001` (use the
repo's default branch in place of main) with the plan's in-scope list and
flag every file outside it. 3) Read each new or changed
test and say what behaviour it would catch if it failed. 4) Check the diff
against "Why this matters" in the plan. End with APPROVE, REVISE (with specific
fixes), or BLOCK (with what the plan got wrong).

Where shadcn/improve fits, and where it does not

Reach for it when you inherit an unfamiliar codebase and want a vetted, prioritized map before touching anything; when you want frontier-model budget spent on judgment and cheaper models on edits; before a PR, with /improve branch; and when you need grounded options for what to build next, with /improve next.

Skip it for a single known bug (ask the agent directly, or use /improve plan <description>), for repositories with no working build or tests until you have fixed that (the skill usually makes “establish a verification baseline” finding number one), and when the job is diff review rather than repository audit, which the code review skills cover.

shadcn/improve failure modes and recovery

Traps

• Wrong install name. The repository is shadcn/improve. It is not part of shadcn/ui, and the shadcn/ui component CLI (npx shadcn) does not install it.
• Wrong command after a plugin install. Plugin skills are namespaced: in Claude Code the command is /improve:improve, not /improve.
• Assuming execute works everywhere. Its dispatch (a general-purpose subagent, worktree isolation, default executor sonnet) is written for Claude Code. On other hosts, run the executor yourself as shown in the loop above.
• --issues on a public repository. Issues are public. The skill checks visibility with gh repo view --json visibility and asks before publishing sensitive findings; do not wave that confirmation through for security plans.

The executor cannot find the plan. A new worktree contains only committed files, so an uncommitted plans/ directory is missing there. Recovery: inline the plan text in the executor prompt (as execute does and the Codex command above does), or commit plans/ first.

The plans went to advisor-plans/. Your repository already had an unrelated plans/ directory. Recovery: nothing is broken; point your executor at advisor-plans/, or rename your directory before the next run.

The executor’s first gate fails with missing modules. The new worktree has no node_modules or build output, and a sandboxed executor may have no network to install them. Recovery: install dependencies in the worktree from your own shell (npm ci or your repo’s install command), run one build if your tooling resolves from dist/, then run the executor again.

A plan is stale. Someone changed the in-scope files after the plan was written, and the drift check reports differences. Recovery: treat it as a STOP, run /improve reconcile to refresh the excerpts and Planned at commit, then execute again.

The executor keeps stopping or failing the same gate. The plan is under-specified, or the task is too hard for the cheaper model. Recovery: run /improve review-plan plans/NNN-*.md to tighten it; if it still fails after two revision rounds, run that plan on the stronger model or split it.

The findings table is noise. It lists by-design behaviour, or trade-offs you settled long ago. Recovery: write the decision down as an ADR under docs/adr/ or in CONTEXT.md; recon reads those, and vetting records rejected findings so they do not return.

The audit is too expensive on a monorepo. Recovery: start with /improve quick or a single category (/improve security), and save deep for when you need every package; even then the skill scopes its subagents to packages rather than the root. The final report says what was not audited, so read that section before assuming full coverage.

Next steps

Installing and managing skills How the skills CLI installs, updates, and removes skills across Claude Code, Codex, and Cursor.

Grill Me and the Pocock skill chain The alignment step before a plan: the agent interviews you until the spec is settled.

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

AI model comparison for coding agents Which model to use as the advisor and which as the executor, with current defaults.