# shadcn/improve: an agent skill that audits your codebase and writes plans for cheaper models

> shadcn/improve uses an expensive model to map a repository, audit it across nine categories and write self-contained implementation plans, then hands execution to a cheaper model. The plan is the product, and the skill never edits source.

**shadcn/improve** — Use your most capable model to audit your codebase and write plans for cheaper models to execute.

- Repository: https://github.com/shadcn/improve
- Stars: 9,184 · Forks: 412
- Language: Unknown
- License: MIT
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/shadcn-improve

## What shadcn/improve solves, and who it is for

Most agent workflows spend the expensive model on the wrong half of the job. Reading a repository, deciding what is worth changing and writing a spec is where intelligence compounds. Typing the change is not. shadcn/improve splits those halves: a capable model audits and writes plans, and a cheaper model executes them. The README states the skill never implements anything itself, and that the plan is the product.

The audience is narrow and specific. You need a repository big enough that a single context window will not hold it, an agent that supports the Agent Skills format, and a willingness to review markdown before code moves. The plans are plain markdown files, so a human can pick them up as easily as another agent. If your codebase is one file, the audit step costs more than the work it finds.

## How the audit pipeline works: recon, fan-out, vet, prioritize, plan

The README describes five stages. Recon maps the repository: stack, conventions, and the exact build, test and lint commands, which later become verification gates inside every plan. It also ingests intent documents when they exist, naming ADRs under docs/adr/ plus PRDs and files such as CONTEXT.md, DESIGN.md and PRODUCT.md, so tradeoffs the team already decided are not re-flagged as findings.

Audit fans out parallel subagents across nine categories: correctness, security, performance, test coverage, tech debt, dependencies and migrations, DX, docs, and direction. Every finding must carry file:line evidence, impact, effort and confidence. Direction findings have an extra constraint: each one has to cite evidence from the repository itself.

Vet is the stage that matters most. The README is explicit that subagents over-report, so the advisor re-reads every cited location before showing anything, drops false positives, corrects wrong attributions and records rejections. Prioritize sorts the survivors by leverage, defined as impact divided by effort, weighted by confidence. You then choose which findings become plans, and Plan writes one file per selection into plans/ with an index, priority order and dependency graph.

The example run in the README shows both sides of this. Against shadcn/ui it surfaced a duplicated shadow-config between search.ts and view.ts where the copies had already drifted, and an O(n^2) icon migration at migrate-icons.ts:168. It also rejected a security finding about the https_proxy environment variable, recording the reason as by-design and noting that every CLI honors the convention. Recording rejections is what stops the same non-finding from resurfacing on the next run.

## Installing shadcn/improve and running a first audit

The README gives one install command. It works in any agent that supports the Agent Skills format, so there is no per-editor configuration to write.

```bash
npx skills add shadcn/improve
```

After that, open your agent inside the repository you want audited and invoke the skill. The README suggests starting cheap:

```
/improve quick
```

A quick pass returns hotspots and top findings only. The full command is `/improve`, which runs the complete audit and produces a prioritized findings table. You then reply with the numbers you want planned, for example "plan 1, 3 and 5", and the skill writes one markdown file per selection into plans/, plus an index with the recommended order.

To hand a plan to a cheaper executor and have the result reviewed, the README shows this form:

```
/improve execute 001
```

That dispatches a cheaper model in an isolated git worktree, reviews the diff against the plan and returns a verdict. Merging stays with you. The README also lists narrower modes: `/improve security` and the other category names, `/improve branch` to scope the audit to what the current branch changes, `/improve next` for feature suggestions, `/improve plan <description>` to skip the audit and spec one thing, `/improve review-plan <file>` to critique an existing plan, and `/improve reconcile` to refresh the backlog. Adding `--issues` publishes plans as GitHub issues with the same self-contained body.

## What makes a plan executable by a weak model

The README says plans are written for the weakest plausible executor, a model that never saw the advisor session and may be much smaller. Three properties carry that weight.

Self-contained means all context is inlined: exact file paths, current-state code excerpts, repository conventions with an exemplar file, and verified commands. There is no "as discussed above" for the executor to resolve. Verification gates mean every step ends with a command and its expected output, so done criteria are machine-checkable and the executor never has to judge its own success. Hard boundaries mean explicit out-of-scope lists and STOP conditions of the form "if X, stop and report", rather than leaving a small model to improvise when the repository does not match the plan.

