Skill
Development
Skill
/spec
Create specifications from requirements
Install
$ npx -y skills add bitcraft-apps/spec-first --skill spec --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/spec
Context preview
The summary Claude sees to decide when to auto-load this skill.
Create specifications from requirements
SKILL.md
spec.SKILL.mdname: spec
description: Create specifications from requirements
disable-model-invocation: true
argument-hint: "[REQUIREMENTS]"
Spec Command
Creates a specification from requirements. One agent does the steps in order.
Usage
`/sf:spec [REQUIREMENTS]`
Context
Read the current branch, the last 5 commits, and the working tree. Check whether `.sf/spec.md` exists.
Clarification Check
If the requirements are vague (fewer than 15 words, or unclear), ask the user before you start. Wait for the answer. Do not assume. Ask about:
- What specific problem are you solving?
- Who are the users?
- What's the desired outcome?
- Any technical constraints?
- What's the minimal viable version?
Directory Management
The working directory is `.sf/`. `$SF_DIR` overrides it.
Pick the mode:
- No `.sf/spec.md` → `first`
- `.sf/spec.md` exists → ask the user: "Update existing" / "Create new" → `update` / `new`
Run `scripts/spec-dir.sh <first|update|new>`, in this skill directory. **If spec-dir.sh fails (non-zero exit), halt immediately — do not do the work below.**
Execution
Write each file in turn. The requirements are the input to this skill.
1. `.sf/research/scope.md` — the narrowest viable change. Exclude what is not needed now. 2. `.sf/research/criteria.md` — the simplest testable pass/fail conditions. 3. `.sf/research/risks.md` — blockers only, not every possible risk. 4. `$SF_DIR/spec.md` — merge the three files. Keep it under 50 lines. Use the structure in `spec-template.md`, next to this file.
**Gate — Post-Spec:** run `scripts/validate-spec.sh`, in this skill directory. **If it fails (non-zero exit), add the sections it names, then run it again. Do not report done.**
Output: `$SF_DIR/spec.md` (direct file or symlink to timestamped spec)
Say: "Spec written to `{output path}`. Run `/sf:implement` to build it."
On Claude Code
Claude Code runs one schema-checked combined research call by default, then synthesis. The combined result supplies scope, criteria, and risks without research files. Set `parallelResearch: true` in the workflow input to run steps 1 to 3 as three parallel research calls.
Context arrives for free:
- Branch: !`git branch --show-current 2>/dev/null`
- Recent commits: !`git log --oneline -5 2>/dev/null`
- Working tree: !`git status --short 2>/dev/null | head -20`
- Existing spec: !`test -f .sf/spec.md && echo "yes" || echo "no"`
- Use the **AskUserQuestion** tool for both questions above, so execution pauses for the answer.
- Bash: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/spec-dir.sh $MODE ${CLAUDE_PROJECT_DIR:+$CLAUDE_PROJECT_DIR/.sf}`
- Workflow tool, `name: "sf-spec"`. Pass `args` as a JSON object, never as a string:
`{"requirements": "$ARGUMENTS", "specPath": "<the spec.md path above>", "templatePath": "${CLAUDE_SKILL_DIR}/spec-template.md"}`. `parallelResearch` is a boolean and defaults to `false`; set it to `true` for three parallel research calls.
- Gate: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate-spec.sh ${CLAUDE_PROJECT_DIR:+$CLAUDE_PROJECT_DIR/.sf}`
Read more
name: spec description: Create specifications from requirements disable-model-invocation: true argument-hint: "[REQUIREMENTS]"
Spec Command
Creates a specification from requirements. One agent does the steps in order.
Usage
`/sf:spec [REQUIREMENTS]`
Context
Read the current branch, the last 5 commits, and the working tree. Check whether `.sf/spec.md` exists.
Clarification Check
If the requirements are vague (fewer than 15 words, or unclear), ask the user before you start. Wait for the answer. Do not assume. Ask about:
- What specific problem are you solving?
- Who are the users?
- What's the desired outcome?
- Any technical constraints?
- What's the minimal viable version?
Directory Management
The working directory is `.sf/`. `$SF_DIR` overrides it.
Pick the mode:
- No `.sf/spec.md` → `first`
- `.sf/spec.md` exists → ask the user: "Update existing" / "Create new" → `update` / `new`
Run `scripts/spec-dir.sh <first|update|new>`, in this skill directory. **If spec-dir.sh fails (non-zero exit), halt immediately — do not do the work below.**
Execution
Write each file in turn. The requirements are the input to this skill.
1. `.sf/research/scope.md` — the narrowest viable change. Exclude what is not needed now. 2. `.sf/research/criteria.md` — the simplest testable pass/fail conditions. 3. `.sf/research/risks.md` — blockers only, not every possible risk. 4. `$SF_DIR/spec.md` — merge the three files. Keep it under 50 lines. Use the structure in `spec-template.md`, next to this file.
**Gate — Post-Spec:** run `scripts/validate-spec.sh`, in this skill directory. **If it fails (non-zero exit), add the sections it names, then run it again. Do not report done.**
Output: `$SF_DIR/spec.md` (direct file or symlink to timestamped spec)
Say: "Spec written to `{output path}`. Run `/sf:implement` to build it."
On Claude Code
Claude Code runs one schema-checked combined research call by default, then synthesis. The combined result supplies scope, criteria, and risks without research files. Set `parallelResearch: true` in the workflow input to run steps 1 to 3 as three parallel research calls.
Context arrives for free:
- Branch: !`git branch --show-current 2>/dev/null`
- Recent commits: !`git log --oneline -5 2>/dev/null`
- Working tree: !`git status --short 2>/dev/null | head -20`
- Existing spec: !`test -f .sf/spec.md && echo "yes" || echo "no"`
- Use the **AskUserQuestion** tool for both questions above, so execution pauses for the answer.
- Bash: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/spec-dir.sh $MODE ${CLAUDE_PROJECT_DIR:+$CLAUDE_PROJECT_DIR/.sf}`
- Workflow tool, `name: "sf-spec"`. Pass `args` as a JSON object, never as a string:
`{"requirements": "$ARGUMENTS", "specPath": "<the spec.md path above>", "templatePath": "${CLAUDE_SKILL_DIR}/spec-template.md"}`. `parallelResearch` is a boolean and defaults to `false`; set it to `true` for three parallel research calls.
- Gate: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate-spec.sh ${CLAUDE_PROJECT_DIR:+$CLAUDE_PROJECT_DIR/.sf}`
Ships withsf
Write the requirements before you write the code. Spec First gives you a workflow with three steps. First, define what to build. Then implement it from the spec. Last, generate the documentation. All steps run in your terminal.
Get the whole plugin