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.
The body is a well-structured principles reference with genuinely actionable decision rules (especially the IF/THEN reference-verification and security sections) and a properly signaled one-level reference to security-checks.md. The main quality drag is redundancy — several bullets restate the same rule two or three times, inflating token cost without adding guidance — plus a lack of illustrative examples for the more abstract principles.
Suggestions
Deduplicate the repeated bullets: merge the two naming bullets in Readability, the two early-return bullets in Function Organization, the three 'When to Optimize' bullets into one, and the overlapping extract-a-function rules in Single Responsibility.
Add one short good/bad code illustration for the most abstract principles (single responsibility, naming) so the guidance is concrete rather than directive-only.
Consider moving the commenting and performance sections (or the security defaults list) into a reference file like security-checks.md to shorten the always-loaded SKILL.md body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with judgment-oriented rules rather than basics Claude already knows, but it contains multiple near-duplicate bullet pairs: "Use meaningful, descriptive names" vs "Use descriptive names", "Use early returns to reduce nesting" vs the next bullet repeating it, and three separate bullets in 'When to Optimize' restating "only after measurable bottlenecks are identified". Mostly efficient but clearly could be tightened by deduplication. | 3 / 5 |
Actionability | For an instruction-only skill, the guidance is largely concrete and executable: "Mask or exclude passwords, tokens, PII from logs", "Extract magic numbers and strings into named constants", "Inject external dependencies as parameters", plus explicit IF/THEN decision rules in 'Verifying References Before Adoption'. Not a 5 because many core bullets remain abstract directives ("Each function should do one thing well", "Keep the codebase lean and focused") with no illustrative good/bad examples. | 4 / 5 |
Workflow Clarity | This is a principles reference with no multi-step process to sequence, and no destructive or batch operations that would require validation checkpoints, so the cap does not apply. Sections are well-organized by topic with a consistent rule format, making application unambiguous in most areas. Not a 5 because some sections interleave overlapping rules (readability, function design, refactoring triggers repeat each other) without a clear precedence for which rule governs a given decision. | 4 / 5 |
Progressive Disclosure | The bundle reference is real (references/security-checks.md exists), one level deep, and clearly signaled at the end of the Security Principles section ("For concrete detection patterns used by security review, see references/security-checks.md") — a good split of concrete detection patterns out of the overview. Not a 5 because the ~170-line body inlines several large sections (commenting principles, performance, error handling) that could arguably live in references, and only one reference file exists. | 4 / 5 |
Total | 15 / 20 Passed |