Shep Kit:New Feature
Use when starting any new feature, functionality, or enhancement. Triggers include "new feature", "start developing", "add functionality", "implement X", or explicit /shep-kit:new-feature invocation. Creates spec branch and scaffolds specification directory. Part of the Shep autonomous SDLC platform — https://shep.bot
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Shep Kit:New Feature when an AI agent needs a reusable SKILL.md workflow for this job: Use when starting any new feature, functionality, or enhancement. Triggers include "new feature", "start developing", "add functionality", "implement X", or explicit /shep-kit:new-feature invocation. Creates spec branch and scaffolds specification directory. Part of the Shep autonomous SDLC platform — https://shep.bot
When not to use it
Skip Shep Kit:New Feature when the task is outside the analysis category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/shep-kitnew-feature # Save SKILL.md to ~/.claude/skills/shep-kitnew-feature/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/shep-kitnew-feature/SKILL.md. For a shared project, commit the folder at .claude/skills/shep-kitnew-feature/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Shep Kit:New Feature skill for this task: Use Shep Kit:New Feature when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 62/100
- Source signals
- 72/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Create New Feature Specification
Start spec-driven development by creating a feature branch and specification directory.
**Full workflow guide:** [docs/development/spec-driven-workflow.md](../../../docs/development/spec-driven-workflow.md)
## Phase Lifecycle
``` Requirements → Research → Planning → Implementation → Complete ↓ ↓ ↓ ↓ ↓ spec.yaml research.yaml plan.yaml tasks.yaml all files ↓ ↓ ↓ ↓ ↓ spec.md research.md plan.md tasks.md (auto-generated) ```
**CRITICAL:** Each phase MUST update the `Phase` status field before proceeding.
**IMPORTANT:** Edit YAML files, not Markdown.
## Workflow
### 1. Gather Minimal Input
Ask the user for:
- **Feature name** (kebab-case, e.g., `user-authentication`) - **One-liner description** (brief summary)
### 2. Create Branch
```bash # Determine next number NEXT_NUM=$(ls -d specs/[0-9][0-9][0-9]-* 2>/dev/null | wc -l | xargs printf "%03d" $(($ + 1))) # If no specs exist, use 001 [ -z "$NEXT_NUM" ] && NEXT_NUM="001"
# Create branch from main git checkout main && git pull git checkout -b "feat/${NEXT_NUM}-${FEATURE_NAME}" ```
### 3. Run Init Script
Execute the scaffolding script:
```bash .claude/skills/shep-kit-new-feature/scripts/init-feature.sh <NNN> <feature-name> ```
This creates `specs/NNN-feature-name/` with all template files using a **YAML-first** approach:
- **YAML source files**: `spec.yaml`, `research.yaml`, `plan.yaml`, `tasks.yaml` (source of truth) - **Markdown files**: `spec.md`, `research.md`, `plan.md`, `tasks.md` (auto-generated from YAML) - **Status tracking**: `feature.yaml` (implementation status, unchanged)
### 4. Analyze Context
Before filling the spec, analyze:
- **Existing specs**: Read `specs/*/spec.yaml` (or `specs/*/spec.md`) to understand feature landscape and discover dependencies - **Codebase**: Identify affected areas, patterns, existing implementations - **Cross-reference**: Infer dependencies, impact areas, size estimate
### 5. Propose Spec Content
Fill the template placeholders with inferred values:
- Problem statement (from user description + context) - Success criteria (inferred from scope) - Affected areas with impact levels (from codebase analysis) - Dependencies on other features (from existing specs) - Size estimate with reasoning (S/M/L/XL) - Open questions (gaps identified during analysis)
Present the proposed spec to the user for review.
### 6. User Confirms/Adjusts
Allow the user to:
- Approve the proposed spec - Modify any inferred values - Add missing context or requirements
### 7. Write Spec & Update feature.yaml
```bash # Write confirmed content to spec.yaml (the source of truth)
# feature.yaml already created by init script with initial state: # - lifecycle: "research" # - phase: "research" # - checkpoint: "feature-created" # See: docs/development/feature-yaml-protocol.md for details
# Stage and commit (both YAML source and generated Markdown) git add specs/NNN-feature-name/ git commit -m "feat(specs): add NNN-feature-name specification" ```
**IMPORTANT:** Always edit `spec.yaml`. Never hand-edit Markdown spec files.
**feature.yaml Status**: Already initialized by init script. No manual updates needed at this stage.
### 8. Next Steps
Inform the user:
> Spec created on `feat/NNN-feature-name`! > Next: `/shep-kit:research` to analyze technical approach.
## Open Questions Policy
**CRITICAL:** Open questions in `spec.yaml` (the `openQuestions` array) MUST be resolved before `/shep-kit:research`.
- If questions are identified, add them to the `openQuestions` array in `spec.yaml` - User must confirm answers or mark the array empty (`openQuestions: []`) - Research phase will REFUSE to proceed if unresolved open questions exist in `spec.yaml`
## Key Principles
- **Branch first**: All spec work happens on the feature branch - **Infer, don't interrogate**: Analyze codebase to propose smart defaults - **Dependencies from specs**: Scan existing `specs/*/spec.yaml` for relationships - **User confirms**: Always get approval before writing files - **Open questions block progress**: Never proceed with unresolved questions
## Template Location
Templates are in: `.claude/skills/shep-kit-new-feature/templates/`
### YAML Templates (Source of Truth)
- `spec.yaml` - Feature specification - `research.yaml` - Technical decisions - `plan.yaml` - Implementation strategy - `tasks.yaml` - Task breakdown
### Other Templates
- `data-model.md` - Domain models - `feature.yaml` - Status tracking
## feature.yaml Protocol
All shep-kit skills update `feature.yaml` as work progresses.
**Reference:** [docs/development/feature-yaml-protocol.md](../../../docs/development/feature-yaml-protocol.md)
**This skill's responsibility:**
- Create initial `feature.yaml` with: - `lifecycle: "research"` - `phase: "research"` - Checkpoint: "feature-created"
## Example
See: `.claude/skills/shep-kit-new-feature/examples/001-sample-feature/`
Intended uses
- Use Shep Kit:New Feature when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.