# Spec Specify

> Create or update specs/{feature}/spec.md from user requirements — writing user stories, functional requirements, acceptance criteria, and resolving ambiguity through focused questions. Use this skill whenever someone wants to document feature requirements, write a specification, turn ideas or user research into a formal spec, update spec.md, or says "create a spec for [feature]". This is the first required step in the spec-driven workflow and typically follows spec-constitution when a team uses shared constitutional rules. Don't use for execution design, task decomposition, bug fixes, or implementation.

- Skill: `h3y6e/spec-specify` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add h3y6e/spec-specify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/h3y6e/spec-specify/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- License: MIT
- Author: h3y6e (https://skillmd.com/u/h3y6e)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/h3y6e/spec-specify

---


# Specify Skill

## Purpose

**Core principle:** Understand before specifying. No spec without exploring the problem space first.

Create or update `specs/{feature}/spec.md` from user requirements.
Resolve ambiguity within this skill before handing off to downstream phases.

## Input

- User requirements
- Existing `specs/constitution.md` when present
- Existing `specs/{feature}/spec.md` when present

## Output

- `specs/{feature}/spec.md`

## Steps

1. Resolve `language` and shared rules from `specs/constitution.md` when present; otherwise infer from the available workflow documents and the user's own message. Ask only if still unclear, then conduct all subsequent interaction in this language.
2. Decide the feature slug and target `specs/{feature}/`.
3. Create the spec from `references/spec-template.md`.
   - Keep the spec focused on user needs, behavior, business rules, and constraints
   - Design for isolation and clarity — break the system into units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
   - YAGNI ruthlessly — remove unnecessary features from all designs
   - When meaningful alternatives exist, compare 2-3 approaches with trade-offs and record the selected direction plus rejected alternatives concisely
   - Avoid locking in technical design choices unless the user explicitly requires them
   - If optional or secondary capabilities can stand alone, prefer splitting them into separate specs instead of expanding the current one
   - Record spec-to-spec prerequisites only in frontmatter `dependencies` as `specs/{feature}/spec.md` paths
   - Write acceptance scenarios as natural sentences that still make context, action, and outcome explicit; avoid forcing literal `Given/When/Then` wording when it hurts readability
4. Run a specification self-review: Scope, Data, UX, Non-Functional, Integration, Edge, Terminology, Ambiguity, Completion.
5. Ask only high-impact clarification questions.
   - Ask one question at a time
   - Prefer multiple choice when possible — easier to answer than open-ended
   - Actively look for ambiguity that would materially change scope, behavior, data, UX, or downstream execution design
   - If the request describes multiple independent subsystems, stop and surface the decomposition decision immediately — do not spend clarification cycles refining details of a project that first needs to be split into separate specs
   - Resolve high-impact ambiguity before recommending the next phase
   - Delegate low-impact open points to `spec-research` for investigation
6. Integrate answers directly into the spec.
7. Update frontmatter.
   - Required keys: `status`, `summary`, `dependencies`
   - Initial `status`: `draft`
   - Set `dependencies: []` when the spec has no prerequisite specs
   - Set `status: approved` when no unresolved high-impact ambiguity remains and the spec is ready for execution design and tasking
8. Perform final review and keep the file within 150 lines.
   - Remove repetition, simplify wording, resolve contradictions
9. In the completion message, suggest the next step.
   - If review-ready: `spec-plan`
   - If open points need investigation: `spec-research`
   - If more refinement is needed: continue `spec-specify`

## Success Criteria

- Prioritized user stories include at least one P1 story.
- Acceptance scenarios are testable.
- Functional requirements align with success criteria.
- Material alternatives and the selected direction are explicit when they affect scope.
- No unresolved high-impact ambiguity remains before handoff.

## Completion Guidance

- Next recommended step: `spec-plan` (or `spec-research` if open points remain)
- Include the target feature and generated `spec.md` path in the response