Content
65%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 tidy, reference-delegating overview with excellent progressive disclosure and good token efficiency. Its weakness is actionability: the Check and Fix sections name the right concepts but provide no executable commands or inline example, and the validation step floats outside the workflow rather than acting as a checkpoint after fixes.
Suggestions
Make the Check section executable: inline the basic commands (e.g., fetch the rendered page and grep for 'application/ld+json') and the Google Rich Results Test URL.
Integrate validation as an explicit checkpoint in the Check → Fix flow (e.g., 'After adding markup, re-fetch the rendered page and run the Rich Results Test') instead of leaving it as a standalone Quick Reference bullet.
De-duplicate the rich-snippet benefit sentence, which currently appears in the intro, the first Quick Reference bullet, and the Explain section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and well-sectioned with no padding of concepts Claude already knows, but the rich-snippet benefit is stated three times ('Structured data enables rich snippets... increasing click-through rates' in the intro, 'Structured data enables rich snippets in search results' as the first Quick Reference bullet, and again nearly verbatim in Explain). Not score 5 because of that triplicated sentence; not score 3 because there is no substantive over-explanation, only minor redundancy. | 4 / 5 |
Actionability | Concrete artifacts are named ('JSON-LD, Microdata, or RDFa markup', 'Schema.org vocabulary', 'Validate with Google Rich Results Test', types like 'Article, Product, FAQ, HowTo, LocalBusiness') but nothing is executable: no fetch/grep command for checking rendered HTML, no validator URL, no inline JSON-LD example — key details are deferred entirely to references/rule.md. Not score 4 because a user cannot act on the Check/Fix steps without opening the reference; not score 2 because the guidance does specify concrete formats, types, and the validation tool. | 3 / 5 |
Workflow Clarity | Check → Fix → Explain → Code Review provides a recognizable sequence for an audit/fix skill, and verification is mentioned ('Validate with Google Rich Results Test', 'describe how to verify the final page output'), but no explicit validate-after-fix checkpoint exists — the validator appears only as a Quick Reference bullet, not as a step in the flow. Not score 4 because validation checkpoints are named but not integrated into the sequence; not score 2 because the Check/Fix ordering is coherent and the Code Review section does call out flagging routes and verifying final output. | 3 / 5 |
Progressive Disclosure | A short, cleanly sectioned overview that delegates implementation detail to a single well-signaled, one-level-deep pointer: 'For full implementation details, code examples, and framework-specific guidance, see references/rule.md' — and references/rule.md exists and covers exactly those topics (Code Example, per-type schema sections, Next.js integration, Verification). Not score 4 because there are no organization gaps: the split is appropriate and navigation is trivial. | 5 / 5 |
Total | 15 / 20 Passed |