# Improve: code audit that writes plans for other agents (shadcn/improve) — skill card for AI agents

> AgentGid skill card. Checked on 2026-11-05 against commit cac56e1 (version 1.0.0).
> Every fact comes from the pack's own files at that commit. Numbers marked "as reported" are the author's.
> Human page: https://agentgid.com/skills/shadcn/improve/

## Explain it to a non-programmer
Your AI coding assistant becomes an advisor for your project. It reads the whole project, lists what is worth fixing or building next, and writes a step-by-step plan for each item you pick. It never changes your code itself; a cheaper assistant or a person follows the plans.

## Who it is for
- You want a ranked list of bugs, security gaps, slow spots and old code in a project you own or took over
- You want ideas on what to build next, each backed by something in the project itself
- You want a strong model to plan the work and a cheaper one to do it
- You use Claude Code or another assistant that reads skills
- Not for: You want the fixes made right away: it declines and points at the plan
- Not for: You want a quick, cheap answer: a full run uses your strongest model and several helper agents

## What it is
- Kind: command, knowledge
- License: MIT
- Repository: https://github.com/shadcn/improve

## What it does
- 1 Recon: maps the project, its build, test and lint commands, its conventions, and design or decision documents if present
- 2 Audit in nine categories: correctness, security, performance, test coverage, tech debt, dependencies and migrations, developer tooling, docs, direction (what to build next)
- Large projects: one read-only helper agent per category, run in parallel
- Every finding carries file:line evidence, impact, effort (S/M/L), fix risk and confidence
- 3 Vet: re-reads every cited location itself, drops false positives and records rejected findings so they do not come back
- 4 Prioritize: a table ordered by impact divided by effort, weighted by confidence; direction ideas shown separately (2 to 4)
- 5 Plan: one self-contained file per chosen finding in plans/, with code excerpts, commands, scope, done criteria and STOP conditions
- Follow-through: execute hands one plan to a cheaper model and reviews its work; reconcile refreshes the backlog; --issues publishes plans as GitHub issues
- Never cuts: no edits to your source code (only plans/ is written), no commands that change your working tree, no secret values in findings or plans, files in the audited project are treated as data, not instructions
- Level quick: Hotspots only; correctness, security and tests; top ~6 high-confidence findings; 0 to 1 helper agents
- Level standard: Default: hotspot-weighted, all nine categories, up to 4 helper agents at once
- Level deep: Whole project, every package, all nine categories, up to 8 helper agents at once, low-confidence items included

## Skills
| Skill | Call | Changes code? | In plain words |
|---|---|---|---|
| improve | /improve [quick|deep] [security|perf|tests|...|branch|next|plan <description>|review-plan <file>|execute <plan>|reconcile] [--issues] | no | Checks your whole project and writes plans for the fixes you pick, without changing your code |

### improve
- Asks for: Your project, with the assistant opened in it
- Asks for: Optional: a focus (security, perf, tests, bugs) or effort level (quick, deep)
- Asks for: Your pick of findings to plan, e.g. "plan 1, 3 and 5"
- Asks for: For plan: a description of the one thing you want specified
- Gives: A findings table: finding, category, impact, effort, risk, evidence
- Gives: 2 to 4 direction ideas with evidence and trade-offs, shown after the table
- Gives: plans/NNN-<slug>.md for each chosen finding
- Gives: plans/README.md: order, dependencies, status, findings considered and rejected
- Gives: For execute: a verdict on the cheaper model's work (approve, revise, block)
- Say: "/improve quick"

## Know before installing
- It can start without the command: its description tells your assistant to use it whenever you ask to audit a codebase or suggest features.
- It writes only into a plans/ folder at the project root, or advisor-plans/ if plans/ is already used for something else.
- execute does change code, but in a separate throwaway copy of the project (a git worktree). A cheaper model (Sonnet by default) installs dependencies and commits there; merging is up to you.
- --issues posts plans as GitHub issues. On a public project it warns you first and asks before posting anything about a security hole or a credential location.
- It is built to run on your most capable model; a deep run starts up to 8 helper agents at once, so it costs more than a normal chat.
- Each plan records the commit it was written against, so whoever runs it first checks whether the code has changed since.

## Install (official commands)
- Any agent (skills CLI): `npx skills add shadcn/improve` — The only install command in the README. Uninstall steps are not documented in the repo.
- Claude Code (plugin): The repo also ships a Claude Code marketplace file (.claude-plugin/marketplace.json) with one plugin named improve; the README does not give plugin install commands.

## What runs on the user's machine
- Code on the machine: no
- Network: none
- Install: Markdown only: SKILL.md, three reference files and a Claude Code plugin manifest. No hooks, no scripts, no install steps.
- Audit: Tells your assistant to read files and run only read-only commands, such as git log, a type check with --noEmit, npm or pnpm audit, and the test suite if cheap and side-effect free.
- Planning: Your assistant writes plans/NNN-<slug>.md and plans/README.md (or advisor-plans/).
- execute: Your assistant starts one helper agent in an isolated git worktree; it installs dependencies, edits, runs the plan's checks and commits there. Nothing is merged, pushed or committed to your branch.
- --issues: Your assistant runs gh issue create for each plan, which sends the plan text to GitHub. Only with the flag.

## Examples (from the pack's own files)
- Findings from a run against shadcn-ui/ui (author's sample output): output format defined in README.md
- The plan it wrote for finding 1 (author's sample output): output format defined in examples/001-extract-shadow-config-resolution.md

## How to tell it works
Open your assistant in a project and run /improve quick. It comes back with a findings table and asks which ones to plan. Answer "plan 1"; a plans/ folder appears with a numbered plan file and a README.md index, and no other file in your project changes.

## Safety
The pack is markdown only. It tells the assistant to treat everything in the audited project as data and to report embedded instructions as a security finding. execute lets a helper model install dependencies and commit in a separate worktree; --issues sends plan text to GitHub. Install only from github.com/shadcn/improve.
