bmad-spec

Distills ideas, PRDs, and transcripts into a five-field SPEC.md contract with companion files.

Updated Sep 4, 2026
One-click install
npx skills add https://github.com/Joao-Victor-Medeiros/save-sc --skill bmad-spec-joao-victor-medeiros
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: bmad-spec
Source: https://github.com/Joao-Victor-Medeiros/save-sc/tree/main/.agents/skills/bmad-spec
Command: npx skills add https://github.com/Joao-Victor-Medeiros/save-sc --skill bmad-spec-joao-victor-medeiros

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes assets (resource) components.

What problem does it solve? Raw intent — vague ideas, brain dumps, PRDs, meeting transcripts, or mixed notes — is too unstructured for downstream planning and development skills to consume reliably. This Skill condenses any input into a canonical SPEC.md kernel (Why, Capabilities, Constraints, Non-goals, Success signal) plus companion files, creating a single machine-readable contract. ## Core Features & Use Cases - Spec distillation: Transforms any intent input into the five-field kernel, routing overflow content (glossaries, diagrams, entity catalogs) into named companion files. - Update and validation: Re-derives specs from an append-only .memlog.md memory log, preserving stable capability IDs, and runs a two-pass self-validation against eight Spec Law rules. - Story breakdown: Optionally breaks a spec into a stories.yaml file of independently shippable slices with human-set checkpoints. - Use Case: Paste a messy Slack thread about a new feature and receive a spec folder containing SPEC.md, a glossary companion, and a validated decision log that downstream PRD, UX, and architecture skills can build from. ## Quick Start Ask the AI to distill the attached product brief into a spec using the bmad-spec skill.

Frequently Asked Questions about bmad-spec

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

FAQPage Schema
How do I turn a PRD or brain dump into a structured spec?▼

Provide the file path or paste the content and ask for a spec. The skill distills it into SPEC.md with five fields — Why, Capabilities, Constraints, Non-goals, Success signal — and routes overflow content into named companion files.

How do I break a spec into development stories?▼

Run the skill interactively on an existing spec folder and request story breakdown. It walks capabilities with you conversationally and writes stories.yaml with per-story checkpoints and dispatch notes.

Can I update an existing spec without losing capability IDs?▼

Yes. Invoking the skill with the same slug targets the existing spec folder and updates it in place. Capability IDs are preserved from the append-only .memlog.md log, and retired IDs are never reused.

What happens when the input is too vague to spec?▼

The skill stops rather than inventing content. In headless mode it returns a JSON error with code insufficient_intent; interactively it suggests running a PRD skill first to draw out the vision.

Does the skill work in headless or programmatic mode?▼

Yes. When invoked without a TTY or by another skill, it runs headless and returns a small JSON object with status and the list of files written, or a blocked status with a defined error code.