bmad-create-story

Generates comprehensive developer story files from epics, architecture, and sprint status.

Updated Sep 3, 2026
One-click install
npx skills add https://github.com/watchthelight/shatterfish --skill bmad-create-story-watchthelight
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-create-story
Source: https://github.com/watchthelight/shatterfish/tree/main/.claude/skills/bmad-create-story
Command: npx skills add https://github.com/watchthelight/shatterfish --skill bmad-create-story-watchthelight

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Developer agents often fail due to missing context: wrong libraries, wrong file locations, broken regressions, and vague requirements. This Skill creates a complete, self-contained story file that gives the dev agent everything needed for implementation, drawing from epics, PRD, architecture, UX docs, previous stories, and git history. ## Core Features & Use Cases - Story Auto-Discovery: Reads sprint-status.yaml to find the next backlog story, or accepts an explicit epic-story number like 1-2-user-auth. - Exhaustive Context Gathering: Loads epics, architecture, UX, and previous story learnings via a discover-inputs protocol with sharded and whole-file strategies. - Quality Validation: Validates the generated story against a checklist that hunts for missing requirements, regression risks, and LLM-optimization issues before finalizing. - Use Case: A team using the BMad method runs this workflow to turn a backlog epic entry into a ready-for-dev story file with acceptance criteria, architecture guardrails, and testing requirements, then hands it to a dev-story agent. ## Quick Start Ask the agent to create the next story from the sprint backlog, or specify an epic-story number such as 2-4 to generate that story file. Note: this Skill is deprecated in favor of bmad-build and should only be used when explicitly invoked by name.

Frequently Asked Questions about bmad-create-story

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a developer story file from an epic?

Provide an epic-story number like 1-2-user-auth, or let the workflow auto-discover the first backlog story in sprint-status.yaml. It loads epics, architecture, and previous story context, then writes a ready-for-dev story file.

What inputs does the create-story workflow need?

It reads sprint-status.yaml plus planning artifacts: epics, PRD, architecture, and UX documents, in whole or sharded form. Missing files are tolerated, but at least a story source and sprint status are expected.

Can I customize the story creation workflow per project?

Yes. A customize.toml in the skill directory provides defaults, and team or user TOML overrides under _bmad/custom merge structurally to add activation steps, persistent facts, or an on-complete action.

Why is bmad-create-story marked deprecated?

The frontmatter states bmad-build is now the official implementation method. This skill remains available only when explicitly invoked by name for backward compatibility with existing BMad workflows.

What happens if no backlog story exists in sprint-status.yaml?

The workflow halts and suggests running sprint-planning to refresh tracking, using correct-course to add stories, or running a retrospective if the sprint is complete.