shadcn/improve

What it does

improve is an Agent Skill that audits an existing codebase, prioritizes what is worth fixing, and writes implementation plans into plans/. It deliberately separates planning from execution: a strong model does the reconnaissance, audit and spec writing, while cheaper models or humans carry out the plans. The skill itself never edits source code; its only writes go to plans/.

The audit fans out across nine categories — correctness, security, performance, test coverage, tech debt, dependencies and migrations, DX, docs, and direction. Every finding must cite file:line evidence, impact, effort and confidence, and the advisor re-reads cited locations before presenting them, recording rejected findings so they do not resurface.

Quick start

You need an agent that supports the Agent Skills format, and you should open it inside the repository you want audited. Install the skill with:

npx skills add shadcn/improve

Then run /improve in the agent session. Use /improve quick for a cheaper pass, or /improve deep to cover every package and category. The skill maps the repo, audits it and returns a findings table. Reply with the findings you want planned, for example "plan 1, 3 and 5". Plans are written to plans/ as one Markdown file per item plus an index with a recommended order; review them before handing one to an executor. /improve execute 001 dispatches a cheaper model in an isolated worktree and reviews its diff against the plan; merging remains your decision. Later, /improve reconcile verifies what landed, rewrites blocked plans and retires fixed findings.

Other entry points cover narrower cases: /improve security (also perf, tests, bugs and similar), /improve branch scopes the audit to the current branch, /improve plan <description> specs a single item without an audit, and --issues publishes plans as GitHub issues. See the usage section for the full command list and an example plan showing the expected level of detail.

How plans stay executable

Each plan is written for the weakest plausible executor: it inlines exact file paths, current-state code excerpts, repo conventions and verified commands, so the executor does not depend on the advisor session's context. Every step ends with a command and expected output, giving machine-checkable done criteria, and plans include explicit out-of-scope lists and STOP conditions. Each plan records the git commit it was written against so executors can check for drift before editing.

Recon also reads intent and design documents when present — ADRs under docs/adr/, PRDs, CONTEXT.md, DESIGN.md, PRODUCT.md — so already-decided tradeoffs are not re-flagged and feature suggestions stay grounded in stated product intent.

Constraints

• The audit is read-only: the skill does not modify the working tree, and it does not implement anything itself.
• Executors edit in disposable git worktrees; merging a diff is always left to the user.
• execute allows at most two revision rounds before it blocks and asks for the plan to be refined.
• Secret values are never reproduced; findings only report locations and credential types, with rotation recommended.
• The plans are plain Markdown, so any agent or human can pick them up, but installation and usage require an agent supporting the Agent Skills format.
• Licensed under MIT.

HotRepo's take

On 2026-11-11 the repository recorded 333 stars gained in a day and reached position 4 on the all-language GitHub daily ranking, with 10,353 stars and 427 forks at that snapshot. There is no longer time series to judge whether that pace held, so the position should be read as a single-day fact rather than a trend. The project's premise fits the ranking context: it targets a concrete cost tradeoff in agent-assisted development, using an expensive model only for audit and specification while delegating execution to cheaper models. Its distinguishing claims are the vetting pass that removes false-positive findings and the plan format built around verification gates and STOP conditions — details worth checking in the example plan before adopting the workflow.