improve
An agent skill that audits any codebase and writes implementation plans for other agents to execute.
The idea: use your most capable model for the part where intelligence compounds — understanding the codebase, judging what's worth doing, writing the spec — and hand execution to cheaper models. The skill never implements anything itself. The plan is the product.
you → /improve (expensive model, advises)
plans/ → 001-fix-n-plus-one.md (self-contained specs)
other agent → implements, tests, ships (cheap model, executes)
Install
npx skills add shadcn/improve
Works in any agent that supports Agent Skills format. The plans it writes are plain markdown, so any agent (or human) can pick them up.
Usage
/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 plan
/improve execute <plan> dispatch a cheaper executor, review its work
/improve reconcile refresh the backlog: verify, unblock, retire
/improve ... --issues also publish plans as GitHub issues
How to use
A typical first run, start to finish:
- Open your agent in the repo and run
/improve (or /improve quick to keep it cheap).
- It maps the repo, audits it, and comes back with a findings table. Reply with the ones you want planned — "plan 1, 3 and 5".
- Plans land in
plans/ — one file each, plus an index with the recommended order. Read them; they're meant to be reviewed.
- Hand a plan to any agent ("implement plans/001-*.md"), or let the skill run it:
/improve execute 001. It dispatches a cheaper model in an isolated worktree, reviews the diff against the plan, and reports back with a verdict. Merging stays up to you.
- Next session, run
/improve reconcile to clean up the backlog: verify what landed, refresh what drifted, unblock what got stuck.
Before a PR, /improve branch does the same thing scoped to just what your branch changes.
Example
A run against shadcn/ui came back with findings like:
| # | 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 |
…and rejected a few, with reasons recorded so they don't come back next run:
- [SEC-01] https_proxy env var "SSRF": by-design — standard proxy convention,
every CLI honors it. Not a finding.
Picking #1 produced this plan — current code excerpted, exact steps, the repo's own test/lint commands as verification gates, and STOP conditions for when reality doesn't match.
How it works
Recon. Maps the repo: stack, conventions, and the exact build/test/lint commands — these become verification gates in every plan.
Audit. Fans out parallel subagents across nine categories: correctness, security, performance, test coverage, tech debt, dependencies & migrations, DX, docs, and direction (feature suggestions — every one must cite evidence from the repo itself, no generic idea-slop). Every finding carries file:line evidence, impact, effort, and confidence.
Vet. Subagents over-report, so the advisor re-reads every cited location itself before showing you anything — false positives get dropped, wrong attributions get corrected, rejections get recorded.
Prioritize. Findings land in a table ordered by leverage (impact ÷ effort, weighted by confidence). You pick what becomes plans.
Plan. One file per selected finding, written into plans/ with an index, priority order, and dependency graph.
What makes the plans executable
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:
