You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .claude-plugin/marketplace.json
+2-2Lines changed: 2 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -12,13 +12,13 @@
12
12
"name": "bmad-builder",
13
13
"source": "./",
14
14
"description": "Build AI agents, workflows, and modules from a conversation. Four skills — Agent Builder, Workflow Builder, Module Builder, and Setup — guide you from idea to production-ready skill structure with built-in quality optimization. Part of the BMad Method ecosystem.",
Copy file name to clipboardExpand all lines: docs/explanation/module-configuration.md
+67-18Lines changed: 67 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,9 @@ title: 'Module Configuration and the Setup Skill'
3
3
description: How BMad modules handle user configuration through a setup skill, when to use configuration vs. alternatives, and how to register with the help system
4
4
---
5
5
6
-
Every BMad module can include a **setup skill** that collects user preferences and registers the module's capabilities with the help system. The BMad Builder module's own setup skill (`bmad-builder-setup`) is the reference implementation.
6
+
BMad modules register their capabilities with the help system and optionally collect user preferences. Multi-skill modules use a dedicated **setup skill** for this. Single-skill standalone modules handle registration themselves on first run.
7
+
8
+
When you create your own custom module, you can choose to either add a configuration skill, or you could just add the feature to every skill following the standalone pattern. for modules with more than 1-2 skills, it would be recommended to just have a setup skill.
7
9
8
10
## When You Need Configuration
9
11
@@ -15,19 +17,32 @@ Most modules should not need configuration at all. Before adding configurable va
15
17
|**Agent memory**| Your module follows the agent pattern and the agent can learn preferences through conversation |
16
18
|**Configuration**| The value genuinely varies across projects and cannot be inferred at runtime |
17
19
18
-
:::tip[Standalone Skills and Agents]
19
-
If you are building a standalone agent or skill — not a multi-capability module — the setup skill overhead is not worth it. A concise overview section at the top of your SKILL.md body, clear comments in script headers, and `--help` flags on any CLI tools give users everything they need to discover and use the skill.
20
+
:::tip[Standalone Skills]
21
+
If you are building a single standalone agent or workflow, you do not need a separate setup skill. The Module Builder can package it as a **standalone self-registering module** — the registration logic is embedded directly in the skill via an `assets/module-setup.md` reference file, and runs on first activation or when the user passes `setup`/`configure`.
|**Configuration**| Collects user preferences and writes them to shared config files |
29
31
|**Help registration**| Adds the module's capabilities to the project-wide help system so users can discover them |
30
32
33
+
### Why Register with the Help System?
34
+
35
+
The `bmad-help` skill reads `module-help.csv` to understand what capabilities are available, detect which ones have been completed (by checking output locations for artifacts), and recommend next steps based on the dependency graph. Without registration, `bmad-help` cannot discover or recommend your module's capabilities beyond what it knows basically from skill headers. the help provides richer potential info such as args, relationship to other skills, inputs and outputs, and any other relevant authored information. also if you have a skill with multiple capabilities, they each have their own help entry.
|**Setup skill**| Multi-skill modules (2+ skills) | A dedicated `bmad-{code}-setup` skill handles registration for all skills |
42
+
|**Self-registration**| Single-skill standalone modules | The skill itself registers on first run or when user passes `setup`/`configure`|
43
+
44
+
The Module Builder detects which path to use based on what you give it — a folder of skills triggers the setup skill approach, a single skill triggers the standalone approach.
45
+
31
46
## Configuration Files
32
47
33
48
Setup skills write to three files in `{project-root}/_bmad/`:
@@ -42,7 +57,7 @@ Core settings (like `output_folder` and `document_output_language`) live at the
42
57
43
58
## The module.yaml File
44
59
45
-
Each module declares its identity and configurable variables in an `assets/module.yaml` inside the setup skill. This file drives both the prompts shown to the user and the values written to config.
60
+
Each module declares its identity and configurable variables in an `assets/module.yaml`file. For multi-skill modules, this lives inside the setup skill. For standalone modules, it lives in the skill's own `assets/` folder. This file drives both the prompts shown to the user and the values written to config.
46
61
47
62
```yaml
48
63
code: mymod
@@ -85,14 +100,42 @@ If these cover your discoverability needs, you can skip the setup skill entirely
85
100
86
101
## The module-help.csv File
87
102
88
-
The CSV asset registers the module's capabilities with the help system. Each row describes one capability that users can discover and invoke.
103
+
The CSV registers the module's capabilities with the help system. Each row describes one capability that users can discover and invoke. The file has 13 columns:
When the setup skill runs, it merges these rows into the project-wide `_bmad/module-help.csv`, replacing any existing rows for this module. This is how users find your module's commands through the help system.
| **module** | Module display name — groups entries in help output |
114
+
| **skill** | Skill folder name (e.g., `bmad-agent-builder`) — must match the actual directory name |
115
+
| **display-name** | User-facing label shown in help menus (e.g., "Build an Agent") |
116
+
| **menu-code** | 1-3 letter shortcode displayed as `[CODE]` in help — unique across the module, intuitive mnemonic |
117
+
| **description** | What this capability does — concise, action-oriented, specific enough for `bmad-help` to route correctly |
118
+
| **action** | Action name within the skill — distinguishes capabilities when one skill exposes multiple (e.g., `build-process`, `quality-optimizer`) |
119
+
| **args** | Arguments the capability accepts (e.g., `[-H] [path]`) — shown in help output |
120
+
| **phase** | When the capability is available — `anytime` or a workflow phase like `1-analysis`, `2-planning` |
121
+
| **after** | Capabilities that should complete before this one — format `skill-name:action`, comma-separated for multiple |
122
+
| **before** | Capabilities that should run after this one — same format as `after` |
123
+
| **required** | `true` if this is a blocking gate for phase progression, `false` otherwise |
124
+
| **output-location** | Config variable name (e.g., `output_folder`, `bmad_builder_reports`) — `bmad-help` resolves from config to scan for completion artifacts |
125
+
| **outputs** | File patterns `bmad-help` looks for in the output location to detect completion (e.g., "quality report", "agent skill") |
126
+
127
+
### How bmad-help Uses These Entries
128
+
129
+
The `after`/`before` columns create a **dependency graph** that `bmad-help` walks to recommend next steps. `required=true` entries are blocking gates — `bmad-help` will not suggest later-phase capabilities until required gates pass. The `output-location` and `outputs` columns enable **completion detection** — `bmad-help` scans those paths for matching artifacts to determine what's been done.
BMad Builder,bmad-agent-builder,Build an Agent,BA,"Create, edit, convert, or fix an agent skill.",build-process,"[-H] [description | path]",anytime,,bmad-agent-builder:quality-optimizer,false,output_folder,agent skill
136
+
```
137
+
138
+
During registration, these rows are merged into the project-wide `_bmad/module-help.csv`, replacing any existing rows for this module (anti-zombie pattern).
| **Ideate Module** | IM | Brainstorm and plan a module through facilitative discovery — produces a plan document |
169
+
| **Create Module** | CM | Package skills as an installable BMad module (setup skill or standalone self-registering)|
170
+
| **Validate Module** | VM | Check that a module's structure is complete, accurate, and properly registered |
128
171
129
-
**Typical workflow:**
172
+
**For a folder of skills (multi-skill module):**
130
173
131
-
1. Run **Ideate Module (IM)** to brainstorm and plan your module
174
+
1. Run **Ideate Module (IM)** to brainstorm and plan
132
175
2. Build each skill using the **Agent Builder (BA)** or **Workflow Builder (BW)**
133
-
3. Run **Create Module (CM)** to scaffold the setup skill into your skills folder
176
+
3. Run **Create Module (CM)** — it generates a dedicated `-setup` skill with `module.yaml`, `module-help.csv`, and merge scripts
134
177
4. Run **Validate Module (VM)** to verify everything is wired correctly
135
178
136
-
The Create Module path reads every skill in your folder, walks you through defining the module identity and capability entries, then generates a complete setup skill with `module.yaml`, `module-help.csv`, and all supporting scripts.
179
+
**For a single skill (standalone module):**
180
+
181
+
1. Build the skill using the **Agent Builder (BA)** or **Workflow Builder (BW)**
182
+
2. Run **Create Module (CM)** with the skill path — it embeds self-registration directly into the skill (`assets/module-setup.md`, `assets/module.yaml`, `assets/module-help.csv`) and generates a `marketplace.json` for distribution
183
+
3. Run **Validate Module (VM)** to verify
184
+
185
+
The Module Builder auto-detects single vs. multi-skill input and recommends the appropriate approach.
137
186
138
187
See **[What Are Modules](/explanation/what-are-modules.md)** for concepts and architecture decisions, or the **[Builder Commands Reference](/reference/builder-commands.md)** for detailed capability documentation.
Copy file name to clipboardExpand all lines: docs/explanation/what-are-modules.md
+29-13Lines changed: 29 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,20 +3,34 @@ title: 'What Are BMad Modules?'
3
3
description: How agents and workflows combine into installable, configurable modules within the BMad ecosystem
4
4
---
5
5
6
-
BMad modules package related agents and workflows into a cohesive, installable unit with shared configuration and help system registration.
6
+
BMad modules package agents and workflows into installable units with shared configuration and help system registration. A module can be a full suite of related skills or a single standalone skill that wants to be discoverable and configurable.
7
7
8
-
## What a Module Contains
8
+
## Distribution: Plugins and Marketplaces
9
+
10
+
At the distribution level, a BMad module is a **plugin** — a package of skills with a `.claude-plugin/` manifest. How you structure it depends on what you're shipping:
|**Single plugin**| One module (standalone or multi-skill) |`.claude-plugin/marketplace.json` with one plugin entry |
15
+
|**Marketplace**| A repo that ships multiple modules |`.claude-plugin/marketplace.json` with multiple plugin entries |
16
+
17
+
The `.claude-plugin/` convention originates from Claude Code, but the format works across all 43+ skills platforms supported by the upcoming BMad installer. You can also install directly using the NPX skill installer from Vercel, or through Anthropic's plugin system if targeting only Claude Code.
9
18
10
-
A module is a folder of skills — agents and/or workflows — plus a **setup skill** that handles installation and configuration.
19
+
The Module Builder generates the appropriate `marketplace.json` during the Create Module (CM) step - but you will want to verify it lists the proper relative paths to the skills you want to deliver with your module.
|**Skills**| Two or more agents/workflows | A single agent or workflow |
28
+
|**Registration**| Dedicated `bmad-{code}-setup` skill | Built into the skill itself (`assets/module-setup.md`) |
29
+
|**module.yaml**| In the setup skill's `assets/`| In the skill's own `assets/`|
30
+
|**module-help.csv**| In the setup skill's `assets/`| In the skill's own `assets/`|
31
+
|**Distribution**| Plugin with multiple skill folders | Plugin with single skill folder + `marketplace.json`|
32
+
33
+
For multi-skill modules, the setup skill is the glue — it registers all capabilities in one step. For standalone modules, the skill handles its own registration on first run or when the user passes `setup`/`configure`.
20
34
21
35
## Agent vs. Workflow vs. Both
22
36
@@ -69,7 +83,9 @@ Modules register with a project through three files in `{project-root}/_bmad/`:
69
83
|`config.user.yaml`| Personal settings (gitignored) — user name, language preferences |
70
84
|`module-help.csv`| Capability registry — one row per action users can discover |
71
85
72
-
Not every module needs configuration. If skills work with sensible defaults, the setup skill can focus purely on help registration. See **[Module Configuration](/explanation/module-configuration.md)** for details on when configuration adds value.
86
+
Registration is what makes a module visible to `bmad-help`. Without it, the help system cannot discover, recommend, or track completion of the module's capabilities.
87
+
88
+
Not every module needs configuration. If skills work with sensible defaults, registration can focus purely on help entries. See **[Module Configuration](/explanation/module-configuration.md)** for details on when configuration adds value and how the help CSV columns work.
73
89
74
90
## External Dependencies
75
91
@@ -94,7 +110,7 @@ Not every module needs a UI. But for complex modules with many capabilities, a v
94
110
The Module Builder (`bmad-module-builder`) provides three capabilities for the module lifecycle:
95
111
96
112
1.**Ideate Module (IM)** — Brainstorm and plan through creative facilitation
97
-
2.**Create Module (CM)** — Scaffold the setup skill into your skills folder
98
-
3.**Validate Module (VM)** — Verify structural integrity and entry quality
113
+
2.**Create Module (CM)** — Package skills as an installable module. Detects whether you have a folder of skills (generates a setup skill) or a single skill (embeds self-registration directly)
114
+
3.**Validate Module (VM)** — Verify structural integrity and entry quality for both multi-skill and standalone modules
99
115
100
116
See the **[Builder Commands Reference](/reference/builder-commands.md)** for detailed documentation on each capability.
0 commit comments