# Improve By **shadcn** ยท Skills Agent skill that audits your codebase with a capable model and writes executable plans for cheaper models to implement, by shadcn. - Source: https://github.com/shadcn/improve - Repository: https://github.com/shadcn/improve - Install: `npx skills add shadcn/improve` - Tags: agent, open-source, cli, code-review, planning, multi-agent, mit-license, agentic - Pricing: free - Upvotes: 0 ## Features - Full codebase audit across nine categories: correctness, security, perf, test coverage, tech debt, deps, DX, docs, direc - Prioritized findings table ordered by leverage (impact divided by effort, weighted by confidence) - Self-contained markdown plan files with inlined context, verification gates, and STOP conditions - execute command dispatches a cheaper subagent in an isolated worktree and tech-leads the diff - reconcile command verifies, unblocks, refreshes, and retires plans across sessions - branch mode scopes the audit to only what the current branch changes - Ingests ADRs, PRDs, CONTEXT.md, DESIGN.md to avoid re-flagging decided tradeoffs - --issues flag publishes plans as GitHub issues for agent or human pickup --- ## Why it matters Running your most capable model on every line of code is expensive and wasteful. Improve splits the job: expensive model understands and judges, cheap model executes. That asymmetry makes high-quality code review economically viable on real codebases. ## The big picture Improve is an agent skill by shadcn, installed with one `npx skills add shadcn/improve` command. It works inside any agent that supports the Agent Skills format. You run `/improve`, it maps the repo, fans out parallel subagents across nine audit categories, vets every finding by re-reading cited locations, and returns a prioritized findings table. You pick what gets planned. The skill never touches a line of source code. ## How it works Recon comes first: the skill maps the stack, conventions, and build/test/lint commands that become verification gates in every plan. It also ingests intent docs when present: ADRs in `docs/adr/`, PRDs, `CONTEXT.md`, `DESIGN.md`, and `PRODUCT.MD`. Decided tradeoffs are not re-flagged as findings. Audit fans out across nine categories: correctness, security, performance, test coverage, tech debt, dependencies and migrations, DX, docs, and direction (feature suggestions must cite repo evidence, per the README). Every finding carries `file:line` evidence, impact, effort, and confidence. Subagents over-report, so the advisor re-reads every cited location before surfacing anything. Plans land in `plans/`, one file each, with an index, priority order, and a dependency graph. Plans are written for the weakest plausible executor: all context is inlined, every step ends with a verifiable command, and explicit STOP conditions prevent small models from improvising when reality diverges from the plan. Each plan stamps the git commit it was written against. ## Zoom in `/improve execute ` spawns a cheaper executor subagent in an isolated git worktree, hands it the plan, and then reviews the diff like a tech lead: re-runs every done criterion, checks scope compliance, and returns a verdict of approve, revise (max two rounds), or block. Merging is always the developer's call. `/improve reconcile` closes the loop after a session: verifies DONE plans still hold, rewrites around obstacles for BLOCKED ones, refreshes drifted plans, and retires findings fixed independently. `--issues` publishes plans as GitHub issues with the same self-contained body. ## Yes, but Improve advises and plans; it does not implement. If you need code written immediately without a planning step, the workflow adds friction. The value compounds over sessions: the reconcile loop is where backlog hygiene pays off. ## The bottom line Improve is the clearest expression of a two-tier agent architecture in the wild: one capable model that thinks, many cheap models that execute, and a plan format designed for the weakest executor in the chain. For teams running AI-assisted development at scale, it is one of the more rigorous approaches to keeping costs low without sacrificing audit quality. ## FAQ ### What is Improve and what does it actually do? Improve is an agent skill by shadcn that audits a codebase using your most capable model and writes self-contained implementation plans for cheaper models to execute. It fans out parallel subagents across nine audit categories, vets every finding by re-reading cited file locations, and returns a prioritized table. The skill never writes or modifies source code, its only output is markdown plan files in a plans/ directory. ### How do I install and run Improve? Install with `npx skills add shadcn/improve` in any agent that supports the Agent Skills format. Once installed, open your agent inside a repo and run `/improve` for a full audit, or `/improve quick` for a cheaper pass focused on hotspots. The skill maps the repo, returns a findings table, and you tell it which findings to turn into plans, for example 'plan 1, 3 and 5'. ### Is Improve free and open source? Yes, Improve is released under the MIT license by shadcn and is free to install and use. There is no subscription or Improve-operated service, all model inference costs are your own and flow through whichever agent and models you configure. The README notes that the audit step intentionally uses your most capable (typically most expensive) model, while execution targets cheaper models. ### What is Improve best for? Improve is best for teams running AI-assisted development who want rigorous, evidence-backed code review without paying capable-model rates for execution. It shines on codebases that maintain intent docs like ADRs, PRDs, or CONTEXT.md, which it ingests so decided tradeoffs are not re-flagged as findings. The two-tier architecture, expensive advisor, cheap executor, makes systematic auditing economically viable at scale. ### How does Improve differ from just asking a model to review my code? A plain model review gives you prose suggestions with no structured handoff to execution. Improve writes plans designed for the weakest plausible executor: all context is inlined, every step ends with a verifiable command and expected output, and explicit STOP conditions prevent a smaller model from improvising when reality diverges from the plan. It also stamps each plan with the git commit it was written against, enabling a mechanical drift check before any executor touches anything. ### What are the hard limits and risks of using Improve? Improve never implements code itself; every plan requires a separate agent or the /improve execute command to act on it, and merging is always the developer's responsibility. Parallel subagents over-report findings, the vet step filters false positives by re-reading cited locations, but it is not infallible. The skill also makes no guarantees about the quality of execution by downstream agents: it reviews the diff and returns a verdict, but cannot force correctness in a model it does not control. --- [View on Analog](https://analoghq.ai/shadcn/skills/improve)