Skip to content

About

Claude Code skill that strips AI slop from a codebase and adds the comments a human team would have written. Atomic commits, gated on tests + typecheck + build, auto-rollback on red.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

humanize-code

A Claude Code skill that audits a codebase the way a careful senior engineer would. It strips the AI-slop patterns bulk-generated code leaves behind, then adds the comments a human team would have written. Every change lands as its own atomic git commit, gated on tests, typecheck, and build all staying green. Anything that turns the baseline red rolls back automatically.

Built for the moment after AI generates a lot of code and a human has to maintain it.

Why this exists

LLM-generated code carries a recognizable signature: comments restating what the code obviously does, single-use abstractions, wrapper functions that just delegate, type theater, speculative else if branches that can't fire, dead exports, copy-pasted blocks, 5-line try/catches around 1-line operations that can't throw, stale console.log calls, and the same concept named four different ways across the codebase.

None of these break the code. All of them slow down the human who inherits it. A human team's code reads differently: terse, consistent, commented where the why isn't obvious from the what.

This skill closes the gap, carefully.

What it does

The skill runs in two passes over your repo:

Pass A: Remove slop. Walks 17 documented patterns ranging from "stale debug logs" (safe) to "repeated 4-10 line blocks across files" (risky). Findings are tiered T1 / T2 / T3 by how invasive the fix is. Safer fixes land first.

Pass B: Add human comments. Finds 11 categories of places that deserve a comment a human would have written: docstrings on public API, why notes on magic numbers, justifications on @ts-ignore / eslint-disable / # type: ignore, context on workarounds, ordering constraints, perf and concurrency notes, file headers. Every comment's why must come from git history, callers, tests, types, or you. It is never invented.

A one-time conventions interview on first run captures your codebase's naming, error handling, file layout, config location, and comment style. The answers get written to team-conventions.md at your repo root and become the canonical reference for every subsequent run. The interview uses plain English with real examples pulled from your code, so it works for users who aren't fluent in camelCase and JSDoc.

The safety contract

The whole skill is built around one promise: it will not break your code.

  • Before any change, the skill runs your test + typecheck + build commands. If any are red, it stops and reports. It never refactors on top of a broken baseline.
  • Every approved finding becomes its own atomic git commit (humanize: <description>).
  • After every commit, the safety gate runs again. If anything goes red, the commit is git reset --hard HEAD~1'd immediately. The failure gets logged and the skill moves on.
  • Three consecutive rollbacks halts the run. That's the canary for hidden coupling or flaky tests; pushing through is reckless.
  • The skill never git pushes. Pushes are your call.

The atomic-commit + verify + rollback loop is enforced by scripts/safe_apply.sh, not by instructions Claude could miss.

Install

Skills are markdown files Claude Code reads from a known location. Install this one by cloning it into your skills directory.

Personal install (available in every Claude Code session):

git clone https://github.com/jIrwinCline/humanize-code.git ~/.claude/skills/humanize-code

Project install (only available in this project):

git clone https://github.com/jIrwinCline/humanize-code.git .claude/skills/humanize-code

Either location works. Personal is right for most people; project install makes sense when you want different teams sharing the same skill via the repo.

Usage

Once installed, invoke it from a Claude Code session by asking in plain English. The skill is designed to trigger on phrases like:

  • "humanize this codebase"
  • "deslop this code"
  • "this looks AI-written, clean it up"
  • "audit for AI slop"
  • "make this look like a team wrote it"
  • "add docstrings explaining what this code does and why"
  • "find repeated patterns"

You can also run just one pass if you want:

  • "run the slop audit only, skip the comment pass"
  • "skip the slop audit, just add the missing comments"

The first invocation in a fresh repo runs the conventions interview (7 plain-English questions, ~5 minutes). Subsequent invocations skip the interview and read your team-conventions.md.

What gets written to your repo

The skill produces five files in the repo it audits, plus git commits:

File Purpose
team-conventions.md Your codebase's persistent memory of naming, error handling, layout, config, and comment style. Written once during the first-run interview. Read by every subsequent run.
slop-audit.md Ranked list of removal findings from Pass A.
slop-applied.md Log of what got applied and what rolled back, with commit SHAs.
comments-audit.md Ranked list of comment-addition candidates from Pass B, split into ready (the why was derivable) and needs_input (the skill needs you to supply the reason).
comments-applied.md Log of comment additions, with commit SHAs.

Every commit the skill creates is prefixed humanize: so you can audit the full set in one view:

git log --grep="humanize:" --oneline

Project structure

humanize-code/
├── SKILL.md                       # the skill manifest (what Claude reads)
├── README.md                      # you are here
├── LICENSE                        # MIT
├── references/
│   ├── slop-patterns.md          # Pass A catalog: 17 removal patterns with before/after
│   ├── comment-additions.md      # Pass B catalog: 11 comment candidates with before/after
│   ├── conventions-interview.md  # the plain-English conventions interview script
│   ├── team-conventions-template.md  # the template written to `team-conventions.md`
│   └── stack-detection.md        # per-language probe order for test/typecheck/build commands
└── scripts/
    └── safe_apply.sh              # atomic commit + verify + rollback (the safety contract)

Supported stacks

The skill auto-detects test, typecheck, and build commands for:

  • JavaScript / TypeScript (npm, pnpm, yarn, bun)
  • Python (pytest, mypy / pyright, poetry / pdm / hatch / uv)
  • Rust (cargo)
  • Go (go test / vet / build)
  • Ruby (bundle, sorbet)
  • Java / Kotlin (Maven, Gradle)

For anything else, the skill asks you which commands to use and records them. See references/stack-detection.md for full probe order.

If your repo has no test suite at all, the skill warns loudly and restricts itself to safe rename / dead-code-removal changes only. Structural refactors without a test gate are reckless.

Sibling skills worth knowing

  • stop-slop — the prose equivalent of this skill, for AI-sounding writing
  • improve-codebase-architecture — when the answer is a structural RFC rather than tactical cleanup; this skill redirects you there for findings that really want a deeper rethink

A note on philosophy

The skill is deliberately not aggressive. It proposes, you approve, then it applies. It will not normalize naming conventions or pick error-handling styles unless you've told it which one wins (via the conventions interview). It will not invent the why behind a piece of code. It will not make incidental "improvements" to adjacent code while fixing a finding.

A wrong comment is worse than no comment. A "clever" refactor that breaks the build is worse than the original mess. The skill is built to be the careful senior engineer in your repo, not the eager intern.

License

MIT. See LICENSE.

About

Claude Code skill that strips AI slop from a codebase and adds the comments a human team would have written. Atomic commits, gated on tests + typecheck + build, auto-rollback on red.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages