improve
Use your most capable model to audit your codebase and write plans for cheaper models to execute.
Improve is an AI agent skill that audits a codebase and writes detailed improvement plans as markdown files, without ever touching your source code directly.
Improve is an agent skill that audits a codebase and writes detailed plans for improvements, but deliberately stops short of making any changes itself. The reasoning behind this separation is that understanding a codebase and judging what is worth fixing requires more intelligence than actually carrying out a well-specified task. So the skill is designed to run on a powerful, more expensive AI model that handles the thinking, and the resulting plans can then be handed to a cheaper model, another agent, or a human to execute.
When you run it, the skill first maps the repository: it reads the code structure, identifies the build and test commands, and ingests any design documents or architecture decision records it finds. It then fans out across nine categories of concerns including correctness, security, performance, test coverage, and technical debt. Multiple sub-processes handle different categories in parallel and report their findings. Before showing you anything, the skill re-reads the cited code locations itself to filter out false positives and wrong attributions.
Findings are presented in a table ranked by impact relative to effort. You pick which ones to plan, and it writes one markdown file per finding into a plans/ directory. Each plan is designed to be read by an executor that knows nothing about the original audit session. It includes exact file paths, current code excerpts, the repository's own lint and test commands as verification steps, and explicit stop conditions for when the real state of the code does not match what the plan assumed.
From there, an execute command can dispatch a separate cheaper model in an isolated copy of the repository to carry out a specific plan, then review the result before anything is merged. A reconcile command revisits existing plans to check which have been completed, which have drifted as the codebase changed, and which need to be unblocked.
The skill never writes to your source files directly. All its output goes to the plans/ directory. Merging any changes produced by an executor is always left to you. It is released under the MIT license by the creator of shadcn/ui.
Where it fits
- Run a security and correctness audit on a codebase and get a ranked table of issues without any code being changed automatically.
- Generate a self-contained markdown plan for a specific bug fix that a cheaper AI model or junior developer can execute without needing the original context.
- Periodically reconcile existing improvement plans against the codebase to find which have been completed and which have drifted.
- Hand off planned improvements to a separate executor agent running in an isolated copy of the repository, then review before merging.