shadcn/improve: the audit skill that hands back plan files instead of code
Use your most capable model to audit your codebase and write plans for cheaper models to execute.
At a glance
- What is it?
- A slash-command agent skill from shadcn that maps a repository, audits it across nine categories, and writes self-contained markdown plans for a cheaper model to execute. It never edits your source, and the merge stays yours.
- Who is it for?
- The judgment: this fits a repo where someone is willing to read markdown before spending model time on execution, and it does not fit a workflow that needs changes to land unattended. Before adopting, check three things.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 64 days ago.
- What is it written in?
- GitHub does not report a main language for this repository.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- shadcn/improve11,944 ★ · +2,805
| Repository | 2026-09-17 | 2026-11-15 |
|---|---|---|
| shadcn/improve | 9.1k | 11.9k |
2,805 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Installing is one npx command, and the whole surface is slash commands
Installation is a single npx call, and what it fetches is a skill rather than a binary:
npx skills add shadcn/improveIt loads into any agent that supports the Agent Skills format. The repository itself is small: .claude-plugin/, skills/, examples/, LICENSE.md and README.md, so there is no config file, no port and no environment variable to set. The output side is plain markdown, which is the point of the design: a plan can be picked up later by another agent or by a person without any conversion step.
Once the skill is loaded, everything is a slash command:
/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 planNote the division of labour the diagram at the top of the README draws: you invoke /improve on an expensive model, the skill writes files like 001-fix-n-plus-one.md into plans/, and a different, cheaper agent implements, tests and ships. The skill sits in the middle and never takes the third role.
The hard rules all point one way: this skill reads, it does not write source
Every entry in the hard rules section restricts what the skill may do, and the consequences for a reader are concrete.
It never modifies source code. The only writes go to plans/, executors spawned later edit only in disposable git worktrees, and merging is always your decision. An approved plan can therefore sit unmerged on your machine indefinitely without anything complaining.
It never runs commands that mutate your working tree, which limits it to read, search and read-only analysis. A finding that says a dependency migration is overdue will not migrate that dependency or regenerate a lockfile, even when the evidence is a file and a line number.
It never reproduces secret values. Reports carry locations and credential types only, and rotation is always recommended. So a finding that points at a hardcoded credential hands you a path and a line, and nothing else: you cannot copy the value out of a plan to check it, and no step in this flow expires the credential for you.
Asked to implement something directly, it declines and points at the plan, or offers execute instead.
Recon reads ADRs and PRDs so settled tradeoffs stop coming back as debt
Recon is where the verification gates come from. It maps the repository's stack, its conventions and the exact build, test and lint commands, and those commands become gates that every later plan has to satisfy.
It also ingests intent and design documents when they are present: ADRs under docs/adr/, PRDs, CONTEXT.md, DESIGN.md and PRODUCT.md. Three things are supposed to follow from that. Decided tradeoffs stop being re-flagged as findings. Direction suggestions stay anchored to stated product intent rather than drifting into taste. Plans end up speaking the repo's own vocabulary instead of generic advice.
What happens without those files is the part worth checking before you adopt this. A repo with no ADRs and no product docs hands the audit no record of what you already settled on the hard way, so an intentional tradeoff can return as a tech-debt row with HIGH confidence and an M effort estimate, indistinguishable from an oversight. Direction findings must cite evidence from the repo itself, and a repo without those documents has thin ground to stand on for that whole category.
Nine categories fan out in parallel, then a vet pass reopens every citation
The audit fans out parallel subagents across nine categories: correctness, security, performance, test coverage, tech debt, dependencies and migrations, DX, docs, and direction. Every finding carries file:line evidence, an impact, an effort and a confidence value, which is what makes the ordering in the next step possible.
Parallel subagents over-report, and the skill's answer is a separate vet stage. The advisor re-reads every cited location itself before anything is shown to you. False positives get dropped, wrong attributions get corrected, and rejections get written down so they do not reappear on the next run:
- [SEC-01] https_proxy env var "SSRF": by-design — standard proxy convention,
every CLI honors it. Not a finding.Two things follow for a reader. The cost is not just the fan-out: every surviving finding has been checked twice, once by a subagent and once by the advisor, and the advisor read is the expensive half. And the containment is by ledger rather than by prevention. The rejection record means a dismissed finding stops costing you attention, but it also means the record has to be read before you can tell a suppressed false positive from a finding you simply never saw.
Findings get impact and effort ratings, and the table waits for your reply
Findings land in a table ordered by leverage, which the README defines as impact divided by effort, weighted by confidence. That ordering is advice, not automation.
The run comes back with the table and stops, because the skill cannot know which problems you want solved this week or which ones are blocked on something outside the codebase. You reply with numbers, for example plan 1, 3 and 5, and only then does anything get written to disk.
What you get per selection is one file in plans/ plus an index carrying the recommended order and a dependency graph, so a cheap executor knows what has to land before what.
The consequence for a team is worth stating plainly: an audit that ends at the table has produced no code and no plan file. If nobody replies, the entire run cost is a document of opinions.
Every step ends with a command and its expected output, and that depends on your repo
Plans are written for the weakest plausible executor: a model that has never seen the advisor session and may be much smaller. Three properties carry that, and each one removes a judgement call from the executor.
Self-contained means exact file paths, current-state code excerpts, repo conventions with an exemplar file, and verified commands. No as discussed above is allowed anywhere, because the reader of the plan has no earlier context.
Verification gates mean every step ends with a command and its expected output, so the done criteria are machine-checkable and the executor never has to decide whether it succeeded.
Hard boundaries mean explicit out-of-scope lists and STOP conditions written as if X, stop and report, instead of leaving a small model to improvise when reality does not match the plan. The bundled example plan, examples/001-extract-shadow-config-resolution.md, is described as current code excerpted, exact steps, the repo's own test and lint commands as verification gates, and STOP conditions.
Read in reverse, those properties depend entirely on what recon found. The gates are your repository's commands, not a fixed suite the skill carries, so a repo with no real build, test or lint commands has nothing machine-checkable to point at and the executor falls back to judging success for itself. The README does not document a fallback command set for that case.
Depth flags decide how much of the repo the audit reads, and what a cheap pass skips
The depth flags decide coverage. Bare /improve runs a full audit. quick is described as a cheap pass over hotspots with top findings only. deep is exhaustive, every package and every category. security narrows the audit to one category, with perf, tests, bugs and others named as alternatives. branch limits the audit to what the current branch changes. next returns feature suggestions about where to take the project, and plan <description> skips the audit outright and specs one thing.
The finding format stays the same at every depth, so a table row is self-describing:
| # | Finding | Category | Effort | Confidence |
|---|------------------------------------------------|-----------|--------|------------|
| 1 | shadow-config duplicated in search.ts/view.ts, | tech-debt | M | HIGH |
| | copies already drifted (TODO at search.ts:31) | | | |
| 2 | O(n²) icon migration (migrate-icons.ts:168) | perf | S | HIGH |The cost of a cheap pass is coverage, and it is silent. quick returns hotspots and top findings only, so a quiet quick run is not evidence that the categories it skipped are clean. branch has a blind spot of its own: debt sitting in files your branch never touches is out of view by construction, which makes it a useful pre-PR pass and a bad periodic sweep.
Two revision rounds, then the plan is blocked, and reconcile is the cleanup pass
Once a plan exists, three commands carry it forward.
execute <plan> spawns a cheaper executor subagent in an isolated git worktree, hands it the plan, then reviews the result like a tech lead: it re-runs every done criterion, checks scope compliance and reads the diff against intent. The verdict is approve with merging still your call, send back for revision with a maximum of 2 rounds, or block and refine the plan. Two rounds is the ceiling, so a plan that keeps failing ends blocked and needs a person to refine it rather than another retry.
Each plan also stamps the git commit it was written against, so executors run a mechanical drift check before touching anything. That stamp is the input to reconcile, which verifies that DONE plans still hold, investigates BLOCKED ones and rewrites around the obstacle, refreshes plans that drifted, and retires findings that got fixed independently.
--issues publishes plans as GitHub issues with the same self-contained body, so work can live where your team already works.
Two practical limits: until reconcile runs, a plan written before someone else's merge is a stale document with a machine-checkable age, and the repository publishes no GitHub releases, so there is no version tag to pin the skill to when you want to freeze its behaviour.
Editorial conclusion
The judgment: this fits a repo where someone is willing to read markdown before spending model time on execution, and it does not fit a workflow that needs changes to land unattended. Before adopting, check three things. Does your host support the Agent Skills format at all, since the install step only loads a skill. Do docs/adr entries, a PRD or CONTEXT.md exist, because without them the audit has no record of what you already decided. And how many plans will sit unmerged, because approve is a verdict, not a commit. Read at least one plan file against your own conventions before handing one to a cheaper model.
Frequently asked questions
What does running /improve on a repository actually produce?
It maps the repo, audits it, and comes back with a findings table. Only after you reply with the numbers you want planned does it write one self-contained plan file per selection into plans/, plus an index with the recommended order and a dependency graph.
Does shadcn/improve change any source code itself?
No. It never modifies source code, and the only writes go to plans/. Executors edit only in disposable worktrees, merging is always your call, and it never runs commands that mutate your working tree.
Is /improve deep different from a quick audit?
Yes. /improve deep is exhaustive across every package and every one of the nine categories, while /improve quick is a cheap pass over hotspots with top findings only, so a clean quick run says nothing about the categories it skipped.
What happens when a plan fails review twice in shadcn/improve?
Revision is capped at 2 rounds. After that the verdict is block and refine the plan, so the next move belongs to a person editing the markdown rather than another automated retry. Merging stays yours either way.
How do plans from shadcn/improve avoid being stale?
Each plan stamps the git commit it was written against, so executors run a mechanical drift check first. Running /improve reconcile later verifies DONE plans still hold, rewrites around BLOCKED obstacles, refreshes drifted plans and retires findings that were fixed independently.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/shadcn-improve)Star history chart for your README
[](https://hysenlabs.com/projects/shadcn-improve)Was this useful?