Content
70%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, operationally rich body: the symptom-to-action table, hard rules with exit codes, and worked example make the workflow unambiguous and self-validating. Its weaknesses are duplicated philosophical framing (the forcing-question library and its canon citations) and references to script/asset files that are not actually shipped in the bundle.
Suggestions
Merge the forcing-question library's recommended answers into the 10-question table and drop the canon citations (Aarron Walter, Ellen Lupton, Adobe Spectrum, Nielsen-Norman) — they duplicate the question set and add tokens Claude doesn't need.
Ship the referenced bundle files (scripts/onboard.py, scripts/config_loader.py, scripts/brand_palette_validator.py, assets/design_system_schema.json) or remove the references — every path beyond SKILL.md is currently dangling.
Replace the '.../' path abbreviations in the worked example and invoke table with the full 'markdown-html/skills/design-system/scripts/' path so every command is copy-paste ready.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient operational content (tables of questions, tokens, exit codes, commands), but it includes unnecessary material: the 'Forcing-question library' section re-covers the 10-question set and pads each item with canon citations ("Canon: Aarron Walter, Designing for Emotion (color carries brand affect)", "Canon: Ellen Lupton, Thinking with Type") that duplicate the question table and add background knowledge Claude does not need. This fits the 'mostly efficient but includes some unnecessary explanation' anchor rather than the 4 anchor's 'minor instances'. | 3 / 5 |
Actionability | Concrete, near-executable guidance throughout — exact invocations with flags ("python3 .../onboard.py --set brand.primary=#FF6B35 --set design_style=editorial", "MARKDOWN_HTML_NO_CONFIG=1 python3 .../config_loader.py --show", "brand_palette_validator.py --primary \"#FF6B35\" --accent \"#00D4AA\"") plus exit codes 3 and 4. It misses the 5 anchor because many commands use abbreviated '.../' paths instead of the copy-paste-ready full path given once at the top. | 4 / 5 |
Workflow Clarity | Clear sequencing with explicit validation and feedback loops: "onboard.py refuses to save (exit code 4) and tells the user to pick a darker primary, blank brand.bg/brand.text to let derivation pick a safe pair, or override brand.text directly", exit code 3 for unwritable output dirs, a symptom-to-action 'When to invoke' table, and an ordered worked example covering first-run, override, reset, inspect, and bypass. This matches the 5 anchor (explicit validation steps, error-recovery guidance); no destructive/batch operation lacks validation. | 5 / 5 |
Progressive Disclosure | Sections are well organized with clear headers, but the body references bundle files that do not exist — "This skill ships exactly three Python tools" (scripts/onboard.py, config_loader.py, brand_palette_validator.py) and "JSON schema lives at assets/design_system_schema.json" — while no scripts/ or assets/ directories are present in the bundle. Per the guideline to score against the actual bundle structure, the clearly-signaled references are all dangling, which undercuts the 'references mostly clear' 4 anchor and lands at 'some structure but could be better organized'. | 3 / 5 |
Total | 15 / 20 Passed |