Each plan also stamps the git commit it was written against, so an executor can run a mechanical drift check before touching anything. That detail is what makes the reconcile step meaningful: if the commit moved, the plan may no longer describe reality. The repository layout reflects this design, with the skill code under skills/ and a worked example at examples/001-extract-shadow-config-resolution.md.

## Where shadcn/improve is the wrong tool

The hard rules are also the limitations. The skill never modifies source code itself. The only writes go to plans/. Executors edit only in disposable worktrees, and merging is always yours. It never runs commands that mutate the working tree, so every operation is read, search or read-only analysis. Asked to implement something directly, it declines and points at the plan or offers the execute path.

That is a deliberate boundary, but it means shadcn/improve does not shorten the loop for a small change. If you want an agent that fixes a failing test while you watch, this is not it. The vetting stage also implies a real cost: the advisor re-reads every cited location, so a deep run over a large monorepo is not cheap in tokens even though execution later is.

There is a second failure mode worth naming. The README does not document rollback for a plan that turns out to be wrong after execution, and it does not describe how the drift check behaves when the stamped commit is no longer reachable, for example after a force push or a rebase. Treat the commit stamp as a warning signal rather than a guarantee. The README is also silent on how many plans a single run can produce before the index stops being readable, and on whether plans/ is expected to be committed or ignored.

## How it differs from a general-purpose coding agent

A general coding agent such as Claude Code or Codex, used directly on a repository, will both find problems and edit files in the same session. The difference in approach here is the separation of advisory and execution roles, and the artifact that separation produces. In shadcn/improve, the expensive model's output is a markdown file with inlined context, verification gates and STOP conditions, addressed to an executor that may be a different model entirely. Nothing is edited until you hand the plan on.

That has a practical consequence for review. With a general agent you review a diff after the fact. Here you review a plan before any diff exists, and the README's example plan is written so the repository's own test and lint commands serve as the gates. The tradeoff is latency and ceremony: a plan has to be written, read and dispatched before the first line changes. If your work is exploratory and you cannot describe the target state in advance, the plan format fights you.

## Maintenance, licence and what you are taking on

The repository is not archived, and the last push was on 2026-09-12, five days before this writing, so the project is being changed. There are no retrieved releases, which means distribution is through the npx skills add path rather than versioned artifacts. Pin nothing you cannot re-resolve: the install command fetches from the repository, so the skill you run next month may not be the one you ran today.

The licence is MIT, copyright shadcn. MIT permits use, modification and redistribution with the licence and copyright notice retained; it offers no patent grant and no warranty. That is a permissive default and it places no obligation on your own code. It also means the maintainers owe you no support commitment, and the README does not describe a deprecation policy or a changelog. If you need a stable interface, the plans/ directory format is the thing to watch, since it is the contract between the advisor and any executor you point at it.

## Conclusion

Adopt shadcn/improve if you already run an agent that supports the Agent Skills format and you want audit output you can review as markdown before anything touches your tree; the hard rule that it never edits source is the reason to trust it on a real repository. Skip it if you want autonomous refactoring, since it declines to implement and only points at a plan or offers execute. Before running it, verify that your agent loads the skills directory, that plans/ is writable and gitignored or committed deliberately, and that the build and test commands the recon step records are the ones you actually use, because those become verification gates.

## FAQ

### How do I install shadcn/improve?

Run npx skills add shadcn/improve. The README states it works in any agent that supports the Agent Skills format, and the plans it writes are plain markdown, so any agent or human can pick them up.

### Does shadcn/improve edit my source code?

No. The README lists as a hard rule that the skill never modifies source code itself, and that the only writes go to plans/. Executors edit only in disposable worktrees, and merging is always yours.

### What is the difference between /improve and /improve quick?

The README describes /improve as a full audit that produces prioritized findings and plans, while /improve quick is a cheap pass that returns hotspots and top findings only.

### Which audit categories does shadcn/improve cover?

The README says the audit fans out parallel subagents across nine categories: correctness, security, performance, test coverage, tech debt, dependencies and migrations, DX, docs, and direction. A single category can be targeted directly, for example /improve security.

## Sources

- [Issues](https://github.com/shadcn/improve/issues)
- [License: MIT](https://github.com/shadcn/improve/blob/main/LICENSE)
- [README](https://github.com/shadcn/improve/blob/main/README.md)
- [shadcn/improve on GitHub](https://github.com/shadcn/improve)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/shadcn-improve