AI-assisted summary: I read the repository and its README, then wrote this overview. The project was not deployed or benchmarked here.

shadcn/improve: spend tokens on thinking, not on typing

A GitHub trend worth watching this week is shadcn/improve — an agent skill that separates the expensive part of software work from the cheap part.

The repository description is blunt: "Use your most capable model to audit your codebase and write plans for cheaper models to execute." The skill never implements anything itself. The plan is the product.

The loop

you          →  /improve                    (expensive model, advises)
plans/       →  001-fix-n-plus-one.md       (self-contained specs)
other agent  →  implements, tests, ships    (cheap model, executes)

Most "cheap model" experiments fail because the task was never specified well. This one flips the order: pay for understanding and judgment, then hand a precise spec to a smaller model.

How it works

Recon maps the repo: stack, conventions, exact build/test/lint commands — these become verification gates later. If the project has ADRs, a PRD, CONTEXT.md or DESIGN.md, it reads them so settled tradeoffs don't come back as findings.

Audit fans out parallel subagents over nine categories: correctness, security, performance, test coverage, tech debt, dependencies and migrations, DX, docs, and direction. Every finding carries file:line, impact, effort, and confidence.

Vet is the part I like most: the advising model re-reads every cited location itself before showing anything. Subagents over-report; false positives are dropped, wrong attributions fixed, and rejections recorded so they don't resurface next run.

Prioritize ranks findings by leverage (impact ÷ effort, weighted by confidence). You pick what becomes a plan.

Plan writes one markdown file per finding into plans/, with an index, priority order, and a dependency graph.

Why the plans are executable

Plans target "the weakest plausible executor" — a model that never saw the advisor session. Three properties carry that:

• Self-contained. Exact paths, current-code excerpts, repo conventions with an exemplar file, verified commands.
• Verification gates. Every step ends with a command and its expected output, so done criteria are machine-checkable.
• Hard boundaries. Explicit out-of-scope lists and STOP conditions instead of letting a small model improvise.

Each plan also stamps the git commit it was written against, so executors can detect drift.

Practical notes

The skill never modifies source code — its only writes go to plans/. /improve execute runs a cheaper agent in an isolated worktree, then reviews the result like a tech lead: re-runs every done criterion, checks scope, reads the diff. Merging stays with you. reconcile refreshes the backlog later.

Around 11.6k stars, MIT, last commit September 2026. It requires an agent that supports the Agent Skills format (npx skills add shadcn/improve).

One boundary worth stating clearly: this audits source code, not servers or infrastructure. It complements dependency scanning and CVE feeds; it does not replace them.

Repository: github.com/shadcn/improve