Learn-skills.dev spec-kit-specify

Use when a Spec Kit feature needs `spec.md` authored or rewritten from natural-language requirements, especially when the feature has no usable specification or requirements are too vague for planning.

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/ahgraber/skills/spec-kit-specify" ~/.claude/skills/neversight-learn-skills-dev-spec-kit-specify && rm -rf "$T"

manifest: data/skills-md/ahgraber/skills/spec-kit-specify/SKILL.md

source content

Spec Kit Specify

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

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

Normalize input:
- Treat the full user request as the feature description.
- If empty, stop:
```
ERROR: No feature description provided
```
  .
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
```
  ).
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)
```
  .
Load template context:
- Preferred template:
```
{REPO_ROOT}/templates/spec-template.md
```
  .
- Fallback template:
```
assets/spec-template.md
```
  .
- Preserve heading order from the selected template.
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.
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.
Write the spec to
```
SPEC_FILE
```
.
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).
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.
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