Improve: code audit that writes plans for other agents
shadcn/improve
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.
Pack description by its author: “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.”
Software engineeringCommands you run when neededKnowledge and rules for your assistant
2. Runs code on your machine
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.
github.com/shadcn/improve/blob/cac56e1/3. Sends data
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.
github.com/shadcn/improve/blob/cac56e1/Checked against the pack's files at commit cac56e1, on Nov 5, 2026. Tap a verdict to see its source.How we checkedReport an error
Good for you if
- 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
Probably not for you if
- You want the fixes made right away: it declines and points at the plan
- You want a quick, cheap answer: a full run uses your strongest model and several helper agents
What its answer looks like
Findings from a run against shadcn-ui/ui (author's sample output)
| # | 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 | - [SEC-01] https_proxy env var "SSRF": by-design — standard proxy convention, every CLI honors it. Not a finding.
The skill's own example, from README.md. More examples
What you'll notice
- A table of findings first: what is wrong, how much it matters, how much work, how risky, and where in the code
- It asks which findings to plan and waits for your answer
- A plans folder in your project: one file per plan and an index with the order to do them in
- Each plan ends with checks to run and clear stop points, so a smaller model can follow it
What you need
- Claude Code, Any agent that supports the Agent Skills format
- Free, MIT license
- One command with the skills tool
- execute needs an assistant that can start helper agents in a separate copy of the project; --issues needs the GitHub gh tool, signed in
Words on this page
- Skill
- A set of written instructions your AI assistant follows. Installing one is like giving it a playbook.
- Slash command
- A command you type in the assistant's chat, starting with /.
- Subagent
- A helper the assistant starts for one part of a task.
| Repository | shadcn/improve |
|---|---|
| Also on AgentGid | Improve as an agent: usage, releases and alternatives |
| GitHub stars | 11,911 |
| Skills | 1 |
| Category | Software engineering |
| License | MIT |
| Last updated | Sep 12, 2026 · card checked Nov 5, 2026 at commit cac56e1 |
| Install counts | shadcn/improve on skills.sh, Vercel's skills directory, which shows installs and security audits per skill |
shadcn/improve popularity over time
What Improve 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 cut, per the skill: 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 | Behaviour |
|---|---|
| quick | Hotspots only; correctness, security and tests; top ~6 high-confidence findings; 0 to 1 helper agents |
| standard | Default: hotspot-weighted, all nine categories, up to 4 helper agents at once |
| deep | Whole project, every package, all nine categories, up to 8 helper agents at once, low-confidence items included |
From the pack's SKILL.md files, summarised by AgentGid.
The skill, explained
improve
Checks your whole project and writes plans for the fixes you pick, without changing your code
You give
- Your project, with the assistant opened in it
- Optional: a focus (security, perf, tests, bugs) or effort level (quick, deep)
- Your pick of findings to plan, e.g. "plan 1, 3 and 5"
- For plan: a description of the one thing you want specified
You get
- A findings table: finding, category, impact, effort, risk, evidence
- 2 to 4 direction ideas with evidence and trade-offs, shown after the table
- plans/NNN-<slug>.md for each chosen finding
- plans/README.md: order, dependencies, status, findings considered and rejected
- For execute: a verdict on the cheaper model's work (approve, revise, block)
See it in action
The skill defines what its answer looks like. Its own example:
| # | 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 | - [SEC-01] https_proxy env var "SSRF": by-design — standard proxy convention, every CLI honors it. Not a finding.
From README.md.
The skill defines what its answer looks like. Its own example:
A Markdown plan of about 170 lines, made at commit 1994caba0 of shadcn-ui/ui: executor instructions and a drift check, status (P2, effort M, risk MED, tech-debt), why it matters, the current code of both copies, commands, scope, step-by-step changes each with a check, done criteria and STOP conditions.
When to reach for it
| You want | Use |
|---|---|
| A full check of your project with ranked findings and plans | /improve |
| A cheap first pass | /improve quick |
| Every package and category checked | /improve deep |
| One area only | /improve security (also perf, tests, bugs, ...) |
| A check before a pull request | /improve branch |
| Ideas for what to build next | /improve next |
| A plan for one thing you already know you want | /improve plan <description> |
| A cheaper model to do a plan and a review of its work | /improve execute <plan> |
| The plan backlog brought up to date | /improve reconcile |
Skills in shadcn/improve
| Skill | In plain words | Changes files? | What it does (author) |
|---|---|---|---|
improve/improve [quick|deep] [security|perf|tests|...|branch|next|plan <description>|review-plan <file>|execute <plan>|reconcile] [--issues] |
Checks your whole project and writes plans for the fixes you pick, without changing your code | No | Survey any codebase as a senior advisor and produce prioritized, self-contained implementation plans for OTHER models/agents to execute. Strictly read-only on source code — never implements, fixes, or refactors anything itself. Use when asked to audit a codebase, find improvement opportunities…npx skills add shadcn/improve --skill improve |
The author's descriptions come from each skill's SKILL.md; the plain-words column is AgentGid's.
Good to know before you install
- 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 Improve
Official commands from the repository
npx skills add shadcn/improve
The only install command in the README. Uninstall steps are not documented in the repo.
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.
Or with the open-source skills CLI: npx skills add shadcn/improve. Skills are instructions your agent follows: read them before installing.
What it installs and runs on your machine
Read in the code at commit cac56e1, Nov 5, 2026
| When | What happens |
|---|---|
| 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. |
Quick answers
- Is it free?
- Yes. MIT license.
- Will it change my code?
- No. It writes only plans. With execute, a separate model edits a throwaway copy and you decide whether to merge.
- Can a person follow the plans instead of an agent?
- Yes. The plans are plain Markdown for any agent or human.
- What if it finds a password or key in my code?
- It names the file, line and kind of credential, never the value, and recommends rotating it.
- Does it post anything online?
- Only with --issues, which creates GitHub issues from the plans; on a public project it asks first for sensitive ones.
Checked by AgentGid on Nov 5, 2026 against commit cac56e1 of the pack's own files. agent.md for AI agents · Report a mistake
More software engineering skill packs
| # | Skill pack | Skills | GitHub stars | Updated |
|---|---|---|---|---|
| 1 |
mattpocock/skills Your AI coding assistant gets a set of working habits for building software. It interviews you about a plan before it builds, tur…
|
39 | 325K | 2026-11-13 |
| 2 |
obra/superpowers Your coding assistant follows one fixed way of working. Before it builds anything, it asks what you really want and writes a shor…
|
15 | 318K | 2026-11-03 |
| 3 |
multica-ai/andrej-karpathy-skills Your AI coding assistant gets four rules: think before coding, keep it simple, change only what you asked for, and set a clear go…
|
1 | 233K | 2026-04-20 |
| 4 |
DietrichGebert/ponytail Your AI coding assistant stops overbuilding. It does what you asked in the simplest way that works, reuses what your project alre…
|
6 | 191K | 2026-10-29 |
| 5 |
Shubhamsaboo/awesome-llm-apps This repo is mostly a big collection of AI apps and tutorials. Its agent_skills folder holds seven separate skills you install on…
|
10 | 145K | 2026-11-15 |
| 6 |
addyosmani/agent-skills Your AI coding assistant works like a careful senior engineer. It writes down what to build before coding, splits the work into s…
|
25 | 118K | 2026-11-14 |