JPeetz/agent-skills / skills/documentation-content/spec-writer
spec-writer
VerifiedUse 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.
| File | Kind | Size |
|---|---|---|
| CHANGELOG.md | markdown | 864 B |
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 8.7 KB |
| evals/evals.json | config | 4.4 KB |
SKILL.md
View on GitHub---
name: spec-writer
description: >
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.
version: 1.0.0
author: JPeetz (based on spec-writer by dannwaneri)
license: MIT
compatibility: >
Cross-platform: Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Windsurf,
Gemini CLI, OpenClaw, Hermes Agent, OpenCode, and any SKILL.md-compatible agent.
tags:
- spec-writing
- technical-planning
- task-breakdown
- requirements-engineering
- spec-driven-development
- sdd
- feature-specification
- assumption-tracking
- acceptance-criteria
- plan-first
- documentation
platforms:
- claude-code
- codex
- opencode
- cursor
- gemini-cli
- openclaw
- hermes-agent
- windsurf
- copilot
---
# Spec Writer
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:
1. **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.
2. **A Plan** — technical and concrete. Architecture decisions, data model changes, API contracts, testing strategy, security constraints.
3. **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)
- **Non-functional requirements** — performance, security, compliance constraints
- **Acceptance criteria** — binary Given/When/Then scenarios
- **Edge cases** — what happens at boundaries, with empty states, with errors
### Plan Section
The Plan section contains:
- **Architecture decisions** — components, interactions, data flow
- **Data model changes** — new/modified entities, fields, relationships
- **API contracts** — endpoints, methods, request/response shapes
- **UI changes** — components, states, navigation flow
- **Testing strategy** — unit, integration, E2E coverage requirements
- **Security & performance constraints** — auth, rate limiting, caching, SLAs
### Task Breakdown Section
The Task breakdown section contains:
- 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
1. **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.
2. **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.
3. **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.
4. **Missing edge cases.** Always include empty states, error states, boundary conditions (pagination limits, max file size, timeout duration), and concurrent access.
5. **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.
6. **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.
7. **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
- [ ] **Edge cases are covered** — empty states, error states, boundary conditions, concurrent access
- [ ] **Non-functional requirements are present** — performance, security, storage, latencyRelated skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |