Content
75%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.
A well-crafted, instruction-only conventions skill: concrete limits, explicit decision checklists, save-gates with error recovery, and a genuine behavioral validation procedure. It stays lean for its scope and correctly encodes the SKILL.md vs references/ split policy, though it carries some deliberate self-restatement, lacks an executable method for its own 'measure the description' mandate, and inlines a re-summary of upstream guidance.
Suggestions
Provide an executable way to measure the folded description length (e.g., a short shell/python one-liner or a `scripts/measure_description.py` helper) instead of the abstract instruction 'count the length of the single string YAML produces'.
Trim the self-restatements: state the 1024-char hard ceiling once (the 'Canonical guidelines' section already cross-references 'Token economy', so the duplicate limit statement can be reduced to the cross-reference), and drop the 'Do not refactor pre-emptively' paragraph that repeats the preceding bullet's 'only length-based trigger' rule.
Move the upstream 'Canonical guidelines (Anthropic)' highlights summary into a `references/upstream-guidelines.md` file and keep a one-line pointer plus the link in SKILL.md, since the body's own policy is to push verbose material to references.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is rule-dense and assumes Claude's competence (no basic-concept explanations), but has minor over-explanation that could be trimmed: the em-dash section restates the ASCII rule ('This line restates it because they slip in through copy-paste'), the 1024-char limit appears in both 'Token economy' and 'Canonical guidelines' (with an explicit cross-reference), the upstream best-practices link appears twice, and the 'Do not refactor pre-emptively' paragraph restates the preceding bullet. This fits anchor 4 ('efficient; minor instances of over-explanation that could be trimmed') rather than 3 because each restatement is deliberate and explicitly justified in the text, and rather than 5 because the duplication is real token cost. | 4 / 5 |
Actionability | Concrete, executable rules throughout: 'Wrap markdown at **100 characters**', 'Only `name` and `description` fields', 'Use the YAML folded block scalar (`>-`)' with a yaml example, 'confirm it is under 1024', 'leave its file untouched' for vendored `humanizer`, and a validation procedure naming a fresh subagent on `opus` prompted with a trigger phrase. This fits anchor 4 ('mostly executable guidance... with minor gaps'); it is not 5 because some actions lack an executable method — 'measure it before saving: count the length of the single string YAML produces' gives no command (e.g., a one-liner) to actually measure, and the trigger-coverage test offers no concrete procedure. | 4 / 5 |
Workflow Clarity | The editorial workflows carry explicit checkpoints and feedback loops: the after-edit checklist ('Add triggers... Remove triggers... Tighten triggers... State explicitly that no change is needed'), the save gate ('A description that reaches 1024 chars is a broken skill. Do not save it; summarize or cut triggers until it fits'), and validation ('prompt a Coding Agent... with a trigger phrase, and confirm the skill loads'). This is anchor 4 ('clear sequence with most checkpoints present; minor validation gaps'); it is not 5 because the document is a distributed conventions reference rather than one coherent end-to-end sequence, and the non-editorial sections (markdown style, frontmatter, vendored skills) are rules without sequence. | 4 / 5 |
Progressive Disclosure | The body (~173 lines) is well under the ~500-line ceiling, self-contained with clear section headers, and explicitly encodes the split policy ('Push to `references/<topic>.md`: Setup, install, troubleshooting...'). No bundle files exist (no `references/`, `scripts/`, or `assets/`), so scoring follows the body's own structure: anchor 4 ('good structure; most content is appropriately placed; minor organization gaps'). It is not 5 because the 'Canonical guidelines (Anthropic)' section re-summarizes upstream material that could itself live in a reference file, and not 3 because nothing large is wrongly inlined and navigation by section is easy. | 4 / 5 |
Total | 16 / 20 Passed |