Content
63%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-organized overview with exemplary progressive disclosure — a concise Quick Reference plus one clearly signaled reference file carrying the detailed examples. The weaknesses are redundant concept explanation (intro and 'Explain' sections) that Claude doesn't need, and Check/Fix guidance that stays at the level of direction rather than concrete, executable instructions.
Suggestions
Cut the intro paragraph and the 'Explain' section — Claude already knows why semantic HTML matters for screen readers and SEO; keep only the non-obvious Quick Reference rules like 'Only one <main> per page'.
Add a compact before/after snippet to the 'Fix' section (a div-soup block next to its semantic rewrite) so the guidance is concrete rather than directional.
Make 'Check' operational: specify what to inspect (rendered/DOM output vs. framework source) and what counts as a violation (e.g., generic containers wrapping nav/main/article content), rather than 'Review this HTML structure'.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient, but the intro ('Screen readers use semantic elements to navigate pages... Search engines also use semantics to understand content hierarchy') and the entire 'Explain' section restate why semantic HTML matters — background knowledge Claude already has. Not score 4, since these sections are clearly trimmable rather than minor instances of over-explanation. | 3 / 5 |
Actionability | The Quick Reference gives a concrete element mapping ('<article> for self-contained content, <section> for grouped content'), but 'Review this HTML structure to ensure...' and 'Replace generic div elements with semantic HTML5 elements' are direction without a concrete before/after example or inspection method. Not score 2 — the element mapping is genuinely concrete guidance — but key executable details are missing from the body. | 3 / 5 |
Workflow Clarity | For this simple single-purpose skill, the Check → Fix sequence is clear and the 'Flag exact elements, attributes, and routes' instruction gives an unambiguous single action. Not score 5 because the Check, Explain, and Code Review sections partially duplicate one another, leaving the intended workflow (inspect rendered markup → flag → fix) slightly ambiguous about which section governs. | 4 / 5 |
Progressive Disclosure | A lean, well-sectioned overview body with a single clearly signaled one-level-deep reference ('For full implementation details, code examples, and framework-specific guidance, see references/rule.md' — verified to exist and contain the full example). Content is appropriately split between the overview and the reference; easy navigation. | 5 / 5 |
Total | 15 / 20 Passed |