Content
78%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 highly actionable, well-organized reference with executable code and dense failure→fix tables, and no wasted prose. Its main structural weakness is that everything lives in SKILL.md itself — per-pattern detail and the state/failure references belong in a references/ bundle to keep the main file a lean overview — and there is no explicit verification step for reviewing an authored widget.
Suggestions
Split the per-pattern essentials (Combobox/Tabs/Disclosure/Tooltip code plus required-ARIA tables) and the 'ARIA states reference' table into references/patterns.md and references/states.md, leaving SKILL.md as a lean overview with well-signaled one-level-deep pointers (e.g. 'See [patterns.md](references/patterns.md) for per-pattern code').
Trim content Claude already knows — e.g. the 'Common ARIA failures' and 'Anti-patterns' tables largely restate standard ARIA knowledge (positive tabindex, aria-hidden on focusable elements, aria-label overriding visible text); keep only the non-obvious entries.
Add an explicit review-checkpoint step, e.g. a short 'Reviewing a widget' checklist: (1) is a native element possible? (2) does it match an APG pattern exactly? (3) run the failures/anti-patterns tables as a checklist, optionally verifying programmatically with axe-a11y.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and table-driven with compact, load-bearing code (no padded prose), but the 31-pattern catalog partially duplicates the 'first rule of ARIA' native-fallback table, and the failures/anti-patterns tables restate knowledge Claude already has (e.g. positive 'tabindex="3"' is fragile, 'aria-hidden' on a focusable element is broken). Matches the score-4 anchor (efficient, minor instances of over-explanation that could be trimmed) rather than score 5. | 4 / 5 |
Actionability | Copy-paste-ready HTML for Combobox, Tabs, Disclosure, and Tooltip, each paired with a required-ARIA/keyboard-behavior table, plus concrete failure→fix and anti-pattern→fix pairs covering the common cases. Fully executable and specific, matching the score-5 anchor rather than score 4 (no significant gaps in the guidance given). | 5 / 5 |
Workflow Clarity | A coherent implicit sequence is present — prefer native HTML ('When the visual design demands a custom widget, follow the matching APG pattern exactly'), apply the per-pattern essentials, then check the 'Common ARIA failures' and 'Anti-patterns' tables — but no explicit validation checkpoint (e.g. a review checklist step) for verifying an authored widget. Matches the score-4 anchor (clear sequence, most checkpoints present, minor gaps), not score 5. | 4 / 5 |
Progressive Disclosure | The skill is well-sectioned with clear headers, but there are no bundle files at all: the 31-pattern catalog, per-pattern code, the ARIA states reference, and the failure tables are all inlined in a ~240-line SKILL.md. This matches the score-3 anchor (good structure, but content that should be separate — the per-pattern essentials — is inline) rather than score 4, which requires well-signaled one-level-deep references into actual bundle files. | 3 / 5 |
Total | 16 / 20 Passed |