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-structured, brief overview with excellent progressive disclosure to a real reference file. Its weaknesses are redundancy between the Quick Reference, Check, and Code Review sections, and Check/Fix guidance that names no concrete detection tooling or example markup in the body itself.
Suggestions
Merge the Quick Reference bullets into the Check section (or cut them) to remove the restatement of the same nesting rule.
Name a concrete detection method in Check (e.g., axe-core rule list or the DevTools accessibility tree) so the verification step is executable, not just directional.
Inline one minimal before/after snippet (orphaned role="listitem" vs. wrapped in role="list") in Fix so the fix is copy-paste ready without opening the reference.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The Quick Reference bullets ("Certain roles (like `listitem`) must be owned by specific parent roles") largely restate the Check section, and the Code Review section repeats the frontmatter description. Mostly efficient, but the redundancy could be tightened into one statement. | 3 / 5 |
Actionability | "Wrap elements with roles that require a specific parent in the appropriate container role (e.g., wrap role="listitem" in role="list")" is concrete, but the Check section gives no method (no axe-core, DevTools accessibility tree, or code snippet in the body). Some concrete guidance, incomplete on the detection side. | 3 / 5 |
Workflow Clarity | A clear sectioned sequence (Quick Reference → Check → Fix → Explain → Code Review) with verification signaled ("note how to verify the fix with browser accessibility tooling"). Simple non-destructive skill; the minor gap is that no specific validation tooling is named in the body itself. | 4 / 5 |
Progressive Disclosure | A short overview body with a single clearly signaled one-level-deep pointer — "For full implementation details, code examples, and framework-specific guidance, see `references/rule.md`" — and the referenced file exists and holds the code examples and verification details. Matches the clear-overview anchor. | 5 / 5 |
Total | 15 / 20 Passed |