Improve: turn codebase audits into executable plans.

Improve: plan the work before an agent writes code

Improve is an Agent Skills format skill for developers who want a structured assessment of an existing repository. Its advisor workflow maps the project, checks code and documentation, vets proposed findings against cited files, and ranks the work. You then select findings to turn into plans that a separate agent or human can execute. The repository README describes the plan, rather than a code change, as the main output.

Install it in an agent that supports the Agent Skills format with npx skills add shadcn/improve. In a repository, run /improve for a broad audit or /improve quick for a narrower first pass. The skill presents findings before drafting plans; choose which ones deserve a specification. It writes individual Markdown files and an index in plans/ (or advisor-plans/ if that folder is already used for something else). You can give a plan to another agent, or use /improve execute <plan> where the host supports subagents and isolated worktrees. The README's usage guide also documents focused audits, branch review, plan review, and backlog reconciliation.

The value is in the handoff detail. According to the skill instructions, plans include the affected paths, current state, repository conventions, ordered steps, verification commands, done criteria, and conditions that tell an executor to stop when the code has drifted. A sample plan shows how those pieces fit together for a small refactor. Read the findings and plans before acting: an audit can miss context, and the skill explicitly asks the user to choose what gets planned.

Improve itself is deliberately limited to advisory changes under its plan directory. Its execute mode delegates implementation to another agent and reviews that work; it does not merge it. The skill's depth and delegation also depend on the agent host. This makes it most useful when you can spend capable-model attention on judging and specifying work, then review implementation separately. Source: skill rules.

Example use cases

• Suggested application: Audit a legacy service for correctness and test gaps, then commission only the highest-confidence fixes.
• Suggested application: Run /improve branch before a pull request to look for issues in changed files and their direct callers.
• Suggested application: Write a plan for a known migration with /improve plan <description>, then hand the Markdown file to an implementation agent.

Sources

• Improve repository and README
• Improve skill instructions
• Example implementation plan

Source image: GitHub repository sharing image for shadcn/improve.