write-spec

Write a detailed feature specification from requirements. Use after shaping to create spec.md with goals, user stories, requirements, and technical approach.

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 18, 2025

When & Why to Use This Skill

This Claude skill streamlines the software development lifecycle by automating the creation of comprehensive technical specifications from raw requirements. It generates structured 'spec.md' files that encompass project goals, user stories, detailed technical approaches, and Mermaid-based architecture diagrams, ensuring a seamless transition from product shaping to engineering execution.

Use Cases

  • Technical Documentation Automation: Transform business requirements and planning documents into professional, structured technical specifications automatically.
  • System Architecture Visualization: Generate integrated Mermaid diagrams to visualize system components, data flows, and architectural hierarchies within the spec.
  • Standardizing Development Workflows: Enforce consistency across engineering teams by using standardized templates for all feature specifications and technical designs.
  • Bridging Product and Engineering: Facilitate better alignment between stakeholders and developers by translating high-level goals into actionable technical requirements and user stories.
  • Pre-Coding Feasibility Analysis: Review and document technical patterns and reusable code components before the implementation phase to reduce technical debt.
namewrite-spec
descriptionWrite a detailed feature specification from requirements. Use after shaping to create spec.md with goals, user stories, requirements, and technical approach.

Write Spec

Create a comprehensive specification document from gathered requirements.

When to Use

  • Requirements are gathered in planning/requirements.md
  • Ready to document the technical specification
  • Need a clear spec before task breakdown

Workflow

  1. Analyze Inputs

    • Read amp-os/specs/[feature]/planning/requirements.md
    • Review any visuals in planning/visuals/
    • Load relevant standards skills
  2. Search for Reusable Code

    • Use finder to locate similar implementations
    • Document patterns to reuse
    • Note existing components to leverage
  3. Write Specification

    • Follow template exactly from spec-template.md
    • Save to amp-os/specs/[feature]/spec.md
  4. Generate Architecture Diagram

    • Load amp-os-architecture-diagrams skill
    • Create system/component diagram with mermaid
  5. Verify Spec Quality

    • Load amp-os-spec-verifier skill
    • Ensure completeness and feasibility

Important Constraints

  • Do NOT write actual code in spec.md
  • Keep sections concise and skimmable
  • Reference visual assets when available
  • Follow template structure exactly

Resources

Amp Tools to Use

  • finder - Find similar implementations
  • mermaid - Architecture diagrams
  • oracle - Review spec for completeness