Content
86%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 well-structured, token-efficient design skill: it points to a real one-level-deep reference for the detailed rubric, provides a fully actionable clarify-then-spec workflow, and includes a copy-paste spec template with concrete defaults. The main improvement opportunities are consolidating flag conventions that repeat across sections and adding an explicit validation pass over the finished spec.
Suggestions
Consolidate the flag/output conventions (--json/--plain, --no-input, quiet/verbose, dry-run/confirmation) that currently repeat across "Clarify", "Deliverables", "Default Conventions", and the Template into a single section that the others reference.
Add an explicit validation checkpoint at the end of the workflow, e.g., "Before delivering, re-check the spec against references/cli-guidelines.md and the Deliverables list" to close the workflow-clarity gap.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and telegraphic ("Primary data to stdout; diagnostics/errors to stderr"), assuming Claude's competence with no concept explanations. However, the same flags and conventions (--json/--plain, --no-input, dry-run/confirmation, quiet/verbose) recur across "Clarify", "Deliverables", "Default Conventions", and the Template, which could be consolidated. Not 5 due to this cross-section repetition; not 3 because there is no padding or explanation of known concepts. | 4 / 5 |
Actionability | For an instruction-only design skill, the guidance is fully actionable: a concrete clarifying-question list, a deliverables checklist ("Command tree + USAGE synopsis", "Error + exit code map", "5-10 example invocations"), and a copy-paste-ready spec skeleton with concrete defaults (exit codes 0/1/2, precedence "flags > env > project config > user config > system", NO_COLOR/TERM=dumb handling). Per the scoring notes, absence of code is not penalized when guidance is this specific. | 5 / 5 |
Workflow Clarity | The sequence is explicit and ordered: "Do This First" (read references/cli-guidelines.md, ask minimum questions) -> "Clarify (fast)" with a fallback checkpoint ("Ask, then proceed with best-guess defaults if user is unsure") -> "Deliverables" -> template. Not 5 because there is no validation step for the produced spec (e.g., cross-check the final spec against the guidelines file before delivering). Not 3 because the sequence is explicit rather than implicit and a clarify-with-fallback checkpoint exists; the destructive/batch validation cap does not apply to this design skill. | 4 / 5 |
Progressive Disclosure | The body is a concise overview with a single, clearly signaled, one-level-deep reference ("Read `references/cli-guidelines.md` from this skill directory and apply it as the default rubric") that verifiably exists in the bundle; the bulk guideline detail lives in that 239-line file. Structure is easy to navigate with distinct sections for clarify/deliver/conventions/template. Not 4 because no content that belongs in the reference is inlined at problematic scale. | 5 / 5 |
Total | 18 / 20 Passed |