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.
The body delivers genuinely actionable, highly specific design-system guidance — exact tokens, ramps, tiers, decision rules, and worked examples that model the full observation-to-fix workflow. Its weaknesses are length and monolithic structure: rhetorical/rationale padding, redundant restatements of the 'lead with the feeling' rule, and specialized sections (unavailable-features policy, fix verification) inlined in SKILL.md that would be better as one-level-deep reference files.
Suggestions
Move the 'Make unavailable features understandable' subsection (with its source-file example table) and the 'Does the fix feel right in use?' verification guidance into a references/ file, keeping a 2–3 line summary with a clearly-signaled link in SKILL.md.
Trim or cut the rhetorical passages ('Why these four?' tensions narrative, the 'shifting left' intro paragraph) — they explain why the values exist but add ~40 lines that don't change how the skill is applied.
Consolidate the redundant 'lead with the feeling' guidance: the values-section aside, the 'Lead with the feeling, not the fix' table, and the numbered feedback ordering all restate the same rule — keep one canonical statement and one table.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Most content is skill-specific and earns its place (decision rules, token tables, worked examples, phrasebook), but at ~370 lines there is genuine padding: rhetorical passages like 'As more and more of the UI is implemented via agents...' and the 'It's fair to ask: who would ever want a UI that isn't calm...' rationale section, plus redundancy — the 'lead with the feeling' guidance appears in the values section, the feedback section, and its own 'Lead with the feeling, not the fix' table, and the phrasebook repeats the 'A bug here sounds like...' phrasing already embedded in each move. It is above anchor 2 (not 'several unnecessary explanations' of things Claude already knows) but below anchor 4 because whole sections could be tightened or cut. | 3 / 5 |
Actionability | For an instruction-only skill the guidance is fully concrete: exact token names (--vscode-cornerRadius-small/medium/large/circle), the enumerated spacing ramp (0,2,4,...,40), named type roles (heading1–3, body1–2, label1–3) with exactly two weights (400/600), icon sizes 16/12 with the *Compact glyph rule, one-stroke 1px, four named reveal-on-intent behaviors, and a do/don't phrasebook — plus worked examples covering common cases (busy panel, flat settings row, mismatched dialogs, bouncing panel) and links to real source implementations. Per the rubric's code-vs-instruction note, absence of code is not penalized when guidance is this actionable. | 5 / 5 |
Workflow Clarity | The core procedure is explicit and well-sequenced: 'name the feeling, find the principle it breaks, then reach for the move', a 5-step feedback ordering (feeling → surface → principle → move → number), worked examples modeling it, and a substantial verification section ('Try the thing, not its description', 'Make sure you're seeing the state you mean', 'Show the fix you actually shipped', check reduced motion and themes). It sits at anchor 4 rather than 5 because the sequence is distributed across several sections rather than one consolidated workflow, and there are no explicit error-recovery loops for cases where the first named principle turns out wrong. | 4 / 5 |
Progressive Disclosure | The file is well-structured internally (clear headers, anchor links, tables), but there is no bundle at all — everything lives in one ~370-line SKILL.md. Content that clearly belongs in reference files is inlined, notably the 'Make unavailable features understandable' policy subsection with its table of four source-file examples and the long 'Does the fix feel right in use?' verification guidance. External references (../ux-css-layout/SKILL.md, ../ux-theming/SKILL.md, design-tokens.instructions.md, source files) are clearly signaled, but they point outside the skill rather than splitting this skill's own bulk. That matches anchor 3: real structure, but content that should be separate is inline. | 3 / 5 |
Total | 15 / 20 Passed |