What is the improve skill?
The improve skill is a SKILL.md in shadcn's improve repository. It surveys any codebase as a senior advisor, ranks findings by value, and writes plan files into a plans folder for other agents to execute. It never edits source code itself. The plan is the product.
The improve skill lives in the skills/improve folder of shadcn's improve repository. Its idea is a split of labor: a high-ceiling model understands the codebase and writes the spec, and cheaper models do the execution.
It works on any codebase, not only shadcn/ui projects. Its hard rules forbid editing source, so the only files it writes are plans, in a plans folder at the repo root.
What changes in your agent's output
- Your agent maps the repo first: stack, conventions and the exact build, test, lint and typecheck commands, which become verification gates in every plan.
- It audits nine categories, from bugs and security to dependencies, docs and product direction, and every finding carries file and line evidence, impact, effort and confidence.
- It re-reads each cited location before presenting findings, because sub-agents over-report, and records rejected findings so they are not re-audited.
- You pick which findings become plans. Each plan is a numbered markdown file with code excerpts, ordered steps, boundaries and done criteria.
- A plans index lists the recommended order, dependencies between plans and a status column.
Who the improve skill is for
Best for
- Developers who want a prioritized backlog of fixes for a front end or full-stack repo, written for another agent to pick up.
- Teams that run an expensive model for judgment and a cheaper one for implementation.
- Pre-PR checks on a branch, using the branch variant, and roadmap input through the next variant.
Not for
- Quick edits. The skill declines to implement directly and points you at a plan instead.
- A design critique of the interface itself. For a UI-specific audit that proves each finding, use improve-ui.
- Choosing components or visual style. For shadcn/ui rules, see the shadcn skill.
Invocation variants
Bare /improve runs the full audit. Keywords change the scope and effort, and the README lists each one. For the token layer underneath, see the Tailwind design system skill.
quickanddeepset audit depth; a focus word such as security or perf limits the categories.branchaudits only what the current branch changes, tagging findings as introduced or pre-existing.nextsuggests where to take the project, andplan <description>skips the audit and specs one thing.review-plan,execute,reconcileand--issuescover critique, dispatch, backlog cleanup and GitHub issues.
How to install shadcn Improve Skill: Audit a Codebase, Get Agent Plans
git clone https://github.com/shadcn/improve.gitClone the repository
Run
git clone https://github.com/shadcn/improve.git. The skill is the skills/improve folder.Copy the skill folder
Copy skills/improve, including its references folder, into the folder where your agent loads skills. SKILL.md points at the audit playbook, plan template and closing-the-loop file there.
Run it in your repo
Open your agent in the project and run /improve, or /improve quick to keep the first pass cheap.
Pick findings
Reply with the findings you want planned. Plans land in plans, and you hand one to any agent or run the execute variant.
Check that it loaded
After a run you should see a findings table in chat, a plans folder with numbered files and an index, and no changes to your source files.
Key features
- Read-only by ruleThe agent may not edit source, run installs or commit. Its only writes go under plans, or advisor-plans when plans already exists for another purpose.
- Recon before judgmentIt reads the README, agent instruction files, config, CI and structure, then notes conventions that plans must tell the executor to match, with examples.
- Nine audit categoriesCorrectness, security, performance, test coverage, tech debt, dependencies and migrations, developer experience, docs, and direction. Quick mode narrows this to correctness, security and tests.
- Intent docs respectedIf the repo has ADRs, PRDs, CONTEXT.md, DESIGN.md or PRODUCT.md, the skill reads them so decided tradeoffs are not re-flagged as findings.
- Vetting stepFindings are re-checked against the code before you see them, and by-design behavior, wrong attributions and duplicates are rejected or corrected.
- Plans for the weakest executorEach plan inlines its context, lists ordered steps with a verification command each, sets file boundaries and adds stop conditions for when reality differs.
- Drift checkEvery plan stamps the git commit it was written against, so an executor can check mechanically whether the code moved before it starts.
- Execute with reviewThe execute variant dispatches a separate executor in an isolated git worktree, then reviews its diff like a tech lead. Merging stays with you.
- Secrets and injection rulesCredentials are referenced by file, line and type, never reproduced, and instructions found inside audited files are treated as data and logged as a finding.
Frequently asked questions
What is the improve skill?
It is a skill from shadcn that audits a codebase as a senior advisor and writes prioritized, self-contained implementation plans for other agents. It is read-only on source code and writes only to a plans folder, so implementation is always a separate step.
How do I install the improve skill?
Clone shadcn/improve and copy skills/improve, with its references folder, into your agent's skills folder. Then run /improve in your project. The repository also ships a plugin manifest, but its README documents the Agent Skills route rather than a plugin command.
Does the improve skill edit my code?
No. Hard rule one forbids editing source, and rule two forbids commands that mutate your working tree. Its execute variant sends a separate executor into a disposable git worktree, and the skill reviews that diff but never merges, pushes or commits to your branch.
What is the difference between improve and improve-ui?
Improve audits a whole codebase across nine categories. Improve UI is a read-only audit of one product surface against its own design system. Use improve for a backlog across code, and improve-ui when the interface itself is the question.
Which AI agents can run the improve skill?
The README says it works in any agent that supports the Agent Skills format, and that the plans are plain markdown any agent or human can pick up. Sub-agent fan-out and the execute variant need a host that can spawn sub-agents, and the skill says so when yours cannot.
How deep does the audit go?
Three levels. Quick looks at hotspots in correctness, security and tests, deep covers every package and category, and the default sits between. The final report states what was not audited, which matters on large monorepos.
Is the improve skill only for shadcn/ui projects?
No. It targets any language or framework, and its recon step finds the build and test commands itself. The README's worked example is a run against shadcn/ui, but nothing in SKILL.md limits it to that library. For shadcn-specific rules, use the shadcn skill.