spec-writer

Create a SPEC.md with user stories, acceptance criteria, and risks.

415|44|Updated Mar 18, 2026
One-click install
npx skills add https://github.com/notque/claude-code-toolkit --skill spec-writer-notque
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: spec-writer
Source: https://github.com/notque/claude-code-toolkit/tree/main/skills/spec-writer
Command: npx skills add https://github.com/notque/claude-code-toolkit --skill spec-writer-notque

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Structured specification with explicit scope boundaries: user stories, acceptance criteria, out-of-scope definitions, risks, and estimation to ensure alignment before design and implementation.

Core Features & Use Cases

  • Defines user stories, acceptance criteria, out-of-scope items, risks, and estimation to guide the feature lifecycle.
  • Enforces a measurable, testable specification that serves as the single source of truth for design, development, and validation.
  • Supports phased workflows from spec to design to plan to implement to release.

Quick Start

Draft a SPEC.md at the project root describing the feature scope, user stories, acceptance criteria, and risks in a single, testable document.

Frequently Asked Questions about spec-writer

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a software specification with clear scope boundaries and acceptance criteria?

A software specification defines user stories, testable acceptance criteria, out-of-scope items, risks, and estimation to ensure alignment before design. This approach enforces a measurable document serving as the single source of truth for development and validation.

What should be included in a feature specification document to prevent scope creep?

A feature specification document prevents scope creep by explicitly defining at least three out-of-scope items alongside user stories and acceptance criteria. Including risks, assumptions, and estimation further constrains the feature lifecycle boundaries before implementation begins.

How many user stories should a specification include before moving to feature design?

A specification should include a maximum of seven user stories to maintain focus before moving to feature design. Limiting user stories ensures the specification remains testable, measurable, and manageable while enforcing gate checks prior to design execution.

Does generating a SPEC.md work within an active git worktree?

Generating a SPEC.md works within an active git worktree by saving the artifact to .feature/SPEC.md instead of the project root. This ensures the specification document integrates seamlessly into isolated feature branches and phased workflows.

When do I need to define risks and assumptions in a project specification?

You need to define risks and assumptions in a project specification before proceeding to feature design and implementation. Documenting these elements alongside estimation and acceptance criteria ensures the team addresses potential roadblocks early in the phased workflow.

What is the best way to structure acceptance criteria for user stories?

The best way to structure acceptance criteria for user stories is to make them objective and testable. This ensures the specification serves as a measurable single source of truth for validation and guides the entire feature lifecycle from design to release.