Skip to content

Commit 5cfa5e2

Browse files
bmadcodeclaude
bmadcode
and
claude
committed
docs: add Diataxis explanation and reference docs for BMad Builder
New explanation docs: - what-are-skills: universal skill format and open standard - what-are-bmad-agents: personas, memory, capabilities, autonomous mode - what-are-workflows: three workflow types, progressive disclosure, modes - progressive-disclosure: four layers of context loading - subagent-patterns: six orchestration patterns with common pitfalls - skill-authoring-best-practices: principles, quality dimensions, anti-patterns New/filled reference docs: - bmad-skill-manifest: complete field reference for bmad-manifest.json - builder-commands: all capabilities, phases, and modes for both builders - workflow-patterns: skill type taxonomy, decision tree, structure patterns Other changes: - Remove apps stub and how-to stubs (not ready yet) - Remove overhaul banner from README - Fix all broken cross-references - Surface design pattern docs on landing page - Add quick start placeholder Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent e83b98c commit 5cfa5e2

24 files changed

Lines changed: 1057 additions & 116 deletions

‎README.md‎

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,6 @@
44
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
55
[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
66

7-
> **🚧 OVERHAUL IN PROGRESS**
8-
>
9-
> BMad Builder is being overhauled. To help test and provide feedback on the new skills, copy any of the skill or sample folders from `skills/` or `samples/` directly into your tool's skills folder and activate them like any other skill.
10-
>
11-
> **Setup:** The `bmad-init` skill and `manifest-bmb` skill (both in `skills/`) should also be added — when workflows run, they will instruct you to set up a `_bmad` folder with a configuration file.
12-
>
13-
> **Note:** This module may be temporarily non-functional with the bmad main installer. It will be fixed and re-enabled on Friday, March 13, 2026.
14-
157
**Build More, Architect Dreams... With the BMad Builder!**
168

179
BMad Builder is so much more than a skill builder. BMad Method modules support:
@@ -64,8 +56,6 @@ Complete guides for building agents, workflows, and modules.
6456

6557
MIT — see [LICENSE](LICENSE) for details.
6658

67-
---
68-
6959
**BMad Builder** — Part of the [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD) ecosystem.
7060

7161
[![Contributors](https://contrib.rocks/image?repo=bmad-code-org/bmad-builder)](https://github.com/bmad-code-org/bmad-builder/graphs/contributors)

‎docs/explanation/index.md‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,22 @@ Create world-class AI agents and workflows with the BMad Builder.
99

1010
| Topic | Description |
1111
|-------|-------------|
12-
| **[What Are Agents](/explanation/what-are-bmad-agents.md)** | AI personas with specialized capabilities |
13-
| **[What Are Workflows](/explanation/what-are-workflows.md)** | Structured step-by-step processes and skills |
14-
| **[What Are Apps](/explanation/what-are-apps.md)** | Full applications built with BMad |
12+
| **[What Are Skills](/explanation/what-are-skills.md)** | The universal building block for everything BMad produces |
13+
| **[What Are Agents](/explanation/what-are-bmad-agents.md)** | AI personas with specialized capabilities and memory |
14+
| **[What Are Workflows](/explanation/what-are-workflows.md)** | Structured step-by-step processes and utilities |
1515

16-
## Quick Start
16+
## Design Patterns
17+
18+
| Topic | Description |
19+
|-------|-------------|
20+
| **[Progressive Disclosure](/explanation/progressive-disclosure.md)** | Four layers of context loading — from frontmatter through step files |
21+
| **[Subagent Patterns](/explanation/subagent-patterns.md)** | Six orchestration patterns for parallel and hierarchical work |
22+
| **[Skill Authoring Best Practices](/explanation/skill-authoring-best-practices.md)** | Core principles, common patterns, quality dimensions, and anti-patterns |
23+
24+
## Reference
1725

1826
| Resource | Description |
1927
|----------|-------------|
20-
| **[Create a Custom Agent](/how-to/create-custom-agent.md)** | Build your first AI agent |
21-
| **[Create Your First Workflow](/how-to/create-your-first-workflow.md)** | Design structured workflows |
28+
| **[Builder Commands](/reference/builder-commands.md)** | All capabilities, modes, and phases for both builders |
29+
| **[Skill Manifest](/reference/bmad-skill-manifest.md)** | Field reference for bmad-manifest.json |
30+
| **[Workflow Patterns](/reference/workflow-patterns.md)** | Skill types, structure patterns, and execution models |

‎docs/explanation/progressive-disclosure.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: "Progressive Disclosure in Skills"
3+
description: How to structure skills so they load only the context needed at each moment — from frontmatter through dynamic routing to step files
4+
---
5+
6+
Progressive disclosure is the technique that separates basic skills from powerful ones. The core idea: never load more context than the agent needs *right now*. This keeps token usage low, prevents context pollution, and makes skills survive long conversations.
7+
8+
## The Four Layers
9+
10+
Skills can use any combination of these layers. Most production skills use Layers 1-3. Layer 4 is reserved for strict sequential processes.
11+
12+
| Layer | What It Does | Token Cost |
13+
| ----- | ------------ | ---------- |
14+
| **1. Frontmatter vs Body** | Frontmatter is always in context; body loads only when triggered | ~100 tokens always, body on demand |
15+
| **2. On-Demand Resources** | SKILL.md points to resources and scripts loaded only when relevant | Zero until needed |
16+
| **3. Dynamic Routing** | SKILL.md acts as a router, dispatching to entirely different prompt flows | Only the chosen path loads |
17+
| **4. Step Files** | Agent reads one step at a time, never sees ahead | One step's worth at a time |
18+
19+
## Layer 1: Frontmatter vs Body
20+
21+
Frontmatter (name + description) is **always in context** — it is how the LLM decides whether to load the skill. The body only loads when the skill triggers.
22+
23+
This means frontmatter must be precise and include trigger phrases. The body stays under 500 lines and pushes detail into Layers 2-3.
24+
25+
```markdown
26+
---
27+
name: bmad-my-skill
28+
description: Validates API contracts against OpenAPI specs. Use when user says 'validate API' or 'check contract'.
29+
---
30+
31+
# Body loads only when triggered
32+
...
33+
```
34+
35+
## Layer 2: On-Demand Resources
36+
37+
SKILL.md points to resources loaded only when relevant. This includes both **reference files** (context for the LLM) and **scripts** (offload work from the LLM entirely).
38+
39+
```markdown
40+
## Which Guide to Read
41+
- Python project → Read `resources/python.md`
42+
- TypeScript project → Read `resources/typescript.md`
43+
- Need validation → Run `scripts/validate.py` (don't read the script, just run it)
44+
```
45+
46+
Scripts are particularly powerful here: the LLM does not process the logic, it just calls the script and receives structured output. This offloads deterministic work and saves tokens.
47+
48+
## Layer 3: Dynamic Routing
49+
50+
The skill body acts as a **router** that dispatches to entirely different prompt flows, scripts, or external skills based on what the user is asking for.
51+
52+
```markdown
53+
## What Are You Trying To Do?
54+
55+
### "Build a new workflow"
56+
→ Read `prompts/create-flow.md` and follow its instructions
57+
58+
### "Review an existing workflow"
59+
→ Read `prompts/review-flow.md` and follow its instructions
60+
61+
### "Run analysis"
62+
→ Run `scripts/analyze.py --target <path>` and present results
63+
```
64+
65+
The key difference from Layer 2: Layer 2 loads supplementary resources alongside the skill body. Layer 3 **branches the entire execution path** — different prompts, different scripts, different skills. The skill body becomes a dispatcher, not an instruction set.
66+
67+
## Layer 4: Step Files
68+
69+
The most restrictive pattern. The agent reads **one step file at a time**, does not know what is next, and waits for user confirmation before proceeding.
70+
71+
```
72+
prompts/
73+
├── step-01.md ← agent reads ONLY current step
74+
├── step-02.md ← loaded after user confirms step 1
75+
├── step-03a.md ← branching path A
76+
└── step-03b.md ← branching path B
77+
```
78+
79+
**When to use:** Only when you need exact sequential progression with no skipping, compaction-resistance (each step is self-contained), or the agent deliberately constrained from looking ahead.
80+
81+
**Trade-off:** Very rigid. Limits the agent's ability to adapt, combine steps, or be creative. Do not use for exploratory or creative tasks. Do not use when Layer 3 routing would suffice. Try to follow level 1-3 first! The lowest level needed is best.
82+
83+
:::tip[Start at Layer 2]
84+
Most skills only need Layers 1-2. Add Layer 3 when the skill genuinely handles multiple distinct operations. Add Layer 4 only for strict compliance or audit workflows where the agent must not skip ahead.
85+
:::
86+
87+
## Compaction Survival
88+
89+
Long-running workflows risk losing context when the conversation compresses. The **document-as-cache pattern** solves this: the output document itself stores the workflow's state.
90+
91+
| Component | Purpose |
92+
| --------- | ------- |
93+
| **YAML front matter** | Paths to input files, current stage status, timestamps |
94+
| **Draft sections** | Progressive content built across stages |
95+
| **Status marker** | Which stage is complete, for resumption |
96+
97+
Each stage reads the output document to restore context, does its work, and writes results back to the same document. If context compacts mid-workflow, the next stage recovers by reading the document and reloading the input files listed in front matter.
98+
99+
```markdown
100+
---
101+
title: "Analysis: Research Topic"
102+
status: "analysis"
103+
inputs:
104+
- "{project_root}/docs/brief.md"
105+
- "{project_root}/data/sources.json"
106+
---
107+
```
108+
109+
This avoids separate cache files, file collisions when running multiple workflows, and state synchronization complexity.
110+
111+
## Choosing the Right Layer
112+
113+
| Situation | Recommended Layer |
114+
| --------- | ----------------- |
115+
| Single-purpose utility with one path | Layer 1-2 |
116+
| Skill with conditional reference data | Layer 2 |
117+
| Skill that does multiple distinct things | Layer 3 |
118+
| Skill with stages that depend on each other | Layer 3 + compaction survival |
119+
| Strict sequential process, no skipping allowed | Layer 4 |
120+
| Long-running workflow producing a document | Layer 3 + document-as-cache |

‎docs/explanation/skill-authoring-best-practices.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
title: "Skill Authoring Best Practices"
3+
description: Core principles, common patterns, quality dimensions, and anti-patterns for writing effective BMad skills
4+
---
5+
6+
Practical guidance for writing skills that work reliably and adapt gracefully. These patterns apply to agents, workflows, and utilities alike.
7+
8+
## Core Principle: Informed Autonomy
9+
10+
Give the executing agent enough context to make good judgment calls — not just enough to follow steps. The test for every piece of content: "Would the agent make *better decisions* with this context?" If yes, keep it. If it is genuinely redundant, cut it.
11+
12+
Simple utilities need minimal context — input/output is self-explanatory. Interactive workflows need domain understanding, user perspective, and rationale for non-obvious choices. When in doubt, explain *why* — an agent that understands the mission improvises better than one following blind steps.
13+
14+
## Freedom Levels
15+
16+
Match specificity to task fragility.
17+
18+
| Freedom | When to Use | Example |
19+
| ------- | ----------- | ------- |
20+
| **High** (text instructions) | Multiple valid approaches, context-dependent | "Analyze structure, check for issues, suggest improvements" |
21+
| **Medium** (pseudocode/templates) | Preferred pattern exists, some variation OK | `def generate_report(data, format="markdown"):` |
22+
| **Low** (exact scripts) | Fragile operations, consistency critical | `python scripts/migrate.py --verify --backup` (do not modify) |
23+
24+
**Analogy:** Narrow bridge with cliffs = low freedom. Open field = high freedom.
25+
26+
## Quality Dimensions
27+
28+
Six dimensions to keep in mind during the build phase. The quality scanners check these automatically during optimization.
29+
30+
| Dimension | What It Means |
31+
| --------- | ------------- |
32+
| **Informed Autonomy** | Overview establishes domain framing, theory of mind, and design rationale — enough for judgment calls |
33+
| **Intelligence Placement** | Scripts handle plumbing (fetch, transform, validate). Prompts handle judgment (interpret, classify, decide). If a script contains an `if` that decides what content *means*, intelligence has leaked |
34+
| **Progressive Disclosure** | SKILL.md stays focused; stage instructions go in `prompts/`, reference data in `resources/` |
35+
| **Description Format** | Two parts: `[5-8 word summary]. [Use when user says 'X' or 'Y'.]` — default to conservative triggering |
36+
| **Path Construction** | Never use `{skill-root}`. Only use `{project-root}` for `_bmad` paths. Config variables used directly — they already contain `{project-root}` |
37+
| **Token Efficiency** | Remove genuine waste (repetition, defensive padding). Preserve context that enables judgment (domain framing, rationale) |
38+
39+
## Common Patterns
40+
41+
### Soft Gate Elicitation
42+
43+
For guided workflows, use "anything else?" soft gates at natural transition points instead of hard menus.
44+
45+
```markdown
46+
Present what you've captured so far, then:
47+
"Anything else you'd like to add, or shall we move on?"
48+
```
49+
50+
Users almost always remember one more thing when given a graceful exit ramp rather than a hard stop. This consistently produces richer artifacts than rigid section-by-section questioning. Use at every natural transition in collaborative discovery workflows. Skip in autonomous/headless execution.
51+
52+
### Intent-Before-Ingestion
53+
54+
Never scan artifacts or project context until you understand WHY the user is here. Without knowing intent, you cannot judge what is relevant in a 100-page document.
55+
56+
```markdown
57+
1. Greet and understand intent
58+
2. Accept whatever inputs the user offers
59+
3. Ask if they have additional context
60+
4. ONLY THEN scan artifacts, scoped to relevance
61+
```
62+
63+
### Capture-Don't-Interrupt
64+
65+
When users provide information beyond the current scope — dropping requirements during a product brief, mentioning platforms during vision discovery — capture it silently for later use rather than redirecting them.
66+
67+
Users in creative flow share their best insights unprompted. Interrupting to say "we'll cover that later" kills momentum and may lose the insight entirely.
68+
69+
### Dual-Output: Human Artifact + LLM Distillate
70+
71+
Any artifact-producing workflow can output two complementary documents: a polished human-facing artifact AND a token-conscious, structured distillate optimized for downstream LLM consumption.
72+
73+
| Output | Purpose |
74+
| ------ | ------- |
75+
| **Primary** | Human-facing document — concise, well-structured |
76+
| **Distillate** | Dense, structured summary for downstream LLM workflows — captures overflow, rejected ideas (so downstream does not re-propose them), detail bullets with enough context to stand alone |
77+
78+
The distillate bridges the gap between what belongs in the human document and what downstream workflows need. Always offered to the user, never forced.
79+
80+
### Three-Mode Architecture
81+
82+
Interactive workflows can offer three execution modes matching different user contexts.
83+
84+
| Mode | Trigger | Behavior |
85+
| ---- | ------- | -------- |
86+
| **Guided** | Default | Section-by-section with soft gates; drafts from what it knows, questions what it doesn't |
87+
| **YOLO** | `--yolo` or "just draft it" | Ingests everything, drafts complete artifact upfront, then walks user through refinement |
88+
| **Autonomous** | `--autonomous` / `-A` | Headless; takes inputs, produces artifact, no interaction |
89+
90+
Not every workflow needs all three — but considering them during design prevents painting yourself into a single interaction model.
91+
92+
### Parallel Review Lenses
93+
94+
Before finalizing any significant artifact, fan out multiple reviewers with different perspectives.
95+
96+
| Reviewer | Focus |
97+
| -------- | ----- |
98+
| **Skeptic** | What is missing? What assumptions are untested? |
99+
| **Opportunity Spotter** | What adjacent value? What angles? |
100+
| **Contextual** | LLM picks the best third lens for the domain (regulatory risk for healthtech, DX critic for devtools) |
101+
102+
Graceful degradation: if subagents are unavailable, the main agent does a single critical self-review pass.
103+
104+
### Graceful Degradation
105+
106+
Every subagent-dependent feature should have a fallback path. Skills run across different platforms, models, and configurations. A skill that hard-fails without subagents is fragile. A skill that gracefully falls back to sequential processing is robust everywhere.
107+
108+
### Verifiable Intermediate Outputs
109+
110+
For complex tasks: plan, validate, execute, verify.
111+
112+
1. Analyze inputs
113+
2. Create `changes.json` with planned updates
114+
3. Validate with script before executing
115+
4. Execute changes
116+
5. Verify output
117+
118+
Catches errors early, is machine-verifiable, and makes planning reversible.
119+
120+
## Writing Guidelines
121+
122+
| Do | Avoid |
123+
| -- | ----- |
124+
| Consistent terminology — one term per concept | Switching between "workflow" and "process" for the same thing |
125+
| Third person in descriptions — "Processes files" | First person — "I help process files" |
126+
| Descriptive file names — `form_validation_rules.md` | Sequence names — `doc2.md` |
127+
| Forward slashes in all paths | Backslashes or platform-specific paths |
128+
| One level deep for references — SKILL.md → resource.md | Nested references — SKILL.md → A.md → B.md |
129+
| Table of contents for files over 100 lines | Long files without navigation |
130+
131+
## Anti-Patterns
132+
133+
| Anti-Pattern | Fix |
134+
| ------------ | --- |
135+
| Too many options upfront | One default with escape hatch for edge cases |
136+
| Deep reference nesting (A→B→C) | Keep references one level from SKILL.md |
137+
| Inconsistent terminology | Choose one term per concept |
138+
| Vague file names | Name by content, not sequence |
139+
| Scripts that classify meaning via regex | Intelligence belongs in prompts, not scripts |
140+
| Over-optimization that flattens personality | Preserve phrasing that captures the intended voice |
141+
| Hard-failing when subagents are unavailable | Always include a sequential fallback path |

0 commit comments

Comments
 (0)