Content
77%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 disciplined, well-sequenced process specification with explicit gates, feedback loops, and verification steps — exemplary workflow clarity for an instruction-only skill. Its main defects are the missing DESIGN-DOC-TEMPLATE.md referenced at step 7, which undermines both progressive disclosure and executability of the drafting phase, and a handful of directives that lack a worked example.
Suggestions
Add the referenced DESIGN-DOC-TEMPLATE.md to the skill bundle (or inline its essential section structure), since step 7 depends on it but the file is absent from the skill directory.
Move the drafting style rules in step 7 (heading depth, table/diagram/list usage, link hygiene) into a short reference file or the template itself, slimming the SKILL.md body.
Include one compact worked example of a frontier question round or a skeletal design tree, so the step-5 directives ("trace", "assign ownership") have a concrete model to follow.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and directive throughout — it assumes competence, never explains general concepts, and avoids padding (e.g., "A heading labels a topic; the body makes the argument"). It earns 4 rather than 5 because a few sections carry layered qualifications that could be tightened, such as the repeated gating language in step 5 and the multi-clause edge-case rules in step 4. | 4 / 5 |
Actionability | Guidance is unusually concrete for a process skill: a default artifact path (`docs/design/<descriptive-slug>.md`), a copy-paste question format block, an exact sub-agent dispatch prompt, and a verification command (`git diff --check -- <document-path>`). It stays at 4 rather than 5 because several core directives remain directional rather than executable — "Trace the production path end to end" and "Assign one clear owner to every concern" describe outcomes without a worked example showing the expected artifact. | 4 / 5 |
Workflow Clarity | Nine explicitly sequenced phases with a hard gate ("Do not write the implementation plan or draft the design until this gate is complete"), explicit feedback loops (return to step 5 on unresolved decisions and on new findings from the adversarial pass), a re-validation loop ("repeat it only when the resulting revisions materially change the proposal"), and an 8-item pre-handoff checklist. This matches the anchor of clear sequence with explicit validation steps and error-recovery loops. | 5 / 5 |
Progressive Disclosure | Section structure is good and the sole external reference is clearly signaled and one level deep ("Read `DESIGN-DOC-TEMPLATE.md` from this skill directory before drafting"), but that file does not exist in the skill bundle — no references/, scripts/, or assets/ directories are present — so the primary progressive-disclosure mechanism is a broken reference. Additionally, the ~220-line body inlines substantial drafting style rules and checklists that could partially live in reference files. | 3 / 5 |
Total | 16 / 20 Passed |