A Claude Skill that writes code comments explaining why, not what — and never deletes an existing comment without asking.
Install
claude.ai — download quality-comments.zip below, then upload it at Settings → Capabilities → Skills.
Claude Code — copy the quality-comments/ folder to ~/.claude/skills/ for all projects, or to .claude/skills/ inside a repo to share it with anyone who clones.
What's in it
- Comments that carry information — the test is whether deleting one loses anything
- Interface contracts kept separate from implementation rationale
- Structured task tags:
TODO(owner): active verb [TICKET-123], plusFIXME,HACK,NOTE,PERF,SAFETY - Cleanup that categorizes, proposes, and asks — never edits first
- Functional directives (
# noqa,//go:build, shebangs,#pragma) treated as code, not prose - Conventions for 11 languages: Python, TypeScript/JavaScript, Go, Rust, Java, C#, C/C++, Swift, Ruby, PHP, shell
Evaluated against baseline
Five test cases run with and without the skill. Assertions were classified as discriminating or baseline-likely before the runs, because the aggregate otherwise overstates the result.
Discriminating assertions: 24/24 with skill, 16/24 baseline.
All assertions: 39/39 with skill, 30/39 baseline.
Clearest single result: given an over-commented file and the instruction "clean it up," baseline rewrote it 104 lines → 53 with no confirmation, deleting two functional directives. The skill left the file byte-identical and returned a categorized proposal ending in a question.
Two evals tied at 100% on both arms. Those are left in as regression guards and reported as null results — the skill wins on structure and consent, and ties when the task is simply "write good documentation on request."
Full numbers, both null results, three grader bugs, and a defect the evaluation caught and fixed: evals/RESULTS.md.
Follows the Agent Skills open standard. MIT licensed.