Spec Writer Skill
Overview
The spec_writer skill creates clear, feature-level specifications in Markdown following Spec-Driven Development (SDD) principles. This skill helps translate high-level feature requirements into well-structured, unambiguous specifications.
Skill Metadata
- •Name: spec_writer
- •Description: Writes clear, feature-level specifications in Markdown following Spec-Driven Development principles
- •Expected Input: High-level feature requirements or system intent
- •Expected Output: Well-structured, unambiguous Markdown specifications
- •Usage Example: Used when defining Phase I CLI features
Constraints
- •No application code
- •No agent definitions
- •Single file implementation
Specification Structure
The skill generates specifications following this standard structure:
markdown
# [Feature Name] Specification ## Overview [Brief description of the feature and its purpose] ## Requirements ### Functional Requirements - [Requirement 1] - [Requirement 2] - [Requirement 3] ### Non-Functional Requirements - **Performance**: [Performance requirements] - **Security**: [Security requirements] - **Usability**: [Usability requirements] ## Acceptance Criteria ### Success Criteria - [Success criterion 1] - [Success criterion 2] - [Success criterion 3] ### Error Handling - [Error condition 1]: [Expected behavior] - [Error condition 2]: [Expected behavior] ## Dependencies - [Dependency 1] - [Dependency 2] ## Out of Scope - [Item not included in this specification] - [Item explicitly excluded] ## Examples ### Example 1: [Example name]
[Example code or scenario]
code
### Example 2: [Example name]
[Example code or scenario]
code
## Notes - [Additional context or considerations] - [Implementation hints or constraints]
Usage Instructions
To use this skill:
Command Line Interface (CLI)
bash
# Invoke the skill via Claude Code claude --skill spec_writer "Create specification for user authentication feature"
Interactive Mode
- •Provide high-level feature requirements or system intent
- •The skill will generate a comprehensive specification in Markdown format
- •Review and refine the generated specification as needed
- •Save the specification in the appropriate location (typically
specs/[feature-name]/spec.md)
Input Validation & Constraints
Required Input Format
- •Type: Natural language description or structured requirements
- •Minimum length: 10 characters
- •Maximum length: 5000 characters
- •Format: Plain text or Markdown
Input Schema Validation
The skill validates input against these criteria:
- •Must describe a feature or system capability (not bug fixes or refactoring)
- •Should include clear intent or purpose
- •Should specify target users or stakeholders
- •Should mention key functionality (optional but recommended)
Invalid Input Handling
- •Empty input: Returns error "Feature description cannot be empty"
- •Too short (< 10 chars): Returns error "Description too brief - please provide more detail"
- •Too long (> 5000 chars): Returns error "Description exceeds maximum length of 5000 characters"
- •Unclear intent: Prompts for clarification with specific questions
Output Format Options
- •Format: Always Markdown (.md)
- •Sections: All sections in template are included by default
- •Optional sections: Can be omitted if not applicable:
- •Examples (if no examples needed)
- •Dependencies (if no external dependencies)
- •Out of Scope (if everything is in scope)
- •Notes (if no additional notes)
Version Compatibility
- •Claude Code Version: Compatible with v2.0 and above
- •Spec-Kit Plus: Compatible with v1.0 and above
- •Last tested: 2026-01-27
Implementation Notes
- •The skill focuses on clarity and unambiguity
- •Follows Spec-Driven Development principles
- •Generates specifications that serve as the single source of truth for feature implementation
- •Designed to be reusable across different projects and features
Optional vs Required Sections
Required Sections (Always Included)
- •Overview
- •Requirements (must include at least Functional OR Non-Functional)
- •Acceptance Criteria (must include at least Success OR Error Handling)
Optional Sections (Included if Applicable)
- •Dependencies (required if external dependencies exist)
- •Out of Scope (required if excluding specific items)
- •Examples (highly recommended but optional)
- •Notes (optional additional context)
Section Marking Convention
- •Bold headings (e.g., Performance) are required metadata
- •[Bracketed placeholders] (e.g., [Feature Name]) must be replaced
- •Optional sections can be marked with "(Optional)" comment if intentionally omitted
Error Handling
The skill handles errors in two contexts:
1. Input Validation Errors
- •Returns specific error messages for validation failures
- •Provides guidance on how to fix the input
- •Does not attempt to "guess" or "fix" invalid input automatically
2. Processing Errors
- •System errors: If Claude Code system errors occur, returns "System error - please retry"
- •Timeout errors: If processing exceeds 30 seconds, returns "Request timed out - please simplify your requirements"
- •Output validation errors: If generated specification fails internal validation, returns "Unable to generate specification - please rephrase your requirements"
Error Recovery: All errors include a suggestion to retry with clearer, more specific requirements.
Implementation Notes</parameter>
<parameter name=new_string>## Usage Instructions
To use this skill:
Command Line Interface (CLI)
bash
# Invoke the skill via Claude Code claude --skill spec_writer "Create specification for user authentication feature"
Interactive Mode
- •Provide high-level feature requirements or system intent
- •The skill will generate a comprehensive specification in Markdown format
- •Review and refine the generated specification as needed
- •Save the specification in the appropriate location (typically
specs/[feature-name]/spec.md)
Input Validation & Constraints
Required Input Format
- •Type: Natural language description or structured requirements
- •Minimum length: 10 characters
- •Maximum length: 5000 characters
- •Format: Plain text or Markdown
Input Schema Validation
The skill validates input against these criteria:
- •Must describe a feature or system capability (not bug fixes or refactoring)
- •Should include clear intent or purpose
- •Should specify target users or stakeholders
- •Should mention key functionality (optional but recommended)
Invalid Input Handling
- •Empty input: Returns error "Feature description cannot be empty"
- •Too short (< 10 chars): Returns error "Description too brief - please provide more detail"
- •Too long (> 5000 chars): Returns error "Description exceeds maximum length of 5000 characters"
- •Unclear intent: Prompts for clarification with specific questions
Output Format Options
- •Format: Always Markdown (.md)
- •Sections: All sections in template are included by default
- •Optional sections: Can be omitted if not applicable:
- •Examples (if no examples needed)
- •Dependencies (if no external dependencies)
- •Out of Scope (if everything is in scope)
- •Notes (if no additional notes)
Version Compatibility
- •Claude Code Version: Compatible with v2.0 and above
- •Spec-Kit Plus: Compatible with v1.0 and above
- •Last tested: 2026-01-27
Implementation Notes
- •The skill focuses on clarity and unambiguity
- •Follows Spec-Driven Development principles
- •Generates specifications that serve as the single source of truth for feature implementation
- •Designed to be reusable across different projects and features
Optional vs Required Sections
Required Sections (Always Included)
- •Overview
- •Requirements (must include at least Functional OR Non-Functional)
- •Acceptance Criteria (must include at least Success OR Error Handling)
Optional Sections (Included if Applicable)
- •Dependencies (required if external dependencies exist)
- •Out of Scope (required if excluding specific items)
- •Examples (highly recommended but optional)
- •Notes (optional additional context)
Section Marking Convention
- •Bold headings (e.g., Performance) are required metadata
- •[Bracketed placeholders] (e.g., [Feature Name]) must be replaced
- •Optional sections can be marked with "(Optional)" comment if intentionally omitted
Error Handling
The skill handles errors in two contexts:
1. Input Validation Errors
- •Returns specific error messages for validation failures
- •Provides guidance on how to fix the input
- •Does not attempt to "guess" or "fix" invalid input automatically
2. Processing Errors
- •System errors: If Claude Code system errors occur, returns "System error - please retry"
- •Timeout errors: If processing exceeds 30 seconds, returns "Request timed out - please simplify your requirements"
- •Output validation errors: If generated specification fails internal validation, returns "Unable to generate specification - please rephrase your requirements"
Error Recovery: All errors include a suggestion to retry with clearer, more specific requirements.
Implementation Notes</parameter>
</invoke> <invoke name="functions.Edit"> <parameter name=old_string>## Implementation Notes- •The skill focuses on clarity and unambiguity
- •Follows Spec-Driven Development principles
- •Generates specifications that serve as the single source of truth for feature implementation
- •Designed to be reusable across different projects and features
- •Handles edge cases gracefully with specific error messages
- •Supports both interactive and programmatic invocation
- •Validates output to ensure specification quality
Example Output
- •The skill focuses on clarity and unambiguity
- •Follows Spec-Driven Development principles
- •Generates specifications that serve as the single source of truth for feature implementation
- •Designed to be reusable across different projects and features
Example Output
markdown
# Todo List Management Specification ## Overview This specification defines the requirements for managing todo items in the application, including creation, retrieval, updating, and deletion operations. ## Requirements ### Functional Requirements - Users can create new todo items with title and description - Users can view all existing todo items - Users can update todo item properties (title, description, status) - Users can delete todo items - Users can mark todo items as complete/incomplete ### Non-Functional Requirements - **Performance**: Todo operations should complete within 500ms - **Security**: Todo data should be accessible only to authenticated users - **Usability**: Interface should be intuitive for non-technical users ## Acceptance Criteria ### Success Criteria - Todo items can be created with title and description - All todo items are displayed in a list view - Individual todo items can be edited - Todo items can be deleted permanently - Todo items can be marked complete/incomplete ### Error Handling - Invalid input: Display validation errors and prevent creation - Network errors: Show user-friendly error messages - Authentication failures: Redirect to login page ## Dependencies - User authentication system - Database storage for todo items - Frontend framework for UI components ## Out of Scope - User registration and authentication flow - Advanced filtering and search capabilities - Collaboration features (sharing todos) ## Examples ### Example 1: Creating a todo
POST /api/todos { "title": "Complete project documentation", "description": "Write comprehensive documentation for the todo app", "dueDate": "2023-12-31" }
code
### Example 2: Updating todo status
PATCH /api/todos/123 { "status": "completed" }
code
## Notes - Todo items should be stored with timestamps for creation and updates - Consider adding priority levels in future iterations
Skill Configuration
The skill is implemented as a single Markdown file that can be referenced by the Claude Code system. No additional configuration or dependencies are required.
Version History
- •1.0: Initial specification structure and examples
- •1.1: Added detailed usage instructions and implementation notes
- •1.2: Added input validation schema, CLI usage examples, error handling details, optional/required sections documentation, and version compatibility information