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
Install
npx skills add iamneilroberts/claude-skills --skill comment-refactorgit 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-refactorPersonal 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
Details
- Skill name
comment-refactor- Repository
- iamneilroberts/claude-skills
- 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
37iamneilroberts/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
Branch
37iamneilroberts/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".
Claude Code Best Practices
37iamneilroberts/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.
Crisp
37iamneilroberts/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.
Codex Review
37iamneilroberts/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
Session End
37iamneilroberts/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".
Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.