The standard
~/.claude/rules/comments.md decides what earns a comment. It is the only
copy. Read it before editing a file and apply it as written.
Do not restate it here, and do not work from memory of it. A subagent running
this skill may not have it loaded, so read the file. If a case it does not
cover comes up, the fix belongs in comments.md, not in this skill.
Deleting a load-bearing directive is the one unrecoverable mistake this skill
can make. Leave these alone: //go:build, // +build, //go:generate,
// prettier-ignore, # fmt:, # -*- coding:, shebangs.
Suppressions are not on that list. @ts-ignore, eslint-disable,
# type: ignore, //nolint are debt under comments.md § Suppressions.
Report them and say what each is silencing. Never delete one in this pass:
removing a suppression breaks the build or the lint run, which is a code
change, and this skill does not make those.
Quick start
Run on staged files before a commit:
/clean-comments
Run on specific files:
/clean-comments src/foo.ts src/bar.go
Workflow
- Read
~/.claude/rules/comments.md - If arguments are provided, treat them as file paths to clean
- If no arguments, get staged files:
git diff --cached --name-only --diff-filter=ACM - Filter to code files (
.go,.ts,.tsx,.js,.jsx,.py,.rs) - For each file, read it, remove the comments that fail the standard, write it back
- Re-stage any modified files:
git add <file> - Report what was removed and from which files; if nothing needed removing, say so
Comment-only edits. Never change code in the same pass.
The commit hook
~/.claude/hooks/check-staged-comments.sh runs on PreToolUse for Bash and
blocks git commit when the staged diff adds comment lines. It ignores
directives, and reads # as a comment marker in Python only.
Trimming a long doc comment counts as adding lines, so a cleanup pass trips it. When every remaining comment earns its place, say so and commit with:
CC_COMMENTS_REVIEWED=1 git commit ...