writing-specs
Creates feature specifications capturing requirements and acceptance criteria. Use when writing specs, documenting features, or defining requirements.
When & Why to Use This Skill
This Claude skill streamlines the creation of comprehensive feature specifications by focusing on the 'what' and 'why' of product development. It provides a structured framework to capture requirements, success criteria, and user experience journeys while intentionally excluding implementation details. By enforcing a strict Given-When-Then format for acceptance criteria and a maximum requirement count, it ensures that specifications remain focused, testable, and aligned with MVP goals, making it an essential tool for product managers and technical writers.
Use Cases
- Product Requirement Documentation: Rapidly generate structured PRDs that define feature goals, design rationales, and measurable success metrics to align stakeholders.
- Agile Sprint Planning: Create clear, testable functional requirements with Given-When-Then acceptance criteria to provide developers and QA teams with an unambiguous definition of 'done'.
- MVP Scoping and Validation: Use the built-in scope check to identify over-engineered features and distill them into core requirements, ensuring a single-focus deliverable.
- User Journey Mapping: Document the expected user experience and interaction flow to ensure design goals are met before moving into the technical implementation phase.
| name | writing-specs |
|---|---|
| description | Creates feature specifications capturing requirements and acceptance criteria. Use when writing specs, documenting features, or defining requirements. |
Spec Writing
Create specifications capturing WHAT and WHY. Do not include implementation details (those belong in technical-details.md).
Required Sections
Feature Overview (2-3 paragraphs) - What it does, who uses it, what problem it solves
Success Criteria - Measurable outcomes defining "done"
Design Goals - Primary (must achieve) and secondary (nice to have)
User Experience (1-2 paragraphs) - How users interact, expected journey
Design Rationale (1-2 paragraphs) - Why this approach, key trade-offs
Constraints and Assumptions - Technical constraints, business assumptions
Functional Requirements (FR-N format) - Max 6-8 per spec, each specific and testable, with Given-When-Then acceptance criteria
Edge Cases and Error Handling - Unusual inputs, failure scenarios, expected behaviors
Acceptance Criteria Format
- [ ] Given [context], when [action], then [expected result]
Include 2-4 criteria per requirement covering happy path and key failure cases.
Exclusions
Do not include: architecture diagrams, code examples, database schemas, API signatures, development estimates, timeline references, or phase sections.
Validation
Before completing:
- Single MVP focus (one deliverable)
- All requirements have testable criteria
- No TODO/TBD placeholders
- Edge cases documented
Scope Check
If more than 6-8 requirements, the feature is too large. Identify 3-4 core requirements and flag the rest for a separate spec. Document in a "Scope Notes" section.
Directory Structure
specs/
├── YYYY-MM-DD-feature-name/
│ ├── README.md # Spec (WHAT and WHY)
│ └── technical-details.md # Implementation (HOW)
└── historical/
Templates
templates/spec-readme.md- New spec templatereferences/spec-guide.md- Guidelines and examples