Skip to content
Agents tracked: 502 Releases (7d): 613 Agent status: 4 with issuesSince last limit reset: Claude 7d · Codex 5d For AI agents: Markdown Updated Nov 18, 2026

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

GitHub

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

Commands you run when neededKnowledge and rules for your assistantNothing to run: text files only

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.
Repositoryshadcn/improve
Also on AgentGidImprove as an agent: usage, releases and alternatives
GitHub stars11,911
Skills1
CategorySoftware engineering
LicenseMIT
Last updatedSep 12, 2026 · card checked Nov 5, 2026 at commit cac56e1
Install countsshadcn/improve on skills.sh, Vercel's skills directory, which shows installs and security audits per skill

shadcn/improve popularity over time

Most starred skill packs

shadcn/improve: GitHub starstotal over time 11,911
shadcn/improve: new stars per weekGitHub 2,578

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.

LevelBehaviour
quickHotspots only; correctness, security and tests; top ~6 high-confidence findings; 0 to 1 helper agents
standardDefault: hotspot-weighted, all nine categories, up to 4 helper agents at once
deepWhole 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)
Say: “/improve quick”

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.

When to reach for it

You wantUse
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
Try it. 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.

Skills in shadcn/improve

SkillIn plain wordsChanges 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 codeNo 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.

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

WhenWhat happens
InstallMarkdown only: SKILL.md, three reference files and a Claude Code plugin manifest. No hooks, no scripts, no install steps.
AuditTells 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.
PlanningYour assistant writes plans/NNN-<slug>.md and plans/README.md (or advisor-plans/).
executeYour 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.
--issuesYour 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

All software engineering skills

# 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