Content
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, highly actionable skill with excellent workflow clarity and well-defined validation checkpoints, conditional branching, and error recovery paths. The content is mostly concise but could be tightened in a few areas (the 'What this skill is NOT' section, some redundant framing). Progressive disclosure is adequate given the single-file format, with clear references to external documents, though the overall length pushes the boundary of what should remain inline.
Suggestions
Consider trimming or removing the 'What this skill is NOT' section — these constraints are already implicit from the workflow steps and the 'When to use' section's negative criteria.
The 'Tool conventions' section says 'Same as draft-spec/SKILL.md' — either inline the 2-3 key rules or remove the section entirely to avoid a reference that adds little value on its own.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient and avoids explaining concepts Claude already knows, but there's some redundancy (e.g., the 'What this skill is NOT' section restates constraints already implied, and the tool conventions section defers to another skill's file rather than being self-contained or omitted). The 'When to use' section is thorough but slightly verbose with its negative examples. | 2 / 3 |
Actionability | The skill provides highly concrete, step-by-step instructions with specific tool calls (e.g., `mcp__github__create_issue_comment`, `mcp__github__add_issue_labels`), exact commit message formats, specific file paths (`docs/epics/_template.md`), branch naming conventions, and precise conditional logic (e.g., ADR status checks with exact responses). Every step is executable. | 3 / 3 |
Workflow Clarity | The workflow is clearly sequenced across Pre-flight → Research → Write → Self-review → Submit → If blocked, with explicit validation checkpoints (ADR status check halts with specific actions, self-review via `review-spec` and `architecture-review`, idempotency short-circuit with `ai:planned` label). Error recovery paths are well-defined (blocked flow, plugin-not-loaded fallbacks, slice count guardrails). | 3 / 3 |
Progressive Disclosure | The skill references external files (`docs/epics/README.md`, `docs/epics/_template.md`, `draft-spec/SKILL.md`, `AGENTS.md`, `CONSTITUTION.md`) appropriately, but all content is inline in a single file that runs quite long. Some sections like the detailed blocker conditions or the 'What this skill is NOT' could potentially be separated. However, references are one-level deep and clearly signaled, which is good. | 2 / 3 |
Total | 10 / 12 Passed |