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 well structured and genuinely actionable, with a clean Check/Fix split and excellent progressive disclosure to references/rule.md. It is held back by redundant statistics repeated across Quick Reference and Explain, an Explain section that teaches concepts Claude already knows, and a batch fix workflow with no explicit validation/verification step.
Suggestions
Merge the Quick Reference stats and the Explain section into one place, and cut the motivational intro and browser-support tutorial — Claude already knows WebP/AVIF tradeoffs; keep only the rule-specific numbers and DevTools confirmation guidance.
Add an explicit validation checkpoint after the Fix step (e.g., 'Verify the <picture> element serves WebP/AVIF in the browser Network panel and that the fallback still renders'), since converting and rewriting all images is a batch operation.
Include a copy-paste-ready <picture> markup example (or a concrete Sharp/Squoosh command) in the Fix section to close the gap between described and executable guidance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The Check and Fix sections are dense and instruction-first, but the motivational intro ("Images are typically 50%+ of page weight... These savings compound across every visitor"), the Explain section's tutorial on WebP/AVIF compression and browser support that Claude already knows, and statistics stated twice ("25-35%" and "40-50%" appear in both Quick Reference and Explain) are unnecessary padding that could be merged. This sits between the 2 anchor (several padded sections) and 4 anchor (minor trim only), so 3 fits best. | 3 / 5 |
Actionability | Guidance is concrete and executable in prose: scan targets are enumerated ("Any <img src> pointing to .jpg, .jpeg, or .png", CSS background-image, missing <source> entries), fixes specify quality settings ("WebP at 80% quality using Squoosh or Sharp", "AVIF at 60% quality"), the exact <picture>/<source> structure, the JPEG fallback, and a "@supports (background-image: url('.webp'))" pattern. As an instruction-only skill this is actionable without code, but a copy-paste <picture> markup example or a concrete Sharp command would lift it to 5. | 4 / 5 |
Workflow Clarity | The Check → Fix → Explain → Code Review sequence is clear and the steps are numbered with reporting requirements ("file path and line number"), which would rate 4. However, the Fix step is a batch operation across all images and markup, and the workflow contains no explicit validation checkpoint for Claude's own changes — the DevTools confirmation appears only as something to "describe" to the user in the Code Review section — so per the batch-operation cap, workflow clarity cannot exceed 3. | 3 / 5 |
Progressive Disclosure | The ~30-line body is organized into scannable sections (Quick Reference, Check, Fix, Explain, Code Review) and defers detail via a clearly signaled one-level-deep pointer: "For full implementation details, code examples, and framework-specific guidance, see references/rule.md" — a real 189-line file with no nested references. This matches the clear-overview-with-well-signaled-references anchor. | 5 / 5 |
Total | 15 / 20 Passed |