Content
92%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
An exemplarily lean, well-organized instruction skill that assumes Claude's competence and adds only genuinely non-obvious guidance. The single gap is the absence of a good-vs-bad comment example to make the WHY-not-WHAT rule concrete.
Suggestions
Add a two-line good-vs-bad example contrasting a WHAT comment ('// increment i by 2') with a WHY comment ('// step by 2: column pairs share a row') to make the core rule copy-paste concrete.
Include one short example of a well-formed TODO or FIXME tag showing the expected owner/date/note format, so the tag guidance is directly executable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Twelve lean lines with zero padding: every token adds non-obvious guidance ('Comment WHY, not WHAT', 'delete it; git has the history') and nothing explains concepts Claude already knows. | 5 / 5 |
Actionability | Concrete, specific instruction-only guidance — 'rename instead of commenting', an explicit do-comment list, and per-tag semantics like 'HACK … say why and when it can go' — but no worked example contrasting a WHY comment against a WHAT comment, which is the skill's core instruction. | 4 / 5 |
Workflow Clarity | A single, unambiguous action for a simple skill under 50 lines, so the simple-skill exception applies; there are no destructive or batch operations that would demand validation checkpoints. | 5 / 5 |
Progressive Disclosure | Under 50 lines with no need for external references, and the content is well organized into clear sections (intro, Annotation Tags, Never), satisfying the simple-skill exception for a 5. | 5 / 5 |
Total | 19 / 20 Passed |