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 conventions skill: imperative, repo-specific rules with concrete bad/good code examples, no filler library comparisons, and clean section organization in a single self-contained file. Weakest spots are mild conceptual padding in section intros, one truncated code example, and content long enough that example material could be split into reference files.
Suggestions
Trim the conceptual intro sentences ("TypeScript's type system is most valuable when it catches bugs at compile time rather than runtime", "Self-documenting names eliminate mental parsing for the next reader") — Claude already knows these; the rules and examples stand on their own.
Complete the truncated fetchSpans example (add the function body or close the signature) or reduce it to just the JSDoc + destructuring pattern it exists to illustrate.
At ~118 lines, consider moving the longer worked examples (the zoomOut defaults example, the bad/good naming pairs) into a references/ file, keeping SKILL.md as the rules overview with clearly signaled one-level-deep links.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with repo-specific rules and bad/good code pairs that earn their tokens, but a few sentences explain concepts Claude already knows — e.g. "TypeScript's type system is most valuable when it catches bugs at compile time rather than runtime" and "Self-documenting names eliminate mental parsing for the next reader". Not a 5 because those trimmable rationale sentences and the ~30-line zoomOut example add mild padding; not a 3 because the vast majority of lines are non-inferable repo conventions. | 4 / 5 |
Actionability | Guidance is highly concrete and executable: imperative rules ("Variables must not use single letters", "Import lodash utilities via path imports", "Use Partial<Record<K, V>> for sparse maps") paired with complete bad/good code examples. Not a 5 because the fetchSpans snippet is truncated mid-function (no body or closing brace) and "check sibling packages for existing utilities" gives no concrete discovery step. | 4 / 5 |
Workflow Clarity | The application sequence is clear: "Before writing new code, explore the directory you're working in to understand existing patterns — then follow these rules", reinforced by the Reuse section's check-before-writing guidance. No validation checkpoints are present, but this is a conventions-consultation skill with no destructive or batch operations, so the anchor-4 fit (clear sequence, minor checkpoint gaps) is better than anchor 3, which requires genuinely ambiguous or poorly defined steps. | 4 / 5 |
Progressive Disclosure | No bundle directories (references/, scripts/, assets/) exist, and the skill is a self-contained ~118-line document with clear section headers (Naming, Functions, Type Safety, Imports, Reuse) and a framing intro. The guideline's automatic 5 is reserved for skills under 50 lines; at this length the good/bad example blocks and the zoomOut reference example could arguably live in a reference file, so anchor 4 (good structure, most content appropriately placed) is the best fit. | 4 / 5 |
Total | 16 / 20 Passed |