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.git
cd codebase-audit-and-improve
chmod +x install.sh && ./install.sh claude

How 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

Other assistants

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.

Test level

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-all also pushes, opens a pull request on a protected branch and fixes CI failures by itself. Run /improve if 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/skills in 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