Content
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured, actionable skill body with a clear phased workflow, explicit validation gates and bounded feedback loops, and clean one-level-deep progressive disclosure. The main weakness is token efficiency: the Verifier is restated across sections and the Output Behavior guidance is tangential.
Suggestions
Consolidate the Verifier description: keep a one-line non-negotiable in Critical Rules #4 and defer all mechanics to Sub-Agent Delegation / sub-agents.md rather than restating the full five-step process inline in two places.
Trim or remove the "Output Behavior" section's model-guidance paragraph — it is tangential ceremony that does not advance the spec-driven workflow.
Reconcile the orphaned references/coding-principles.md: either link it from the body (e.g., under a principles/practices pointer) or remove it so the bundle has no dangling files.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly dense and procedural with no padding of concepts Claude already knows, but not every token earns its place: the Verifier is described twice (Critical Rules #4 and again in Sub-Agent Delegation), and the "Output Behavior" model-guidance section is tangential ceremony. Not a 3 because of this redundancy and ceremony; not a 1 because it never explains basic concepts. | 2 / 3 |
Actionability | Gives concrete, actionable guidance — exact commands ("python3 scripts/lessons.py list --status confirmed"), the .specs/ directory tree, trigger-to-reference mapping tables, and concrete rules ("One atomic commit per task"). Per the instruction-skill scoring note, absence of code is not penalized when guidance is actionable; not a 2 because nothing is pseudocode or missing key details for its role as a coordinator. | 3 / 3 |
Workflow Clarity | Clear Specify→Design→Tasks→Execute sequence with explicit validation checkpoints ("the gate must pass... before a task is done", always-on Verifier after the last task) and an explicit feedback loop ("fix→re-verify loop is bounded to 3 iterations before escalating"). Not a 2 because checkpoints and retry bounds are explicit, not implicit. | 3 / 3 |
Progressive Disclosure | Clear overview body with well-signaled one-level-deep references (all [name](references/name.md) links resolve to real files), content split by phase plus cross-cutting concerns, and easy navigation via the Commands trigger tables. Not a 2 because references are clearly signaled and one level deep, not inline walls of text; the unreferenced coding-principles.md orphan is a minor nit. | 3 / 3 |
Total | 11 / 12 Passed |