# Spec Writing

> Write a technical or feature specification covering behavior, states, edge cases, and acceptance criteria. Use whenever the user mentions spec, feature spec, technical spec, behavior spec, or needs a document that an engineer can implement against.

- Skill: `dragoon0x/spec-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dragoon0x/spec-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dragoon0x/spec-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dragoon0x (https://skillmd.com/u/dragoon0x)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dragoon0x/spec-writing

---


# spec-writing

a spec answers "how will this behave in every situation it could be in?" without describing implementation.

## the difference from a prd

a prd says why and what. a spec says how it behaves. the prd answers "should we build it?". the spec answers "what exactly are we building?".

## structure

```
# [feature name] spec

## overview
one paragraph: what this is, who uses it, what it lets them do.

## user-facing behavior

### entry points
how do users get here. list every path.

### primary flow
step by step, what the user does and what the system does back.

### states
- default
- loading
- empty
- partial (some data present, some missing)
- error
- success
- offline
for each, describe: what's shown, what's interactive, what changes when state changes.

### edge cases
list them explicitly:
- input outside expected range
- network failure mid-action
- concurrent edits
- expired auth
- permission boundaries
- very large inputs
- very small or zero inputs
- characters outside ascii
- timezone considerations

## data

### inputs
each field: name, type, validation, source.

### outputs
each piece of data the system produces or stores.

### persistence
what gets saved, where, for how long.

## permissions
who can see what.
who can do what.
how permission changes propagate.

## acceptance criteria

given/when/then statements that pass when the feature is correctly built:

given [precondition]
when [action]
then [expected result]

write enough of these to cover every state and every edge case.

## out of scope
explicit list of things adjacent that this spec does not address.

## open questions
what's not decided yet and who decides.
```

## rules

- specs are not implementation. don't dictate database choice or framework. do dictate behavior the user experiences.
- every behavior gets an acceptance criterion. if you can't write one, the behavior isn't specified.
- be boring. specs are read by people who need to implement, not be entertained.