Spec Kit Specify

Create or refresh the feature specification for the active Spec Kit feature.

Invocation Notice

• Inform the user when this skill is being invoked by name: spec-kit-specify.

When to Use

• Start a new feature and create the first spec.md.
• Convert free-form requirements into a structured, testable, implementation-agnostic specification.
• Rework an existing spec draft so it is ready for spec-kit-clarify or spec-kit-plan.

When Not to Use

• Clarify ambiguity in an already-written spec without redrafting it (spec-kit-clarify).
• Generate design artifacts or tasks from an approved spec (spec-kit-plan, spec-kit-tasks).
• Reconcile cross-artifact drift in an existing feature (spec-kit-reconcile).

Router Fit

• Primary route from spec-kit when spec.md does not exist yet.
• Downstream: hand off to spec-kit-clarify (if high-impact ambiguity remains) or spec-kit-plan (if spec is ready).

Preconditions

• User provided a non-empty feature description.
• Run from repository root (or a subdirectory inside the repository).

Workflow

1. Normalize input:

• Treat the full user request as the feature description.
• If empty, stop: ERROR: No feature description provided.

1. Generate a short branch suffix (2-4 words, kebab-case):

• Preserve meaningful technical terms/acronyms.
• Prefer action-noun phrasing (for example user-auth, bulk-export-audit-log).

1. Bootstrap feature branch and spec exactly once:

• Run scripts/create-new-feature.sh --json --short-name "<short-name>" "<feature description>".
• Do not manually pre-compute branch numbers; let the script assign the next number.
• Parse JSON output and capture:
• BRANCH_NAME
• SPEC_FILE
• FEATURE_NUM
• Derive FEATURE_DIR as dirname(SPEC_FILE).

1. Load template context:

• Preferred template: {REPO_ROOT}/templates/spec-template.md.
• Fallback template: assets/spec-template.md.
• Preserve heading order from the selected template.

1. Draft spec.md content (focus on WHAT/WHY, not HOW):

• Fill prioritized user stories with independent tests and acceptance scenarios.
• Write testable functional requirements.
• Add edge cases and scope boundaries.
• Add measurable, technology-agnostic success criteria.
• Include key entities when data is central.
• Use reasonable defaults and document assumptions when needed.

1. Clarification policy while drafting:

• First, make informed defaults using domain norms.
• Add [NEEDS CLARIFICATION: ...] only for high-impact uncertainty.
• Hard limit: at most 3 clarification markers.
• Prioritize by impact: scope > security/privacy > UX > technical detail.

1. Write the spec to SPEC_FILE.

1. Create and run requirements quality validation:

• Create FEATURE_DIR/checklists/requirements.md.
• Validate spec against this checklist:
• No implementation details (frameworks, languages, APIs, internal architecture).
• Mandatory sections are complete.
• Requirements are unambiguous and testable.
• Success criteria are measurable and technology-agnostic.
• User scenarios and edge cases are covered.
• Scope boundaries, dependencies, and assumptions are explicit.
• No unresolved [NEEDS CLARIFICATION] markers for plan-ready specs.
• If non-clarification issues fail, revise spec and re-validate (max 3 passes).

1. If clarification markers remain after validation:

• Ask up to 3 numbered clarification questions total.
• For each question, present 2-3 concrete options plus a short custom answer path.
• Wait for user responses, update spec.md, then re-run validation.

1. Report completion:

• Branch name.
• spec.md path.
• requirements.md path and pass/fail summary.
• Recommended next step:
• spec-kit-clarify if high-impact ambiguity remains.
• spec-kit-plan if ready.

Output

• Active feature branch from scripts/create-new-feature.sh
• specs/<feature>/spec.md
• specs/<feature>/checklists/requirements.md
• readiness handoff for spec-kit-clarify or spec-kit-plan

Common Mistakes

• Writing implementation design into the spec instead of user-visible behavior and outcomes.
• Leaving vague requirements that cannot be acceptance-tested.
• Asking too many clarification questions instead of making reasonable defaults.
• Running feature bootstrap script multiple times for one request.

References

• references/spec-kit-workflow.dot
• scripts/create-new-feature.sh
• assets/spec-template.md
• https://github.com/github/spec-kit/blob/9111699cd27879e3e6301651a03e502ecb6dd65d/templates/commands/specify.md