A Claude Skill that writes code comments explaining why, not what, and never deletes an existing comment without asking.
Language models over-comment. The default failure looks like this:
// increment the counter
counter++;
// loop through the users
for (const user of users) {Every line restates the line below it. It takes longer to read than the code it describes, and it trains people to skip comments entirely, so the one comment that actually mattered gets skipped too.
This skill produces the other thing:
// API is 1-indexed; the off-by-one here is intentional
counter++;
// Sorted by lastSeen, not id — the dashboard depends on this order
for (const user of users) {Writes comments that carry information. The test is whether deleting the comment loses anything. A comment that restates its line at the same altitude is noise; one that summarizes twenty lines, or records a constraint the code can't express, is not.
Separates contracts from rationale. Doc comments on a declaration define what a caller needs — parameter units and ranges, return semantics, error conditions, side effects. Inline comments explain non-obvious decisions to whoever maintains it. Different audiences, different rules.
Structures task tags. TODO(owner): active verb [TICKET-123], with FIXME, HACK, NOTE, PERF, and SAFETY for the rest. An owner and a ticket are what make a tag assignable and greppable instead of a note to nobody.
Cleans up without deleting. Given an over-commented file, it categorizes what it would remove, shows the proposed result, and asks. It never edits the file first. Functional directives — shebangs, # noqa, //go:build, #pragma — are treated as code, not prose.
Eleven languages have documented conventions: Python, TypeScript/JavaScript, Go, Rust, Java, C#, C/C++, Swift, Ruby, PHP, and shell.
Claude Code — personal, all projects
cp -r quality-comments ~/.claude/skills/Claude Code — project-scoped, shared via the repo
cp -r quality-comments .claude/skills/Anyone who clones the project gets the skill.
claude.ai
Zip the quality-comments/ folder — the folder must be the zip root, not nested inside another directory — then go to Settings → Capabilities → Skills and upload it. A pre-built .zip bundle is attached to each release.
Note that Cowork and cloud sessions load the skills enabled on your claude.ai account, not ~/.claude/skills/ on your machine. If you use both surfaces, install in both places.
Follows the Agent Skills open standard.
Worth being direct about this, because the evaluation makes it clear.
The skill wins where it imposes structure and where it governs consent — task tag format, and the flag-before-delete cleanup workflow. Those are real, measurable gains over baseline.
It ties whenever the task is simply "write good documentation on request." Asked to document a Go function properly, default Claude already produces a strong contract; the skill matched it and didn't beat it, across two rounds and two different assertion sets. The same held for a regression test on load-bearing constraints.
So: this is worth installing if you want comment discipline applied consistently without asking for it, and especially if you want cleanup that can't quietly destroy information. It is not going to make Claude think better about documentation it was already asked to write carefully.
Five test cases, run with and without the skill, graded against pre-registered assertions. Assertions were classified as discriminating or baseline-likely before the runs, because the aggregate number otherwise reads as a much bigger win than the skill earns.
| With skill | Baseline | |
|---|---|---|
| Discriminating assertions | 24/24 | 16/24 |
| All assertions | 39/39 | 30/39 |
The cleanest single result: given an over-commented file and the instruction "clean it up", baseline rewrote it from 104 lines to 53 with no confirmation, deleting two functional directives on the way. The skill left the file byte-identical and returned a categorized proposal ending in a question.
Full numbers, both null results, three grader bugs, and a defect the evaluation caught and fixed are in evals/RESULTS.md.
quality-comments/ the skill — this is what you zip or copy
├── SKILL.md
└── references/
├── languages.md
└── cleanup-workflow.md
evals/ test cases, fixture, grading, results
MIT — see LICENSE.