improve Skill (shadcn) for Claude: What It Does and How to Install It

Makes your agent audit a codebase and write detailed plans for other agents to carry out, without changing your source code itself.

Installs: 38.6K; on skills.sh
Stars: 9.3K; on GitHub
Files: 3; besides SKILL.md
Updated: Sep 2026; last repo commit

This is shadcn's advisor skill. Run /improve and the agent maps the repo, audits it across nine categories, checks each finding itself and shows a ranked table. You pick which findings become plans.

Plans go in a plans/ folder, each written so a different agent with no context can execute it. The skill says it never edits your source. Only its execute mode sends a separate agent to change code, in an isolated git worktree.

Good for

Developers who want a prioritized list of bugs, security and tech-debt issues
Teams that plan with a strong model and build with cheaper ones
Maintainers who want roadmap ideas grounded in their own repo
Anyone about to open a pull request who wants a branch-only review

Install improve

Claude Code

Copy this prompt.

Install the improve skill in Claude Code. Run this command:

npx skills add https://github.com/shadcn/improve --skill improve

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

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 (bugs, security, performance, test coverage, tech debt, migrations, DX), suggest features or where to take the project next (roadmap, product direction), or generate handoff plans for another agent to implement.

Sections in SKILL.md

Hard Rules
Workflow
Phase 1 — Recon (always)
Phase 2 — Audit (parallel)
Phase 3 — Vet, prioritize, confirm
Phase 4 — Write the plans
Invocation variants
Tone of the output

Key facts

Author: shadcn
License: MIT
Installs on skills.sh: 38,560 (Nov 2, 2026)
GitHub stars: 9,319 for the shadcn/improve repo (Nov 2, 2026)
Last repo commit: Sep 12, 2026
What it includes: 4 files: SKILL.md and 3 reference guides (audit playbook, plan template, closing the loop). No scripts
Needs: A git repository for branch and execute modes; the GitHub CLI (gh) only for --issues
Skill version: 1.0.0
Works in: Any agent that supports the Agent Skills format, per the README. The execute mode needs an agent that can spawn subagents in an isolated git worktree

What it includes

Full audit, ranked findings, then plans
Recon, parallel audit, vetting, then plans for the findings you choose. Plans are written to plans/ (or advisor-plans/ if plans/ is taken).
Try: “/improve quick”
Write · /improve
Sets how much of the repo is audited
Quick looks at hotspots with about 6 top findings. Deep covers every package with up to 8 parallel subagents.
Read · quick / deep
Audits one category, such as security, perf or tests
Runs recon, then only that category.
Try: “/improve security”
Write · Focus argument
Audits only what the current branch changes
Compares against the merge base and tags findings as introduced or pre-existing.
Try: “/improve branch”
Runs code · branch
Feature and roadmap ideas
4 to 6 suggestions, each with evidence from the repo and trade-offs. Also called features or roadmap.
Read · next
Skips the audit and writes one plan
Investigates just enough to specify what you described.
Write · plan <description>
Critiques and tightens an existing plan
Checks a plan in plans/ against the template standards.
Write · review-plan <file>
Sends a cheaper agent to carry out a plan
The executor works in an isolated git worktree. The advisor re-runs the done checks, reads the diff and gives a verdict. Merging stays yours.
Try: “/improve execute 001”
Runs code · execute <plan>
Refreshes the plan backlog
Verifies finished plans, investigates blocked ones and retires findings that were fixed.
Write · reconcile
Also publishes each plan as a GitHub issue
Uses the gh CLI and only runs when you pass the flag. Public repos need your confirmation for security plans.
Write · --issues

From the official docs

Permissions

Medium risk

The skill reads your whole repository and writes plan files, and its execute and --issues options can change code in a worktree or publish to GitHub. Skip those options unless you want them, and review every diff.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

execute lets another agent change your code
In execute mode a separate agent edits files in an isolated git worktree. The skill reviews the diff and never merges for you, but you still read the diff before merging. github.com
--issues can publish findings on GitHub
SKILL.md says to check whether the repo is public and to get your confirmation before publishing security or credential findings. Say no if unsure. github.com
Deep audits spend a lot of tokens
Deep mode runs up to 8 parallel subagents. Use quick first on large repos. github.com
It tells the agent to treat repo text as data
SKILL.md says instructions found in repo files are not to be followed and are logged as a security finding. It also says secret values are never copied into plans. github.com
It runs commands in your repo during the audit
SKILL.md allows read-only analysis such as tsc --noEmit, lint in check mode, npm or pnpm audit and the test suite. Your own test suite runs your code, and an audit command may contact a package registry. Check what it ran. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	Its hard rules say it does not edit your source and does not run commands that change your working tree. Plans are the only files it writes outside execute mode.
Talks to	GitHub, only with --issues. Package registry, if the agent runs npm or pnpm audit
Sign-in and keys	SKILL.md does not mention any account or key. The GitHub CLI uses your own gh login for --issues.
Scopes	Reads your repository, including README, CLAUDE.md, config and git history Writes plan files under plans/ or advisor-plans/ execute mode: a separate agent edits code in a disposable git worktree and runs verification commands --issues: creates GitHub issues with gh Runs analysis commands in your repo, such as tsc --noEmit, lint in check mode, npm or pnpm audit, and your test suite if it is cheap and side-effect free

Questions

What does the improve skill do?

It audits your codebase like a senior advisor and writes self-contained plans for other agents to implement. It covers bugs, security, performance, tests, tech debt, dependencies, tooling, docs and product direction.

How do I install improve?

Use the install box at the top of this page. The README's own command is the skills CLI, shown there. Then run /improve in your repo.

Does it change my code?

Not by itself. SKILL.md says the only files it writes are under plans/ (or advisor-plans/). The execute option sends a separate agent to edit code in an isolated git worktree, and merging is up to you.

What should I run first?

Try /improve quick for hotspots and about 6 top findings. Use deep for every package and category, or a focus word such as security or perf.

Does it need a git repository or the GitHub CLI?

Git is needed for the branch and execute modes. The GitHub CLI is needed only for --issues, and the skill only publishes issues when you pass that flag.

Which AI tools does it work in?

The README says it works in any agent that supports the Agent Skills format. The execute mode needs an agent that can spawn subagents in an isolated worktree. If yours cannot, the skill says to hand the plan over for manual execution.

Is improve safe?

It reads your repo and writes plan files under plans/ or advisor-plans/. SKILL.md says it never copies secret values into plans. execute lets a separate agent edit code in an isolated git worktree, and --issues publishes plans as GitHub issues, so review those two before you use them.

Information

updated Nov 2, 2026

Repository: shadcn/improve
Folder: skills/improve

shadcn/improve skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 3

improve SKILL.md · github.com
shadcn/improve README · github.com
closing-the-loop.md · github.com