Content
67%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-structured, genuinely actionable conventions skill with clear decision rules, checklists, and a validation philosophy. Its main costs are redundancy: the description-length ceiling is repeated across three sections, and the Canonical guidelines section restates upstream best practices that add tokens without adding repo-local value.
Suggestions
Consolidate the 1024-char ceiling guidance into a single section: it is currently explained in Token economy, When to refactor a description, and Canonical guidelines, with overlapping restatements of the do-not-trim-preemptively rule.
Replace the Canonical guidelines section's restatement of upstream best practices with a brief link plus only the repo-specific deltas, since Claude and the linked document already know the canonical content.
Provide a concrete command for measuring the folded description length (e.g., a short YAML round-trip one-liner) so the 'measure, do not eyeball' rule is directly executable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient, rule-dense prose that assumes competence, but it includes avoidable repetition: the 1024-char ceiling is stated three times (Token economy, When to refactor a description, Canonical guidelines), and the Canonical guidelines section restates upstream Anthropic best practices (hard limits, progressive-disclosure tiers) that the linked document and Claude's own knowledge already cover. This matches the 'mostly efficient but could be tightened' anchor rather than the minor-trim anchor at 4. | 3 / 5 |
Actionability | Concrete, executable guidance throughout: wrap at 100 characters, ASCII only, only `name` and `description` keys, use the `>-` folded scalar with a copy-paste YAML example, an annotated WHAT/WHEN example, and a validation procedure ('prompt a Coding Agent... with a trigger phrase'). It stops short of 5 because 'measure it before saving' the folded description length never provides an actual command or method to do the measurement. | 4 / 5 |
Workflow Clarity | The edit workflow is clearly sequenced with checkpoints: apply conventions on every edit, the After-Editing checklist explicitly requires deciding add/remove/tighten triggers and 'State explicitly that no change is needed... Do not skip the check silently', and the Validating section defines a post-change verification step. Minor gap: the validation step is described abstractly (no concrete prompt example or pass/fail criteria) rather than as an explicit feedback loop, so it sits at 4 rather than 5. | 4 / 5 |
Progressive Disclosure | A single well-sectioned SKILL.md (~180 lines, well under its own 500-line guidance) with no bundle files and no nested references, which is appropriate for always-apply conventions. It is not a 5 because the Canonical guidelines section duplicates upstream documentation that could be reduced to a short pointer, the one minor organization gap in an otherwise clean structure. | 4 / 5 |
Total | 15 / 20 Passed |