Content
72%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 strongly actionable, well-organized body whose executable tool guidance and worked example are excellent. The weaknesses are structural: every referenced bundle file is missing from the skill directory, and the batch-audit workflow never closes the loop by re-running the checker after fixes. Time-sensitive version details scattered through the evergreen sections will also rot quickly.
Suggestions
Add an explicit fix-then-revalidate step to Mode 2: after applying fixes, re-run 'python3 scripts/hig_checker.py batch audit.json' and only report 'ship' status once the score reaches the 90+ threshold — this closes the feedback loop the batch workflow requires.
Ship the referenced bundle files ('references/visual-design.md', 'references/accessibility.md', 'references/platform-specifics.md', 'scripts/hig_checker.py', 'templates/hig-audit-template.md') or inline their essential content — currently every referenced path is missing from the bundle, so the skill's core audit workflow cannot actually be executed as written.
Consolidate the version/date details (WWDC25 announcement, iOS 26/macOS Tahoe, Sept 2025 ship dates) out of the intro and Core Design Principles into a single short 'Version notes' or 'Deprecated patterns' section so the evergreen guidance does not rot with each OS release.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and lean — exact CLI invocations, the batch JSON input shape, a worked example with real output, and numbered fixes — but time-sensitive version/date details ('announced at WWDC25, June 2025; shipped Sept 2025 across iOS 26, iPadOS 26, macOS Tahoe...') appear in the intro and in Core Design Principles #1 outside any 'old patterns'/'deprecated' section, which the guidelines penalize. This is a minor, trimmable amount of over-explanation (anchor 4) rather than a broader tightness problem (anchor 3). | 4 / 5 |
Actionability | Fully executable, copy-paste-ready guidance: three concrete subcommands with real expected output ('python3 scripts/hig_checker.py contrast "#8E8E93" "#FFFFFF" -> Contrast Ratio: 3.26 [FAILED]'), the batch JSON input shape, and a worked example whose fixes include specific values ('darken to >= #6E6E73 on white', 'expand the hit region to 44x44 with padding/contentShape'). Matches anchor 5; the examples cover the common audit cases. | 5 / 5 |
Workflow Clarity | The Mode 1/Mode 2 sequence is clearly laid out with per-check pass/fail and scorecard thresholds (90-100 ship, 70-80 fix, <70 rework), but the batch-audit workflow lacks an explicit fix-then-re-run feedback loop: the worked example delivers findings and fixes without re-running 'hig_checker.py batch' to confirm the score recovers. The scoring notes cap workflow_clarity at 3 when feedback loops are missing in batch-operation contexts, so this cannot score 4 despite the otherwise clean sequencing. | 3 / 5 |
Progressive Disclosure | The body's structure is well-designed — clearly signaled, one-level-deep references to 'references/visual-design.md', 'references/accessibility.md', 'references/platform-specifics.md', 'scripts/hig_checker.py', and 'templates/hig-audit-template.md' — but none of these files exist in the bundle (no references/, scripts/, assets/, or templates/ directories are present), so every referenced path dangles and navigation dead-ends. Scored against the actual bundle structure per the guidelines, the cross-file organization is unfulfilled: a 3 ('some structure but could be better organized'), not the 4-5 the design would earn if the files shipped. | 3 / 5 |
Total | 15 / 20 Passed |