Stop Burning Expensive Tokens on Work a Cheaper Model Could Do

You've probably noticed that the cost of running an AI agent isn't evenly distributed. Asking a top-tier model to reason about your codebase, weigh tradeoffs, and figure out what's actually worth fixing is money well spent. Asking that same model to then go rename a variable across twelve files or fix an N+1 query is not. So what if you split the job—let the smart model write the spec, and hand execution to something cheaper? That's the idea behind improve, an agent skill that audits your codebase and writes implementation plans for other agents to execute.

What It Does

improve is a skill in the Agent Skills format. You point it at a repo, and it maps the codebase, audits it, and produces a findings table—prioritized issues with categories, effort estimates, and confidence levels. From there, you pick which findings you want planned, and it writes self-contained markdown specs into a plans/ directory, one file per plan, plus an index with a recommended order.

The skill never implements anything itself. The plan is the product. Each plan excerpts the current code, lays out exact steps, includes your repo's own build/test/lint commands as verification gates, and adds STOP conditions for when reality doesn't match the spec. Because the plans are plain markdown, any agent—or any human—can pick them up and run with them.

It also ingests your existing intent docs when they're present (ADRs in docs/adr/, PRDs, CONTEXT.md, DESIGN.md, PRODUCT.md), so decided tradeoffs don't get re-flagged as findings and the plans speak your repo's own vocabulary.

Why It's Cool

• It puts intelligence where it compounds. The core insight is simple but well-executed: use your most capable model for the part that requires judgment—understanding the codebase, deciding what matters, writing the spec—and let cheaper models handle execution. The README's example flow makes this explicit: expensive model advises, cheap model executes.

• The plan format is genuinely thought through. These aren't vague "refactor this" notes. The example plan (linked in the README, generated from a run against shadcn/ui) includes current code excerpts, exact steps, verification gates pulled from your repo's actual commands, and STOP conditions. That last part matters—it tells the executing agent when to bail out rather than improvise.

• It records what it rejected. Findings that get dismissed are logged with reasons so they don't come back next run. The README's example is a security finding that turned out to be by-design proxy behavior. That kind of memory keeps the backlog from filling with noise.

• The command set covers the full loop. Beyond the full audit, there's quick for a cheap pass, deep for exhaustive coverage, category-focused runs (security, perf, tests, bugs), branch to scope an audit to just what your current branch changes, and next for feature suggestions grounded in your product docs.

• It closes the loop on execution and cleanup. /improve execute 001 dispatches a cheaper model in an isolated worktree, reviews the diff against the plan, and reports a verdict—merging stays with you. /improve reconcile refreshes the backlog between sessions: verifying what landed, unblocking what got stuck, retiring what's done. And --issues publishes plans as GitHub issues if that's how your team works.

How to Try It

1. Install the skill:

   npx skills add shadcn/improve
   

   It works in any agent that supports the Agent Skills format.

2. Open your agent in a repo and run a first pass. To keep it cheap:

   /improve quick
   

   Or go full audit with /improve.

3. Review the findings table it returns and reply with the numbers you want planned—something like "plan 1, 3 and 5."

4. Read the plans that land in plans/. They're meant to be reviewed, not blindly trusted.

5. Hand a plan to any agent ("implement plans/001-*.md"), or let the skill dispatch one:

   /improve execute 001
   

6. Next session, tidy up with /improve reconcile. Before a PR, scope an audit to your branch with /improve branch.

You can find the repo and the example plan at github.com/shadcn/improve.

Final Thoughts

The pitch here isn't a new model or a new framework—it's a workflow discipline. Separating the advisory work from the execution work is something most of us do informally already; improve just makes it explicit and gives the handoff a durable artifact. It's best suited to people running agents on real codebases where token costs add up and where a reviewed plan is more trustworthy than an unsupervised diff. If that sounds like your setup, the first /improve quick run is about as low-commitment as it gets.

Follow @githubprojects for more developer tools and open source projects.