Skip to main content
Agent skill

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 started

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?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/shep-kitnew-feature
# Save SKILL.md to ~/.claude/skills/shep-kitnew-feature/SKILL.md
  1. 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.
  2. 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.
  3. 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.

Starter prompt
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.