AI-powered specification creation, validation, and enhancement for Claude
OpenSpec is a Claude skill that transforms specification-driven development by providing AI-powered assistance for creating, validating, and enhancing technical specifications. Whether you're documenting a new feature, designing an API, or architecting a system, OpenSpec helps you produce comprehensive, professional specifications in minutes instead of hours.
- Intelligent Specification Generation - Create comprehensive specs from natural language descriptions
- Automated Validation - Check specifications against industry standards and best practices
- Smart Enhancement - Add technical details, edge cases, and security considerations automatically
- Multiple Specification Types - Support for features, APIs, architecture, and processes
- Interactive Guidance - Step-by-step assistance for first-time spec writers
- Quality Scoring - Objective quality assessment with actionable feedback
This skill is designed to work with Claude. Simply clone or download this repository:
git clone https://github.com/yourusername/openspec.git
cd openspecSimply ask Claude to help with specifications:
"Create a specification for a user authentication system with OAuth support"
Claude will automatically use the OpenSpec skill to:
- Ask clarifying questions about your requirements
- Generate a comprehensive specification
- Validate the specification for completeness
- Save the result as a markdown file
Example conversation:
You: "Help me create a specification for a dark mode feature"
Claude: "I'll help you create a comprehensive feature specification for dark mode.
Let me ask a few questions to ensure we cover everything:
1. Should dark mode activate automatically based on system preferences?
2. Do you want users to manually toggle between themes?
3. Should the preference be saved across sessions?
4. Are there specific accessibility requirements?
5. What's your target timeline for implementation?"
[After answering questions]
Claude: "Excellent! I'll now generate your specification. This will take about
a minute..."
[Generates complete specification with all required sections]
Claude: "I've created your Dark Mode Feature Specification and saved it to
dark-mode-feature-spec.md
The specification includes:
- Executive summary and background
- 4 detailed user stories with acceptance criteria
- Technical architecture using CSS variables
- Accessibility requirements (WCAG AA compliant)
- Testing strategy and rollout plan
- Timeline with 7 milestones
Quality Score: 8.7/10
Would you like me to:
1. Enhance any specific section?
2. Add more edge cases?
3. Convert it to Word format?
4. Review the validation feedback?"
Generate comprehensive specifications from minimal input:
"Create an API spec for a tasks management API with CRUD operations"
"I need a technical architecture specification for a microservices platform"
"Help me write a process specification for our code review workflow"
Check your specifications for completeness and quality:
"Validate this specification" [attach file]
"Check if my spec meets industry standards"
"Review this technical spec for gaps"
Improve existing specifications with AI suggestions:
"Enhance this spec with technical details"
"Add edge cases to my specification"
"Suggest security considerations for this API spec"
Get step-by-step help for writing specifications:
"Guide me through creating a specification"
"I need help writing my first spec"
"Walk me through the specification process"
OpenSpec supports four types of specifications:
For new product features or enhancements.
Includes:
- User stories and use cases
- Functional requirements
- UI/UX specifications
- Technical architecture
- Testing strategy
Example: Dark mode feature, user authentication system, notification system
For designing and documenting APIs.
Includes:
- Endpoint definitions
- Request/response formats
- Authentication & authorization
- Error handling
- Rate limiting
Example: REST API, GraphQL API, WebSocket API
For system architecture and technical design.
Includes:
- System architecture diagrams
- Component design
- Technology stack
- Scalability & performance
- Security architecture
Example: Microservices architecture, cloud infrastructure, data pipeline
For operational processes and workflows.
Includes:
- Process steps and flows
- Roles & responsibilities
- Business rules
- Quality assurance
- Monitoring & reporting
Example: Deployment process, code review workflow, incident response
OpenSpec generates comprehensive specifications by:
- Understanding Context - Analyzes your requirements and asks clarifying questions
- Applying Best Practices - Uses industry standards and proven templates
- Generating Realistic Content - Creates specific, actionable content (no placeholders)
- Ensuring Completeness - Includes all required sections with appropriate detail
- Self-Validating - Checks quality before presenting results
Result: Professional specifications that score 8.0+ on quality metrics in under 30 minutes.
Specifications are validated across four dimensions:
- All required sections present
- Sufficient detail in each section
- No placeholder content
- Tables and lists populated
- Specific, measurable requirements
- Testable acceptance criteria
- Clear, unambiguous language
- Appropriate examples
- No contradictions
- Aligned sections
- Consistent terminology
- Accurate cross-references
- Security considerations
- Performance requirements
- Testing strategy
- Risk identification
Overall Quality Score: 0-10 scale with actionable feedback
OpenSpec can enhance existing specifications by adding:
- Technical Details - Architecture decisions, implementation approaches
- Edge Cases - Unusual scenarios and error conditions
- Security Considerations - Threats, mitigations, compliance requirements
- Performance Requirements - Response times, throughput, scalability
- Testing Strategies - Test approaches, coverage requirements
- Risk Analysis - Potential risks and mitigation strategies
Enhancements maintain consistency with your existing content and preserve your writing style.
openspec/
├── SKILL.md # Core skill documentation (read by Claude)
├── README.md # This file
├── SPECIFICATION.md # Project specification
├── templates/
│ ├── feature-spec-template.md # Template for feature specifications
│ ├── api-spec-template.md # Template for API specifications
│ ├── architecture-spec-template.md # Template for architecture specs
│ └── process-spec-template.md # Template for process specifications
└── examples/
├── example-feature-spec.md # Example: Dark Mode feature
└── example-api-spec.md # Example: Tasks API
- Provide Context - Share background about the problem you're solving
- Be Specific - More details lead to better specifications
- Answer Questions - OpenSpec's clarifying questions improve quality
- Review and Refine - Use validation feedback to improve the spec
- Iterate - Enhance sections that need more detail
- Review All Feedback - Check each validation issue carefully
- Prioritize Critical Issues - Address high-severity items first
- Understand Trade-offs - Some brevity may be intentional
- Consider Your Audience - Adjust detail level appropriately
- Identify Gaps - Determine which sections need improvement
- Request Specific Enhancements - "Add edge cases" or "Enhance security section"
- Review Suggestions - Evaluate each enhancement before accepting
- Maintain Consistency - Ensure enhancements align with existing content
| Score | Quality Level | Interpretation |
|---|---|---|
| 9.0-10.0 | Excellent | Ready for approval with minimal changes |
| 8.0-8.9 | Good | Minor improvements recommended |
| 7.0-7.9 | Acceptable | Moderate improvements needed |
| 6.0-6.9 | Needs Work | Significant improvements required |
| < 6.0 | Incomplete | Major revisions needed |
To improve Completeness:
- Add missing sections
- Expand brief sections with more detail
- Remove placeholder content
- Populate all tables and lists
To improve Clarity:
- Make requirements specific and measurable
- Add testable acceptance criteria
- Define technical terms
- Provide examples
To improve Consistency:
- Check for contradictions
- Align goals with requirements
- Use consistent terminology
- Verify numbers match across sections
To improve Best Practices:
- Add security considerations
- Define performance requirements
- Include testing strategy
- Identify risks and mitigations
See examples/example-feature-spec.md for a complete dark mode feature specification.
Highlights:
- Comprehensive user stories with acceptance criteria
- Technical architecture with CSS variables
- Accessibility requirements (WCAG AA)
- Performance requirements and metrics
- Complete testing strategy
- 6-week implementation timeline
Quality Score: 8.7/10
See examples/example-api-spec.md for a complete Tasks API specification.
Highlights:
- Full CRUD endpoint documentation
- OAuth 2.0 authentication
- Request/response examples
- Error handling with status codes
- Rate limiting and webhooks
- Security and performance requirements
Quality Score: 8.5/10
You can modify templates in the templates/ directory to match your organization's standards:
- Edit the relevant template file
- Add or remove sections as needed
- Update field definitions and examples
- Save the template
OpenSpec will use your customized templates for future specifications.
Convert specifications between formats:
"Convert this markdown spec to Word format"
"Export this specification as a docx file"
OpenSpec uses appropriate styling and formatting for each target format.
For multiple specifications:
"Create specifications for these three features: [list features]"
"Validate all specs in the current directory"
Issue: Specification is too generic
Solution: Provide more specific requirements and context. Answer all clarifying questions in detail.
Issue: Validation score is lower than expected
Solution: Review validation feedback carefully. Focus on addressing high-severity issues first. Use enhancement feature to improve specific sections.
Issue: Generated specification doesn't match expectations
Solution: Request refinements: "Add more technical detail to the architecture section" or "Expand the edge cases section with 5 more scenarios."
Issue: Need specification in specific format
Solution: OpenSpec generates markdown by default. Request format conversion: "Convert this to Word format" or customize the output format in your request.
Q: How long does it take to generate a specification?
A: Most specifications are generated in 1-3 minutes, depending on complexity. Simple specs (< 10 sections) take about 1 minute, while comprehensive specs (20+ sections) may take 2-3 minutes.
Q: Can I customize the templates?
A: Yes! Edit the template files in the templates/ directory to match your organization's requirements.
Q: What makes a high-quality specification?
A: High-quality specifications score well across four dimensions: completeness (all required sections with detail), clarity (specific and measurable), consistency (no contradictions), and best practices (security, testing, risks).
Q: Can OpenSpec integrate with my project management tools?
A: Not in v1.0. OpenSpec generates markdown files that you can import into your tools. Direct integrations are planned for future versions.
Q: Is my data secure?
A: Specifications are processed locally within your Claude environment. No data is sent to external services. Generated files are saved to your specified location.
Q: Can I use OpenSpec for non-technical specifications?
A: Yes! While optimized for technical specifications, OpenSpec works well for any structured documentation including business processes, operational procedures, and project plans.
- Server-side storage - Sync specifications across devices
- Collaboration features - Multi-user editing and comments
- Custom validation rules - Define organization-specific requirements
- Template marketplace - Share and download community templates
- Integration with project management - Export to Jira, Linear, Asana
- Visual diagram generation - Auto-generate architecture diagrams
- Version control integration - Track specification changes over time
We welcome contributions! Here's how you can help:
- Report Issues - Found a bug or have a suggestion? Open an issue.
- Improve Templates - Submit better templates or examples.
- Add Examples - Share your successful specifications as examples.
- Enhance Documentation - Improve this README or other docs.
- Share Feedback - Tell us how you're using OpenSpec and what could be better.
MIT License - see LICENSE file for details.
- Documentation: Full documentation
- Examples: See examples/ directory
- Issues: GitHub Issues
- Discussions: GitHub Discussions
OpenSpec is built on industry best practices from:
- IEEE Software Requirements Specifications
- Material Design documentation guidelines
- OpenAPI Specification standards
- WCAG Accessibility Guidelines
Built with Claude | Powered by AI | Designed for Developers
Made with ❤️ by the OpenSpec Team