Use this skill when a vague feature request, ticket, PRD fragment, or rough idea needs to be turned into a structured specification, technical plan, and ordered task breakdown for AI coding agents. Generates all three output sections immediately, then flags every implicit decision as an inline [ASSUMPTION: ...] marker with an impact rating and correction guidance — no back-and-forth questions needed before drafting. Primary keywords: spec-driven development SDD, feature specification generation, technical planning, task breakdown, assumption flagging, acceptance criteria Given When Then, requirements engineering, feature request refinement, specification writing agent, plan-first development. For all major agentic platforms.
Turns a vague feature request into a structured spec, technical plan, and task breakdown — ready for any coding agent to implement without guessing.
Overview
AI coding agents don't fail because the model is weak. They fail because the instructions are ambiguous. This skill closes that gap before the agent starts.
Given any feature description — a sentence, a ticket, a PRD fragment, a rough idea — spec-writer produces three deliverables in a single output:
A Spec — functional, technology-agnostic. What the feature does, who uses it, what must be true, what can go wrong, and binary acceptance criteria in Given/When/Then format.
A Plan — technical and concrete. Architecture decisions, data model changes, API contracts, testing strategy, security constraints.
A Task breakdown — ordered, self-contained tasks. Each completable in a single agent session. Each with its own acceptance criteria.
The key methodology: generate first, flag assumptions inline. Instead of asking clarifying questions before drafting, the skill produces a complete output and marks every decision made without user input as [ASSUMPTION: ...] — impact-rated, with guidance on when to correct it.
When to Use
A stakeholder or user sends a vague feature request ("add export", "build a dashboard", "let users invite teammates")
You have a Jira ticket, Linear issue, or GitHub issue that says what but not how, and needs decomposing into agent-ready work
You need to validate scope and surface hidden assumptions before implementation starts
You're handing work to another agent or developer and want to eliminate ambiguity
You want acceptance criteria that are binary pass/fail, not "works correctly"
You need a plan-first methodology for Spec Driven Development (SDD)
Do not use this skill when:
The requirements are already a complete, unambiguous spec with acceptance criteria
You need a quick one-line answer rather than a structured document
You're asking a question rather than requesting a feature
How to Invoke
/spec-writer [feature description]
Pass anything — a feature description, a ticket, a PRD fragment, a rough idea:
/spec-writer Add password reset via email
/spec-writer Build an admin dashboard showing daily active users
/spec-writer Let users invite teammates to their workspace
/spec-writer Add rate limiting to the public API
The skill produces a complete spec, plan, and task breakdown in one shot. No intermediate questions.
Output Format
The output is a single document with three sections, each clearly delimited:
Spec Section
The Spec section contains:
Purpose — one or two sentences describing the feature's goal
Use case(s) — who uses this feature and what they accomplish
Functional requirements — what the system must do (numbered)
A numbered list of ordered, self-contained tasks, each with:
Dependencies — which tasks must complete first
Acceptance criteria — binary pass/fail conditions unique to that task
Estimated complexity — (small / medium / large)
No task says "implement the feature" — every task is independently verifiable
Assumption Markers
Every decision the skill makes without explicit user input is marked inline with an [ASSUMPTION: ...] annotation:
When the export contains more than 1,000 rows
[ASSUMPTION: async for large exports — Impact: HIGH]
Then the export is generated asynchronously and the user is notified by email
At the end of the output, all assumptions are collected into a prioritized summary:
## Assumptions to Review
1. Async generation for exports over 1,000 rows — Impact: HIGH
Correct this if: your order volumes are low and synchronous is fine
2. Date range filter is required — Impact: MEDIUM
Correct this if: the first version should export all orders with no filtering
Assumption Impact Levels
Impact
Meaning
HIGH
Changing this assumption could significantly alter the architecture or effort
MEDIUM
Changing this assumption would affect the design but not the overall approach
LOW
Changing this assumption is a minor adjustment with no architectural impact
Common Pitfalls
Over-specifying technology in the Spec section. The Spec must remain technology-agnostic. Framework choices, database decisions, and library selections belong in the Plan section only.
Acceptance criteria that aren't binary. "Works correctly" is not a criterion. "Returns 401 when unauthenticated" is. Every criterion must be testable as pass/fail.
Tasks that are too large. If a task's acceptance criteria read like a mini-spec, break it down further. Every task should be completable in a single agent session.
Missing edge cases. Always include empty states, error states, boundary conditions (pagination limits, max file size, timeout duration), and concurrent access.
Skipping the assumptions review. The generated assumptions are a feature, not a bug. Always explicitly review and either confirm or override each HIGH/MEDIUM assumption before handing the output to an implementer.
Mixing spec with plan details. If an acceptance criterion mentions a specific library or framework, it belongs in the Plan. Keep the Spec pure functional requirements.
No non-functional requirements. Storage limits, latency targets, concurrency expectations, and accessibility requirements are often assumed but must be explicit.
Verification
After generating the output, verify the following before considering it complete:
Every [ASSUMPTION] marker is impact-rated — HIGH, MEDIUM, or LOW — with correction guidance
Assumptions are collected into a single summary section at the end
Spec is technology-agnostic — no framework, library, or infrastructure choices in functional requirements or acceptance criteria
Acceptance criteria are binary — every scenario is a clear Given/When/Then that can pass or fail
Plan contains concrete decisions — architecture, data model, API contracts, testing strategy
Tasks are self-contained — each has unique acceptance criteria and clear dependencies
No task says "implement the feature" — the largest task should be implementable in a single agent session
Non-functional requirements are present — performance, security, storage, latency
1---2name: spec-writer3description: >4 Use this skill when a vague feature request, ticket, PRD fragment, or rough idea5 needs to be turned into a structured specification, technical plan, and ordered6 task breakdown for AI coding agents. Generates all three output sections7 immediately, then flags every implicit decision as an inline [ASSUMPTION: ...]8 marker with an impact rating and correction guidance — no back-and-forth9 questions needed before drafting. Primary keywords: spec-driven development10 SDD, feature specification generation, technical planning, task breakdown,11 assumption flagging, acceptance criteria Given When Then, requirements12 engineering, feature request refinement, specification writing agent,13 plan-first development. For all major agentic platforms.14version: 1.0.015author: JPeetz (based on spec-writer by dannwaneri)16license: MIT17compatibility: >18 Cross-platform: Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Windsurf,19 Gemini CLI, OpenClaw, Hermes Agent, OpenCode, and any SKILL.md-compatible agent.20tags:21 - spec-writing22 - technical-planning23 - task-breakdown24 - requirements-engineering25 - spec-driven-development26 - sdd27 - feature-specification28 - assumption-tracking29 - acceptance-criteria30 - plan-first31 - documentation32platforms:33 - claude-code34 - codex35 - opencode36 - cursor37 - gemini-cli38 - openclaw39 - hermes-agent40 - windsurf41 - copilot42metadata:43 source: https://skillmd.com/skills/jpeetz/spec-writer44---4546# Spec Writer4748Turns a vague feature request into a structured spec, technical plan, and task breakdown — ready for any coding agent to implement without guessing.4950---5152## Overview5354AI coding agents don't fail because the model is weak. They fail because the instructions are ambiguous. This skill closes that gap **before** the agent starts.5556Given any feature description — a sentence, a ticket, a PRD fragment, a rough idea — spec-writer produces three deliverables in a single output:57581. **A Spec** — functional, technology-agnostic. What the feature does, who uses it, what must be true, what can go wrong, and binary acceptance criteria in Given/When/Then format.592. **A Plan** — technical and concrete. Architecture decisions, data model changes, API contracts, testing strategy, security constraints.603. **A Task breakdown** — ordered, self-contained tasks. Each completable in a single agent session. Each with its own acceptance criteria.6162The key methodology: **generate first, flag assumptions inline**. Instead of asking clarifying questions before drafting, the skill produces a complete output and marks every decision made without user input as `[ASSUMPTION: ...]` — impact-rated, with guidance on when to correct it.6364---6566## When to Use6768- A stakeholder or user sends a vague feature request ("add export", "build a dashboard", "let users invite teammates")69- You have a Jira ticket, Linear issue, or GitHub issue that says *what* but not *how*, and needs decomposing into agent-ready work70- You need to validate scope and surface hidden assumptions before implementation starts71- You're handing work to another agent or developer and want to eliminate ambiguity72- You want acceptance criteria that are **binary pass/fail**, not "works correctly"73- You need a plan-first methodology for Spec Driven Development (SDD)7475Do **not** use this skill when:76- The requirements are already a complete, unambiguous spec with acceptance criteria77- You need a quick one-line answer rather than a structured document78- You're asking a question rather than requesting a feature7980---8182## How to Invoke8384```85/spec-writer [feature description]86```8788Pass anything — a feature description, a ticket, a PRD fragment, a rough idea:8990```91/spec-writer Add password reset via email92/spec-writer Build an admin dashboard showing daily active users93/spec-writer Let users invite teammates to their workspace94/spec-writer Add rate limiting to the public API95```9697The skill produces a complete spec, plan, and task breakdown in one shot. No intermediate questions.9899---100101## Output Format102103The output is a single document with three sections, each clearly delimited:104105### Spec Section106107The Spec section contains:108109- **Purpose** — one or two sentences describing the feature's goal110- **Use case(s)** — who uses this feature and what they accomplish111- **Functional requirements** — what the system must do (numbered)112- **Non-functional requirements** — performance, security, compliance constraints113- **Acceptance criteria** — binary Given/When/Then scenarios114- **Edge cases** — what happens at boundaries, with empty states, with errors115116### Plan Section117118The Plan section contains:119120- **Architecture decisions** — components, interactions, data flow121- **Data model changes** — new/modified entities, fields, relationships122- **API contracts** — endpoints, methods, request/response shapes123- **UI changes** — components, states, navigation flow124- **Testing strategy** — unit, integration, E2E coverage requirements125- **Security & performance constraints** — auth, rate limiting, caching, SLAs126127### Task Breakdown Section128129The Task breakdown section contains:130131- A numbered list of **ordered, self-contained tasks**, each with:132 - **Dependencies** — which tasks must complete first133 - **Acceptance criteria** — binary pass/fail conditions unique to that task134 - **Estimated complexity** — (small / medium / large)135- No task says "implement the feature" — every task is independently verifiable136137---138139## Assumption Markers140141Every decision the skill makes without explicit user input is marked inline with an `[ASSUMPTION: ...]` annotation:142143```144When the export contains more than 1,000 rows145 [ASSUMPTION: async for large exports — Impact: HIGH]146Then the export is generated asynchronously and the user is notified by email147```148149At the end of the output, all assumptions are collected into a prioritized summary:150151```152## Assumptions to Review1531. Async generation for exports over 1,000 rows — Impact: HIGH154 Correct this if: your order volumes are low and synchronous is fine1552. Date range filter is required — Impact: MEDIUM156 Correct this if: the first version should export all orders with no filtering157```158159### Assumption Impact Levels160161| Impact | Meaning |162|--------|---------|163| **HIGH** | Changing this assumption could significantly alter the architecture or effort |164| **MEDIUM** | Changing this assumption would affect the design but not the overall approach |165| **LOW** | Changing this assumption is a minor adjustment with no architectural impact |166167---168169## Common Pitfalls1701711. **Over-specifying technology in the Spec section.** The Spec must remain technology-agnostic. Framework choices, database decisions, and library selections belong in the Plan section only.1722. **Acceptance criteria that aren't binary.** "Works correctly" is not a criterion. "Returns 401 when unauthenticated" is. Every criterion must be testable as pass/fail.1733. **Tasks that are too large.** If a task's acceptance criteria read like a mini-spec, break it down further. Every task should be completable in a single agent session.1744. **Missing edge cases.** Always include empty states, error states, boundary conditions (pagination limits, max file size, timeout duration), and concurrent access.1755. **Skipping the assumptions review.** The generated assumptions are a feature, not a bug. Always explicitly review and either confirm or override each HIGH/MEDIUM assumption before handing the output to an implementer.1766. **Mixing spec with plan details.** If an acceptance criterion mentions a specific library or framework, it belongs in the Plan. Keep the Spec pure functional requirements.1777. **No non-functional requirements.** Storage limits, latency targets, concurrency expectations, and accessibility requirements are often assumed but must be explicit.178179---180181## Verification182183After generating the output, verify the following before considering it complete:184185- [ ] **Every [ASSUMPTION] marker is impact-rated** — HIGH, MEDIUM, or LOW — with correction guidance186- [ ] **Assumptions are collected** into a single summary section at the end187- [ ] **Spec is technology-agnostic** — no framework, library, or infrastructure choices in functional requirements or acceptance criteria188- [ ] **Acceptance criteria are binary** — every scenario is a clear Given/When/Then that can pass or fail189- [ ] **Plan contains concrete decisions** — architecture, data model, API contracts, testing strategy190- [ ] **Tasks are self-contained** — each has unique acceptance criteria and clear dependencies191- [ ] **No task says "implement the feature"** — the largest task should be implementable in a single agent session192- [ ] **Edge cases are covered** — empty states, error states, boundary conditions, concurrent access193- [ ] **Non-functional requirements are present** — performance, security, storage, latency
Run npx get-skill add jpeetz/spec-writer in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Use this skill when a vague feature request, ticket, PRD fragment, or rough idea needs to be turned into a structured specification, technical plan, and ordered task breakdown for AI coding agents. Generates all three output sections immediately, then flags every implicit decision as an inline [ASSUMPTION: ...] marker with an impact rating and correction guidance — no back-and-forth questions needed before drafting. Primary keywords: spec-driven development SDD, feature specification generation, technical planning, task breakdown, assumption flagging, acceptance criteria Given When Then, requirements engineering, feature request refinement, specification writing agent, plan-first development. For all major agentic platforms. It is listed under Product & Planning on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.
JPeetz (@jpeetz) published this skill. Their other Agent Skills are listed on their SkillMD profile.