A Claude Code skill for creating detailed feature specifications and implementation plans.
When you ask Claude Code to plan a feature, design a specification, or prepare an implementation plan, this skill produces a structured, testable spec that includes:
- User Stories & Acceptance Criteria — prioritised stories with Given-When-Then acceptance scenarios
- BDD Scenarios — formal behaviour-driven development scenarios with full traceability back to user stories
- Test-Driven Development Plan — tests designed before code, ordered by dependency (unit -> integration -> E2E)
- Test Datasets — comprehensive data covering boundary conditions, edge cases, and error scenarios
- Functional Requirements & Success Criteria — measurable, testable requirements with unique IDs
- Traceability Matrix — links requirements to user stories, BDD scenarios, and tests so nothing falls through the cracks
Copy the .claude/skills/plan-spec/ directory into your project's .claude/skills/ folder, or clone this repo and symlink it.
# Option 1: Clone into your project
git clone git@github.com:nixlim/claude-skill-plan-spec.git
cp -r claude-skill-plan-spec/.claude/skills/plan-spec /your-project/.claude/skills/
# Option 2: Symlink
git clone git@github.com:nixlim/claude-skill-plan-spec.git ~/claude-skill-plan-spec
mkdir -p /your-project/.claude/skills
ln -s ~/claude-skill-plan-spec/.claude/skills/plan-spec /your-project/.claude/skills/plan-spec
In Claude Code, trigger the skill with natural language:
> Plan a password reset feature
> Write a spec for the user onboarding flow
> Design the API for inventory management
Or point it at an existing brief:
> Plan the feature described in docs/rfcs/search-v2.md
The skill follows a six-phase process:
- Discovery — Asks clarifying questions about actors, scope, constraints, and integrations. Waits for your confirmation before proceeding.
- User Stories — Writes prioritised stories with acceptance scenarios in Given-When-Then format.
- BDD Scenarios — Expands acceptance criteria into formal scenarios categorised as Happy Path, Alternate Path, Error Path, or Edge Case.
- TDD Plan — Designs tests before implementation, with datasets covering boundaries, edge cases, and errors.
- Requirements — Defines functional requirements (MUST/SHOULD/MAY) and measurable success criteria.
- Output — Assembles everything into a single markdown spec file with a full traceability matrix.
.claude/skills/plan-spec/
├── SKILL.md # Main skill instructions
├── bdd-template.md # BDD scenario format and rules
├── spec-template.md # Output document structure
├── test-dataset-template.md # Test dataset construction reference
└── examples/
└── sample-output.md # Complete example of expected output
MIT