Content
73%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 is a dense but genuinely instructive process skill: it sequences a multi-phase interview with explicit gates, stopping rules, a decision grid, worked examples, and a failure catalog, and it correctly defers the artifact template to a well-signaled reference file. Its main weakness is token economy — the aphoristic style restates each rule several times, inflating the context cost without adding guidance.
Suggestions
Tighten the prose: each critical rule is currently stated as an aphorism plus two or three restatements (e.g., rule 1 on proposing technology, or 'a spec wearing a design's clothes'); state the rule once and cut the rhetorical elaboration to reduce the ~330-line body materially.
Move the Common failures catalog and/or the Examples section into a references file (like document-format.md) and keep one-line summaries in SKILL.md, so the main body reads as an overview with well-signaled one-level-deep pointers.
Ground the remaining abstract directives ('Be incisive', 'propose the overall shape') with one concrete before/after illustration each, as the question sets and slice-naming rules already do.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The guidance is genuinely novel (no explanation of concepts Claude already knows), but nearly every rule is delivered with rhetorical elaboration — e.g., "the adjectives lose every time, and the adjectives are usually the customer", "a rubber stamp... paperwork people learn to route around", "a spec wearing a design's clothes". The same point is often restated two or three ways across ~330 lines, so the document could be tightened substantially without losing content; that matches "mostly efficient but includes some unnecessary explanation or could be tightened" rather than the noticeably-padded level 2. | 3 / 5 |
Actionability | This is an instruction-only skill, and the guidance is concrete: exact question sets ("who hurts", "what it costs today", "what do they do instead"), a literal decision grid table, named edge states to probe ("Empty, first time, the retry, the half-finished, the expired, the unauthorised"), a template artifact via `references/document-format.md`, and three worked examples with numbered actions and results. It is not 5 because a portion of the direction stays abstract ("Be incisive", "propose the overall shape") without the concrete illustrations the question sets get, and the artifact itself is deferred to the reference file. | 4 / 5 |
Workflow Clarity | The sequence is explicit and gated: SITUATION → PROBLEM → VERDICT → DECIDE, with hard checkpoints — "stop at a verdict and wait", "The user confirms before a single technical option is discussed", "get agreement before exploring" (Bound the round), "done when nothing answerable is left", and diagrams "checked against the repository before it lands". Error recovery is a dedicated Common failures section with cause/solution pairs, and the Examples section grounds the sequence in numbered action lists. This is an interview skill, not a destructive/batch operation, so no validation cap applies. | 5 / 5 |
Progressive Disclosure | The one bundle file (`references/document-format.md`) is a real, well-signaled, one-level-deep reference with explicit load timing ("Read references/document-format.md when you write the .design/<name>.md artifact... Do not load it during the interview"), and the body is clearly sectioned. It is not 5 because the SKILL.md body itself runs ~330 lines of dense material — much of the interview doctrine and the failure catalog could live in reference files, leaving the overview leaner, which matches "good structure; most content is appropriately placed; minor organization gaps". | 4 / 5 |
Total | 16 / 20 Passed |