Content
78%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 tight, actionable body with an executable pipeline, explicit refusal gates with exit codes, and good decision guidance, only slightly padded by a redundant ASCII diagram and citation flourishes. The main defects are the dangling references/ pointer and missing script files in the bundle, plus the absence of any post-render verification step.
Suggestions
Ship the referenced citation files (references/presentation_ux.md, keyboard_nav_patterns, single_file_deck_conventions) in the skill's references/ directory, or remove the 'See references/ for full citations' pointer — as bundled, the reference leads nowhere.
Use bundle-relative script paths (scripts/slide_splitter.py rather than markdown-html/skills/md-slides/scripts/slide_splitter.py) so the pipeline commands resolve from the skill's own directory, and verify the scripts actually ship alongside SKILL.md.
Add a post-render validation step with an error-recovery loop (e.g., confirm the deck's slide count matches slides.json after rendering, and re-run the failing stage on error) to close the workflow checkpoint gap.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and assumes competence: a symptom/action table, three-line pipeline, feature bullets, and numbered hard rules with exit codes — no explanation of concepts Claude already knows. Minor trimmable padding remains (the ASCII pipeline diagram duplicates the Pipeline commands, and book-citation flourishes like "(the polemic)" and "(Matt Pocock grill discipline)" plus the dated citation "Shihipar — Claude Code HTML output (Medium, 2026)" add tokens beyond what's needed). Efficient with minor over-elaboration, so level 4 rather than the every-token-earns-its-place level 5. | 4 / 5 |
Actionability | The Pipeline section gives three fully executable, copy-paste-ready bash commands with concrete flags and chained intermediate files (/tmp/slides.json → /tmp/deck.json → deck.html), refusal exit codes (5/6/7) are specified, the output artifact pattern "deck-{slug}.html" with collision suffixes is given, and flag semantics (--strict-notes, --syntax) are documented. Fully executable commands cover the common case, matching level 5. | 5 / 5 |
Workflow Clarity | The three-step pipeline is clearly sequenced with numbered comments and file chaining, and refusal rules with exit codes act as pre-flight validation gates ("Auto mode needs ≥ 3 HR lines or ≥ 5 H1 headings. Otherwise exit 6 — route to md-document"). However there is no post-render verification or error-recovery loop (e.g., check rendered slide count, what to do when a step fails mid-pipeline). Clear sequence with most checkpoints present but minor validation gaps, so level 4, not 5. | 4 / 5 |
Progressive Disclosure | Section organization is good (When to invoke, Pipeline, Hard rules, Distinct from, References), but the body's external pointers dangle: "See references/ for full citations (presentation_ux, keyboard_nav_patterns, single_file_deck_conventions)" refers to a references/ directory that does not exist in the bundle, and the pipeline commands invoke scripts under markdown-html/skills/md-slides/scripts/ that are also not present as bundle files. References are clearly signaled but unverifiable/nonexistent, leaving structure present but with real navigation gaps — level 3 rather than 4. | 3 / 5 |
Total | 16 / 20 Passed |