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 automates the creation of professional feature specifications, focusing on the 'what' and 'why' of product development. It streamlines the process of capturing functional requirements, user experience goals, and measurable success criteria while ensuring a clear separation between business logic and technical implementation.
Use Cases
- Product Requirement Document (PRD) Creation: Transforming high-level feature ideas into structured specifications with clear functional requirements and design rationale.
- QA and Testing Alignment: Generating precise 'Given-When-Then' acceptance criteria that serve as a direct foundation for test cases and quality assurance workflows.
- Stakeholder Communication: Creating a standardized single source of truth to align product managers, designers, and engineers on feature scope and user journeys.
- Scope Management: Utilizing the built-in validation and scope-check rules to identify overly complex features and break them down into manageable MVP deliverables.
| 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