rebirth-code-cleanup

rebirth-code-cleanup

Like a phoenix rising from the ashes: messy code goes in, clean code comes out.

An Agent Skill that turns a messy codebase, AI-generated or human-written, into clean, linted, well-commented, easy-to-read code without changing what it does.

It works in any folder and with any language, including Markdown and plain text. It runs in Claude Code and any other agent that supports the open Agent Skills format.

The goal: anyone who opens a cleaned-up file should know what they're walking into, and be able to start hand-coding right away.

What it does

1. Understands the project: reads your docs, config, and CI files, and learns your conventions.
2. Audits it: finds noise, dead code, duplication, confusing names, over-engineering, and the habits typical of AI-written code.
3. Plans: shows a ranked plan in small batches and waits for your OK.
4. Cleans up in batches: formatting, lint fixes, dead code, naming, simplification, and (if you choose) restructuring.
5. Comments well: a short purpose header on each file, doc comments on public code, and "why" comments where the reason isn't obvious. It also removes comments that only repeat the code.
6. Verifies: after every batch it runs your existing linter, formatter, type checker, and tests, then saves the batch as its own git commit.
7. Reports: writes CLEANUP_REPORT.md with before/after numbers, real before-and-after examples explained in plain language, and an honest list of anything it couldn't verify.

What to expect

It asks up to four simple questions, all at once, each with a default:

Then it creates a cleanup/<date> branch, shows the plan, cleans in batches with one commit each, and writes the report. You can undo any single batch with git revert, or drop the whole branch.

If your project has no linter, it suggests the standard one for your language as a step in the plan. Nothing gets installed unless you approve the plan.

Use it if

• AI-generated code has piled up and become hard to follow
• you inherited a legacy or "it works, don't touch it" codebase
• you're about to hand a project to someone else, or bring new people onto it
• your project has no linter or formatter, or nobody follows the one it has
• your docs or Markdown files are messy and inconsistent

Don't use it if

• you need a production hotfix right now. Fix the bug first, clean up later.
• you want new features, bug fixes, or speedups. This skill deliberately keeps behavior the same.
• the project is tiny or throwaway. It isn't worth the time.
• the code is about to be deleted or rewritten. Cleaning it is wasted effort.
• it's mostly generated code. Regenerate it instead.
• the code is critical and has no tests. The skill will still work, but it warns you and stays conservative, because without tests it can't fully prove nothing changed.

What it never touches

The skill is told never to open, read, edit, move, or delete these:

• .env and every .env.* file, including .env.example, .env.sample, and .env.template, unless you name that exact file and ask it to edit it
• keys and certificates (*.pem, *.key, *.p12, *.pfx, id_rsa*, ...)
• credential files (secrets.*, credentials.*, .npmrc, .pypirc, .netrc, .git-credentials)
• the folders .ssh/, .aws/, .gnupg/, .azure/, .kube/, .docker/

It also never edits dependencies (node_modules/, vendor/, ...), build output, generated or minified files, lock files, binary files, or anything in .gitignore.

If it finds a password or key typed directly into your code, it reports only the file and line, never the value, and recommends replacing it with a new one.

It also never weakens your safety checks: no changing lint rules, no hiding errors with ignore comments, and no editing or skipping tests to make them pass.

Security recommendation

My personal recommendation: set up blockers in your agent for secret files instead of letting your AI agent roam freely, especially when running cleanup skills like this one, which touch many files. The skill's own rules are instructions to the AI. A block in your agent's settings is enforced by the tool itself.

For Claude Code, add this to .claude/settings.json in your project, or to ~/.claude/settings.json for all projects:

{
  "permissions": {
    "deny": [
      "Read(**/.env)",
      "Read(**/.env.*)",
      "Edit(**/.env)",
      "Edit(**/.env.*)",
      "Read(**/*.pem)",
      "Read(**/*.key)",
      "Read(**/secrets/**)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)"
    ]
  }
}

These rules block Claude Code's file tools. Shell commands such as cat .env are a separate route, so for full protection also turn on Claude Code's sandbox mode. Other agents have similar ignore or deny settings; check your agent's documentation.

Install

skills.sh (any compatible agent):

npx skills add TheWirelessPhoenix/rebirth-code-cleanup

Claude Code plugin:

/plugin marketplace add TheWirelessPhoenix/rebirth-code-cleanup
/plugin install rebirth-code-cleanup@rebirth-code-cleanup

Manual: copy skills/rebirth-code-cleanup/ into ~/.claude/skills/, or into your agent's skills folder.

Usage

Ask in plain words, or call it by name:

• "Clean up this codebase"
• "Tidy the src/api folder, light comments, show me the plan first"
• /rebirth-code-cleanup (on its own, or as /rebirth-code-cleanup:rebirth-code-cleanup when installed as a plugin)

What's inside

skills/rebirth-code-cleanup/
  SKILL.md                          the workflow and hard rules
  references/
    ai-code-smells.md               audit checklist
    comment-guide.md                commenting standard for levels 1-3
    language-tooling.md             linters and formatters per language
  assets/
    cleanup-report-template.md      CLEANUP_REPORT.md layout
    project-guide-template.md       newcomer guide layout

The skill is plain Markdown with no scripts, so it works in any agent without Python or Node installed. It uses your project's own tools.

Limitations

• It can only prove behavior stayed the same as far as your tests cover. Fewer tests means less certainty, and the report says so.
• On large projects it starts with the messiest files instead of doing everything in one run.
• AI judgment can still be wrong. Review the branch before merging.

License

MIT