SkillInstalls cleanly
Audit and improve a codebase
codebase-audit-and-improve
Adds /improve and /improve-all: audits codebase health, writes an IMPROVEMENTS.md roadmap, then fixes items one tested git commit at a time.
- Works with
- Claude Code, Codex CLI
- Good for
- Build an app, Web developers
What it does
Codebase Audit & Improve is a pair of skills that turn "make this repo healthier" into a repeatable loop. It checks the working tree and records a lint and test baseline, audits the project in six areas (architecture, code quality, performance, maintainability, security, tests), and writes an IMPROVEMENTS.md roadmap with numbered tasks from P0 to P3.
/improve stops after the audit and shows you the plan. When you ask it to implement the tasks, or when you run /improve-all, it works through them one by one: a small change, lint with no new warnings, tests, then one git commit per task. /improve-all goes on by itself to push the work, open a pull request and watch CI until it passes.
The installer is a shell script that copies the two skill folders into place. It deletes and recreates the folders it manages so old copies do not linger. Use the claude target unless you want every supported agent updated at once.
Example prompts
- "/improve"
- "/improve-all"
- "Run codebase audit with improve skill"
- "Implement all tasks in IMPROVEMENTS.md atomically"
- "Run full test suite, push changes, and verify CI status"
How to install
git clone https://github.com/Aclguh/codebase-audit-and-improve.gitcd codebase-audit-and-improvechmod +x install.sh && ./install.sh claudeHow to use it
In Claude Code type /improve for an audit and an IMPROVEMENTS.md plan, or /improve-all for the full loop: fixes, commits, push, PR and CI checks.
Check it works
After ./install.sh claude, confirm ~/.claude/skills/improve/SKILL.md and ~/.claude/skills/improve-all/SKILL.md exist. Start a new Claude Code session in a throwaway git project and type /improve. It should check git status, detect the stack, run the lint and test baseline, and write IMPROVEMENTS.md.
Common problems
- Your own /improve command disappeared — install.sh deletes files named improve.md and improve-all.md in ~/.claude/commands and ~/.cursor/commands on every run; back them up first — https://github.com/Aclguh/codebase-audit-and-improve/blob/11b20647301a50a8063ea6f4e102a5a81130cb8a/install.sh
- Too many agents updated — the README's
./install.sh allwrites for every agent; rerun with one target such as./install.sh claude(see./install.sh --help) — https://github.com/Aclguh/codebase-audit-and-improve/blob/11b20647301a50a8063ea6f4e102a5a81130cb8a/install.sh - check_health.py not found — the skill text calls
python scripts/check_health.py, but the scripts are in~/.claude/skills/improve/scripts/, not in your project; point the assistant there — https://github.com/Aclguh/codebase-audit-and-improve/blob/11b20647301a50a8063ea6f4e102a5a81130cb8a/skills/improve/SKILL.md - Slash commands missing — start a new session after install — https://github.com/Aclguh/codebase-audit-and-improve
Other assistants
- Codex:
./install.sh codexwrites into~/.agents/skills(the user skills folder Codex reads); call$improveor$improve-all— https://github.com/Aclguh/codebase-audit-and-improve/blob/11b20647301a50a8063ea6f4e102a5a81130cb8a/README.md - Cursor:
./install.sh cursorwrites~/.cursor/rules/improve.mdcandimprove-all.mdc— https://github.com/Aclguh/codebase-audit-and-improve/blob/11b20647301a50a8063ea6f4e102a5a81130cb8a/install.sh - Google Antigravity:
./install.sh antigravitywrites~/.gemini/config/skills. That is not a Gemini CLI folder, and the README does not list Gemini CLI — https://github.com/Aclguh/codebase-audit-and-improve/blob/11b20647301a50a8063ea6f4e102a5a81130cb8a/README.md
What to watch out for
- install.sh deletes and recreates ~/.claude/skills/improve and ~/.claude/skills/improve-all (or .claude/skills in the project with --workspace)
- Every install.sh run, also with the claude target, deletes any files named improve.md and improve-all.md in ~/.claude/commands and ~/.cursor/commands (your own too, if they have those names), and ~/.codex/skills/improve* when ~/.agents/skills/improve exists
- The README's default ./install.sh all also writes ~/.gemini/config/skills (Antigravity), ~/.cursor/rules/*.mdc, ~/.continue/config.json (only if absent) and ~/.agents/skills (Codex, DeepSeek); use the claude target unless you want every agent
- Both skills edit your code and make one git commit per task; the skill may stash uncommitted work first
- /improve-all also creates a refactor/audit-improvements-<date> branch when you are on main, master or release, pushes to origin, opens a PR with gh pr create, and keeps fixing, committing and pushing until GitHub Actions CI is green
- First run appends IMPROVEMENTS.md to .gitignore when the rule is missing; at the end the roadmap is moved to docs/audits/ and committed (or deleted on request)
- scripts/check_health.py runs git commands and, for the baseline, your project's lint and test commands with shell=True (120 s timeout each); with no lint script in package.json it runs npx eslint ., which can download eslint
Licence and author
- Licence
- MIT
- Author
- Aclguh
- Source code
- github.com/Aclguh/codebase-audit-and-improve
How we tested it
We installed it on an empty test computer on 6 Nov 2026. Installed and started in a clean test system. Not yet used in a real AI session.
The intake sandbox cannot run git clone install lines, so this test was done by hand. Before the install we put our own improve.md in ~/.claude/commands and ~/.cursor/commands: the installer deleted both and kept other.md. ./install.sh gemini is rejected (exit 2). We did not run /improve on a project. Not yet used on real work.
Technical details of the test
- Date
- 6 Nov 2026
- Method
- Manual sandbox run on 2026-11-06 in a clean container (oexp-sandbox image) with no account and no API key: ran git clone https://github.com/Aclguh/codebase-audit-and-improve.git, cd codebase-audit-and-improve, chmod +x install.sh && ./install.sh claude (commit 11b2064). Exit 0; ~/.claude/skills/improve and ~/.claude/skills/improve-all each hold SKILL.md (name improve / improve-all), LICENSE, references/ and scripts/. Nothing was written for other agents.
Checked again on 6 Nov 2026
Alternatives
- Code Modernization — Anthropic's plugin that assesses old code and plans an upgrade you approve
- Trail of Bits Skills — security review of your own, authorised code
- Superpowers — plan, test first and review its own work, for any coding task
FAQ
- Q: Does install need network beyond git clone? A: No. install.sh only copies local files. Later, the baseline step can run
npx eslint ., which may download eslint. - Q: Will it commit for me? A: Yes. Both skills make one git commit per task.
/improve-allalso pushes, opens a pull request on a protected branch and fixes CI failures by itself. Run/improveif you want to read the plan first. - Q: Can I keep it project-only? A: Yes. Add
--workspace(for example./install.sh claude --workspace) so the skills go under.claude/skillsin the current repo.
Sources
- github.com/Aclguh/codebase-audit-and-improve
- github.com/Aclguh/codebase-audit-and-improve/blob/11b20647301a50a8063ea6f4e102a5a81130cb8a/README.md
- github.com/Aclguh/codebase-audit-and-improve/blob/11b20647301a50a8063ea6f4e102a5a81130cb8a/install.sh
- github.com/Aclguh/codebase-audit-and-improve/blob/11b20647301a50a8063ea6f4e102a5a81130cb8a/skills/improve-all/SKILL.md
- github.com/Aclguh/codebase-audit-and-improve/blob/11b20647301a50a8063ea6f4e102a5a81130cb8a/scripts/check_health.py