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.
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:
- 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)
- 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
- 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
- Edge cases are covered — empty states, error states, boundary conditions, concurrent access
- Non-functional requirements are present — performance, security, storage, latency
Related 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: 470k | Updated | Claude CodeCodex | Verified | 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 |