Writing formal, machine-readable specifications that drive AI-assisted implementation. This skill owns the Specify phase of the SDD pipeline and its output is the prerequisite for all downstream SDD work.
SDD Pipeline Position
INCEPTION → [SPECIFY] → PLAN → TASKS → IMPLEMENT → VERIFY
↑
You are here
The specification is the single source of truth. Every downstream artifact — task plan, architecture, implementation, tests — derives from and traces back to this document. Ambiguity in the spec propagates as defects in every subsequent phase.
Artifact-Pyramid Output: SPEC.md
The specification documents produced by this skill follow the artifact-pyramid structure:
| Layer | Content | File |
|---|---|---|
| L1 | Executive Summary — one-paragraph scope statement, key stakeholders, overall success criteria | 00-index.md (entry point) |
| L2 | Per-dimension specification — user stories, Gherkin scenarios, edge cases, NFRs, out-of-scope, data contracts | Individual *.spec.md files |
| L3 | Detailed per-story dossiers — full acceptance criteria, interface definitions, data schemas, examples | dossiers/ directory |
| SOURCES | Navigation index linking each L2 dimension to its L3 sources | Footer of each file |
Loading Guidance
| Reference | When to load | File |
|---|---|---|
| Spec Quality Gates | Before delivering any SPEC.md — validates completeness against 7 quality dimensions | references/spec-quality-gates.md |
| Gherkin Patterns | Writing executable scenarios — Given/When/Then structure for specific patterns | references/gherkin-patterns.md |
| Acceptance Criteria Design | Crafting ACs that pass the "no-surprises" test — edge case enumeration, boundary conditions | references/acceptance-criteria-design.md |
| Template | When to use | File |
|---|---|---|
| SPEC.md | Producing a specification document from scratch | templates/SPEC.md |
| Script | When to run | File |
|---|---|---|
spec-quality-check.sh |
After authoring a SPEC.md — validates all required sections exist | scripts/spec-quality-check.sh |
Trigger Conditions
Invoke this skill when:
- A new feature, component, or system needs a formal specification before implementation begins
- An existing specification needs refinement or gap analysis
- A vague requirement (ticket, conversation, email) needs to be translated into a structured SDD-ready spec
- The input is a research report, competitive analysis, or user interview transcript that needs distillation into engineering requirements
Output Contract
Every SPEC.md MUST include:
- Problem statement — what problem this solves and why it matters
- Scope boundary — explicit in-scope and out-of-scope
- User stories — prioritized, with links to acceptance criteria
- Acceptance criteria — per-story, framed as Given/When/Then or bulleted pass/fail conditions
- Edge cases — explicit enumeration of boundary conditions, error states, invalid inputs
- Non-functional requirements — performance, security, observability, compliance, accessibility
- Data contracts / interfaces — schemas, APIs, events (can be stubs that get refined in later phases)
The spec is NOT complete until a automated quality check passes (run spec-quality-check.sh).
SDD Philosophy
Specifications in SDD serve a different purpose than traditional requirements documents. They are not communication artifacts for humans that happen to be read by an AI. They are executable inputs to a code generation pipeline that happen to be readable by humans.
This distinction drives everything about how specs are written:
- Precision over clarity. A spec that is technically precise but dense is better than a spec that reads well but leaves ambiguity. The AI cannot ask for clarification when it encounters a vague phrase — it implements one interpretation at random.
- Completeness over brevity. Every missing acceptance criterion is a missing feature, not a question the implementer will ask. The cost of specifying an edge case up front is minutes. The cost of discovering it in production is hours or days.
- Testability over descriptiveness. An acceptance criterion that cannot be verified (passed or failed) by a deterministic check is not an acceptance criterion — it is a hope. Every AC must produce a binary verdict.
Framework Awareness
This skill is methodology-agnostic at the framework level but follows SDD principles common to all major frameworks:
- GitHub Spec Kit — Four-phase Specify→Plan→Tasks→Implement. The spec produced here fulfills Phase 1 (Specify).
- GSD — Uses PROJECT.md and REQUIREMENTS.md as spec layer. SPEC.md maps to these artifacts.
- BMAD — Role-based specification chain (BA → PRD → Architecture). SPEC.md here aligns with the PRD and Architecture layers.
- Taskmaster AI — PRD-driven. SPEC.md is the structured PRD that Taskmaster parses into task graphs.
- Native Claude Code — CLAUDE.md + spec files. SPEC.md is consumed alongside CLAUDE.md by the implementation agent.