Content
60%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 presents a clear, well-sequenced review workflow with concrete finding specs and severity criteria, and it correctly delegates detailed rules to one-level-deep reference files. However, the entire referenced bundle (11 rules/*.md files and templates/review-report.md) is missing, so the skill's core analysis content and report format are unreachable as shipped, and roughly a third of the body restates CLI basics Claude already knows.
Suggestions
Ship the referenced bundle files: all 11 rules/*.md files and templates/review-report.md are cited in the body but absent from the bundle, leaving Phases 2 and 3 unexecutable — either include them or inline the essential rules into SKILL.md.
Trim the 'Key Principles (Quick Reference)' section: standard flags (-h/--help, --version), exit codes (0/1/2/126/127/130), and the stdout/stderr split are knowledge Claude already has — keep only the skill-specific judgments (severity criteria, safety hierarchy, response-time policy for when to flag a violation) and move the rest into a rules file.
Include one worked example finding (cited line, named principle, severity, and a code fix) directly in the body so the expected output shape is reproducible even when the report template file is unavailable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The workflow sections are tight, but the 'Key Principles (Quick Reference)' section (~30 of ~107 lines) restates concepts Claude already knows: '### Standard Flags (Always Support) - -h, --help: Show help text', '### Exit Codes - 0: Success ... 127: Command not found', and '### Output Streams - stdout: Primary output ... stderr: Logs, errors'. This is mostly efficient with a meaningful block of unnecessary known material — matching anchor 3 rather than anchor 4, where over-explanation would be only minor. | 3 / 5 |
Actionability | As an instruction-only advisory skill the guidance is concrete: a decision table mapping code features to rule files ('Help text, usage strings, --help | rules/help-and-documentation.md'), a four-part finding spec ('Identify the specific line(s) ... Name the violated principle ... Explain why ... Provide a concrete fix with code'), a worked specificity example ('"--output flag on line 42 shadows POSIX -o convention" not "flags should follow conventions"'), and severity criteria. It falls short of anchor 5 because no example finding or inline output format is shown — the report format lives entirely in a template file that is not present in the bundle. | 4 / 5 |
Workflow Clarity | A clear three-phase sequence ('Phase 1: Context Discovery' → 'Phase 2: Analysis' → 'Phase 3: Report') with numbered steps, a tool-type taxonomy, and checkpoints ('If ambiguous, ask the user', 'Read all target files completely. Do not review code you haven't read'). This is an advisory skill with no destructive or batch operations, so the validation cap does not apply; it sits at anchor 4 rather than 5 only because there is no step validating the produced report (e.g., confirming findings are grounded in cited lines) before output. | 4 / 5 |
Progressive Disclosure | The body is architected correctly for progressive disclosure — an overview delegating detail to well-signaled, one-level-deep references ('rules/core-principles.md', 'rules/error-handling.md', 'templates/review-report.md', selected via a clear table) — but the actual bundle contains no rules/ or templates/ directories: all 12 referenced paths are dangling. Scored against the actual bundle structure as the guidelines direct, the disclosure structure is broken as shipped: the detailed content is neither inlined nor reachable, which is a structural failure below anchor 3 (references present and functional but imperfectly organized). | 2 / 5 |
Total | 13 / 20 Passed |