Content
82%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, highly actionable converter skill: the pipeline commands are fully executable with concrete flags and exit-coded input gates, and sections are clearly organized. It drops points for triple-stating the reviewer mandate, lacking a post-render validation/feedback step, and signaling bundle references that are not shipped alongside the SKILL.md.
Suggestions
Add a final validation step to the pipeline (e.g., confirm review.html was written and that rendered hunk/annotation counts match hunks.json/annotations.json) plus error-recovery guidance for each stage, which would raise workflow_clarity to anchor 5.
State the mandatory --reviewer rule once in Hard rules and reference it from the Pipeline and 'What gets rendered' sections, and trim canon attributions to their short form, to cut redundant tokens.
Ship references/ (diff_rendering_canon, severity_coding, pr_annotation_ux) and the three scripts alongside SKILL.md — or make the script paths relative to this skill's own directory — so the signaled one-level-deep references are actually resolvable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly lean — dense tables, commands, and rules with no explanations of concepts Claude already knows — but the mandatory --reviewer rule is stated three times ("--reviewer is mandatory — refuses without", "Reviewer footer — mandatory; refuses to render without --reviewer", and Hard rule 1) and canon attributions ("Mirrors research-ops's 'named owner' discipline") add tokens; minor over-explanation that could be trimmed fits anchor 4 rather than anchor 5's 'every token earns its place'. | 4 / 5 |
Actionability | The three-step pipeline is copy-paste ready with full flags and example values ("--reviewer \"Jane Doe\" --title \"PR #123: Add retry logic\""), each refusal carries a concrete exit code ("Refuses with exit 3 otherwise", "exit 4"), and a custom flag example is given ("--severity-convention \"critical,important,suggestion,nit\""); specific examples cover the common end-to-end case, matching anchor 5. | 5 / 5 |
Workflow Clarity | The sequence is explicit (diff_parser → annotation_extractor → review_html_renderer, each step annotated with its purpose) and input validation is strong (exit-code refusals, "Refuses input < 100 lines", onboarding gate), but there is no post-render verification of the output HTML and no error-recovery loop if a pipeline step fails — clear sequence with most checkpoints present fits anchor 4 rather than anchor 5's 'explicit validation steps; feedback loops'. | 4 / 5 |
Progressive Disclosure | Structure is good — a concise overview with clearly signaled one-level-deep references ("See `references/` for full citations (diff_rendering_canon, severity_coding, pr_annotation_ux)") — but the referenced references/ and scripts/ files are not present in the skill bundle, and script paths resolve against an external repo layout ("markdown-html/skills/md-review/scripts/…") rather than this skill's own directory, leaving navigation unverifiable; this minor organization gap fits anchor 4 rather than anchor 5. | 4 / 5 |
Total | 17 / 20 Passed |