| name | spec-write |
| description | Draft or update a SPEC.md product specification for any project. Use when user says "write a spec", "draft the spec", "document what we're building", or "update the spec". |
Spec Write Skill
Purpose
Produce a SPEC.md that serves as the single source of truth for what a project is, what it does, and how it is built. This document drives TASKS.md, AGENTS.md, and all implementation decisions.
Step 1: Gather Context
Before writing, ask or infer:
- What is the project? — One-sentence description
- Who is it for? — Target user or persona
- What problem does it solve? — Core pain point
- What are the key features? — Top 3–7 capabilities
- What is explicitly out of scope? — Non-goals
- What is the tech stack? — Languages, frameworks, databases, external APIs
- What are the domain models? — Key data entities
If the user has already described the project, extract these from the conversation. Do not ask for information that is already clear.
Step 2: Write the SPEC.md
Use this exact structure:
# <Project Name>
## Overview
<2-3 sentence description of what the application does and who it is for.>
---
# Goals
The system should help users:
- <goal 1>
- <goal 2>
- <goal 3>
---
# Non Goals
The application will NOT initially support:
- <non-goal 1>
- <non-goal 2>
The focus is strictly <core focus area>.
---
# Core Features
## <Feature Name>
<Description of the feature and what it must do.>
---
## <Feature Name>
<Description.>
---
# System Architecture
<Brief description of the architectural approach — monolith, microservices, serverless, etc.>
Core components include:
- <component 1>
- <component 2>
---
# Tech Stack
## Backend
<Language and framework>
## Frontend
<Framework and libraries>
## Database
<Database>
## Background Jobs
<Queue system if applicable>
## External APIs
<Third-party integrations>
---
# Domain Models
## <ModelName>
<What this model represents.>
Fields include:
- <field 1>
- <field 2>
---
# Background Jobs (if applicable)
## <Job Name>
<What this job does.>
---
# Data Flow
1. <Step 1>
2. <Step 2>
3. <Step 3>
---
# User Interface
## <Page Name>
Displays:
- <element 1>
- <element 2>
---
# Security
The application must:
- <security requirement 1>
- <security requirement 2>
---
# Milestones
## Milestone 1
<Name and brief description>
## Milestone 2
<Name and brief description>
Step 3: Write or Update the File
- If
SPEC.md does not exist, create it.
- If it already exists, read it first, then produce a targeted edit — do not rewrite sections that haven't changed.
- Keep descriptions factual and implementation-neutral where possible.
Quality Rules
ALWAYS:
- Write in plain, unambiguous language
- Separate goals from non-goals clearly
- List domain models with their key fields
- Define milestones that map to discrete deliverables
NEVER:
- Include implementation code in the spec
- Over-specify UI details that belong in design docs
- Leave the Non Goals section empty — it is as important as Goals
- Write a spec longer than necessary — favor clarity over completeness
