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.
A lean, well-structured overview body with exemplary progressive disclosure to a single, clearly signaled reference file. The weaknesses are in the middle sections: the Check/Fix guidance lacks executable specifics (no search pattern, no deprecated-role list, no role-to-modern-equivalent mapping), and redundant Quick Reference/Explain sections pad the token budget without adding information Claude doesn't already have.
Suggestions
Make the Check section executable: give a concrete search pattern (e.g., grep -rn 'role="(directory|...)' across templates/JSX) and enumerate the deprecated/abstract roles to look for instead of just citing `directory`.
Add a short deprecated-to-modern mapping in Fix or ensure the body points to where one lives (e.g., directory → role="list" or native <ul>, prefer native <nav> over role="navigation") so the fix step is copy-paste actionable.
Trim the Quick Reference bullets and the generic Explain section, which restate the intro and instruct Claude to do something it already knows, freeing tokens for the missing concrete details.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is short and sectioned, but contains redundant material: the "Quick Reference" bullets ("Deprecated ARIA roles should be replaced with modern equivalents", "Ensures long-term compatibility with assistive technologies") largely restate the opening paragraph, and the "Explain" section instructs Claude to do something it already knows how to do without adding information. The templated "Code Review" section also repeats content. It is above a 2 because there is no concept-teaching padding and most sections carry some signal, but it could be tightened. | 3 / 5 |
Actionability | "Search the codebase for deprecated ARIA roles like `directory` or abstract roles" and "Update deprecated ARIA roles to their modern recommended equivalents or use native HTML elements" give direction and one concrete example role, but no executable search command/pattern (e.g., grep for role=\"directory\"), no list of which roles are deprecated or abstract, and no deprecated-to-modern mapping table. The guidance is concrete in intent but incomplete in the details needed to execute without consulting the reference. | 3 / 5 |
Workflow Clarity | The Check → Fix → Explain → Code Review sections form a coherent sequence for a simple review skill, and verification is addressed ("note how to verify the fix with browser accessibility tooling or assistive tech"). It is not a 5 because the verification step names no specific tool or command in the body (axe/Lighthouse live only in the reference file) and there is no explicit checkpoint that the fix be re-verified before finishing. It is above a 3 because the single-purpose flow is unambiguous and non-destructive, so the missing-validation cap does not apply. | 4 / 5 |
Progressive Disclosure | The body is a concise overview with clear sections, and the single reference `references/rule.md` (verified to exist) holds the code example, standards, and verification detail — one level deep, well signaled ("For full implementation details, code examples, and framework-specific guidance, see `references/rule.md`"), with no nested references. Content is appropriately split between overview and detail, matching the anchor for clear structure and easy navigation. | 5 / 5 |
Total | 15 / 20 Passed |