Comment Refactor

Refactor the comments in AI-generated (or long-lived) code — strip the accumulation of fix-history narration, obsolete explanations, and code-restating noise while preserving load-bearing WHY/TODO/warning comments. Works over a path, glob, or the whole repo; skips dead/abandoned/unused and vendored/generated files; and stamps each cleaned file with a content-hash marker so re-runs skip files that haven't changed. Incorporates the /remove-comments and /deslop (humanizer) heuristics plus a used-code filter and incremental idempotency. Triggers on `/comment-refactor [path|glob]`, "refactor the co

37 stars 7 forksSoftware Development

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add iamneilroberts/claude-skills --skill comment-refactor
Manual install
git clone --depth 1 https://github.com/iamneilroberts/claude-skills.git /tmp/claude-skills
mkdir -p ~/.claude/skills
cp -r /tmp/claude-skills/skills/comment-refactor ~/.claude/skills/comment-refactor

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# /comment-refactor — clean comment cruft, incrementally, across a codebase

Comments in AI-assisted code accumulate: fix-history narration (`// changed to X because the old
way broke`), stale explanations that no longer match the code, and line-by-line restating of what
the code plainly does. This skill removes that layer while keeping the comments that carry real
information, across many files, and **only re-touches files that changed since their last pass**.

It composes three things:
1. the `/remove-comments` keep/remove judgment (the engine),
2. the `/deslop` → **humanizer** pass applied to comment *prose* (AI-tell removal inside the
   comments that survive), and
3. two mods you asked for: a **used-code filter** (skip dead/abandoned/unused + vendored/generated
   files) and an **incremental content-hash marker** (skip files already up to date).

## Bundled helpers

- `marker.py` — the idempotency control marker. `check <file>` (exit 0 = up-to-date/skip, 10 =
  process), `stamp <file>` (write/refresh the marker), `hash <file>`. The marker is
  `@comment-refactor:v1:<sha256(body-without-marker)[:16]>` in the file's own comment syntax,
  placed at the top (after a shebang). Excluding the marker line from the hash makes re-stamping
  stable; any real edit changes the hash and forces a reprocess.
- `scan.sh [path|glob …]` — prints the mechanical worklist (`PROCESS <file>` / `SKIP-UPTODATE
Read the full skill on GitHub

Details

Skill name
comment-refactor
Path
skills/comment-refactor/SKILL.md
Repo updated
21 August 2026

FAQ

What does the Comment Refactor skill do?

Refactor the comments in AI-generated (or long-lived) code — strip the accumulation of fix-history narration, obsolete explanations, and code-restating noise while preserving load-bearing WHY/TODO/warning comments. Works over a path, glob, or the whole repo; skips dead/abandoned/unused and vendored/generated files; and stamps each cleaned file with a content-hash marker so re-runs skip files that haven't changed. Incorporates the /remove-comments and /deslop (humanizer) heuristics plus a used-code filter and incremental idempotency. Triggers on `/comment-refactor [path|glob]`, "refactor the co

How do I install the Comment Refactor skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add iamneilroberts/claude-skills --skill comment-refactor. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Comment Refactor popular?

It lives in iamneilroberts/claude-skills, which has 37 GitHub stars and 7 forks.

Related skills

Brag

37

iamneilroberts/claude-skills

Memorialize something you just built by generating a self-contained "showcase" page for it — a persuasive, good-looking deep dive: what it is, why it's impressive, how it works — with a screenshot if one can be found or captured, and links to related showcase pages. This is the sales/hype-leaning counterpart to /write-post (which drafts a neutral, no-BS technical post); reach for /brag when you want it to sell. Fast by design, like /idea: ask only what's needed, build the page, don't turn it into a project. Triggers on `/brag <subject>`, "brag about this", "make a showcase page for X", "write

Writing & Content

Branch

37

iamneilroberts/claude-skills

Create an isolated git worktree for a task and log it to a shared work journal, so multiple Claude Code sessions run in parallel without racing on HEAD, uncommitted edits, or the index. Subcommands: `list`, `done <slug>`, `update` (heartbeat), `coord <message>` / `coord clear <slug>` (cross-session constraints). Triggers on `/branch`, "start in a worktree", "isolate this work", "parallel session", "heartbeat the journal".

Git & Code Review

Claude Code Best Practices

37

iamneilroberts/claude-skills

Use when asked about Claude Code workflow, prompt caching cost, session economics, CLAUDE.md hygiene, context-window management, plan mode, permission modes, hooks, skills, subagents, checkpointing/rewind, parallel sessions, worktrees, headless/CI usage, the Agent SDK, slash commands, MCP configuration, or "what's the right way to use Claude Code for X". Also use proactively BEFORE suggesting /model, /compact, fast-mode toggle, or editing CLAUDE.md mid-session, since those bust the system cache.

AI, LLMs & Agents

Crisp

37

iamneilroberts/claude-skills

Use this skill when the user wants shorter, more direct responses. Activate on: "crisp mode", "go crisp", "/crisp", "be brief", "less tokens", "cut the fluff", "shorter answers", "stop being verbose", "drop the filler", "skip the pleasantries", "no fluff", "just the answer". Do NOT activate for: "explain in detail", "walk me through", "full report", or any question answerable correctly in one sentence without the skill.

Software Development

Codex Review

37

iamneilroberts/claude-skills

Get a second opinion on the current change or a plan from a different model (Codex), and enforce its verdict mechanically. Codex returns a structured JSON verdict — findings scored by priority (0 critical, 1 important, 2 minor, 3 nit) against sev.schema.json — and a gate script turns that into a pass/fail exit code, so a critical or important finding gets fixed or escalated rather than re-argued by the model that wrote the code. Infra failures (rate limit, model reject, empty output) are their own outcome and never count as a clean pass. Use after writing tests, before a deploy or merge, or to

Software Development

Session End

37

iamneilroberts/claude-skills

Wrap up a coding session — run a right-sized end-of-session self-critique, optionally curator-verify the claims, prepend a SESSION_LOG.md entry, and print a rename + counter summary. Use before you /clear or stop for the day. Triggers on `/session-end`, "end this session", "wrap up and log what we did".

Software Development

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.