Content
71%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 concrete code examples and precise review heuristics across all 21 laws. Its weaknesses are verbosity from restating well-known law definitions and a monolithic structure with no progressive disclosure into separate reference files.
Suggestions
Trim or collapse the 'Definition' fields for widely-known laws (Miller's, Hick's, Fitts's, Jakob's, Occam's Razor) to one phrase, since Claude already knows them; keep the full definitions only for the more niche laws.
Split the per-law detailed GOOD/BAD examples and review flags into one-level-deep reference files (e.g. references/cognitive-laws.md, references/visual-laws.md, references/behavioral-laws.md) and make SKILL.md an overview + Review Checklist that links to them, improving progressive disclosure and token efficiency.
Add an explicit numbered review workflow (1. scan the checklist, 2. identify relevant laws, 3. inspect code per law, 4. group findings via Cross-Cutting Concerns, 5. report) so the process is sequenced rather than implied.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is well-structured but ~970 lines and restates definitions of well-known laws (Miller's, Hick's, Fitts's, Jakob's, Occam's Razor) that Claude already knows; the 'Definition' + 'Key Takeaway' fields for obvious laws could be trimmed, though the GOOD/BAD examples and review flags earn their place. | 3 / 5 |
Actionability | Every law provides concrete 'What to look for in code' bullets, copy-paste-ready GOOD/BAD HTML/CSS examples, and specific review flags with numeric thresholds (e.g., '>7 top-level nav items', '44x44px targets', '>10 ungrouped <select> options'). | 5 / 5 |
Workflow Clarity | Clear usage sequence ('check the Review Checklist first... then refer to the detailed sections') plus the Review/Guidance mode distinction and Cross-Cutting Concerns grouping guidance; minor gaps in that there is no explicit numbered review-process workflow. | 4 / 5 |
Progressive Disclosure | Internal structure is solid (clear headers, a scannable checklist table, per-law subsections, cross-cutting grouping), but the file is monolithic with no bundle files and no overview-to-reference navigation; the detailed per-law GOOD/BAD examples that could live in separate reference files are all inlined in SKILL.md. | 3 / 5 |
Total | 15 / 20 Passed |