| title | Module Configuration and Registration |
|---|---|
| description | How BMad modules register with the help system, collect user preferences, and decide between root-placement, setup-skill, and self-registering layouts |
BMad modules register their capabilities with the help system and optionally collect user preferences. The recommended layout is root placement: module.yaml and module-help.csv at the module root, installed via the BMad installer. Setup skills and self-registering single-skill modules are alternative layouts for direct-download distribution.
Most modules should not need configuration at all. Before adding configurable values, consider whether a simpler alternative exists.
| Approach | When to Use |
|---|---|
| Sensible defaults | The variable has one clearly correct answer for most users that could be overridden or updated by the specific skill that needs it the first time it runs |
| Agent memory | Your module follows the agent pattern and the agent can learn preferences through conversation |
| Configuration | The value genuinely varies across projects and cannot be inferred at runtime |
:::tip[Most Modules Don't Need a Setup Skill]
Putting module.yaml and module-help.csv at the module root is sufficient for any module distributed through the BMad installer. The setup skill exists as an alternative for authors who want their module installable by direct download (no installer required); it bundles the registration scripts into a skill so the user can run setup to register the module manually.
:::
Module configuration (this doc) and per-skill customization (customize.toml) are different surfaces with different jobs. Configuration is about install-time answers: paths, language, team preferences, per-module install answers, and the agent roster. You still author module.yaml as the source of truth; at install the installer flows module-level answers and the agents: roster into _bmad/config.toml (and config.user.toml for user-scoped answers) at the project root, where many skills consume them. Customization is about per-skill behavior overrides: activation hooks, persistent facts, swappable templates. It lives in _bmad/custom/{skill-name}.toml and is scoped to one skill.
Use configuration when the value is cross-cutting (every skill needs to know the output folder). Use customization when the value shapes one skill's behavior (this workflow's brief template). Some values legitimately fit both surfaces; the End-User Customization Guide includes a decision table for that case. For the author-side decision about whether to expose customization at all, see Customization for Authors.
Module registration serves two purposes:
| Purpose | What Happens |
|---|---|
| Configuration | Collects user preferences and writes them to shared config files |
| Help registration | Adds the module's capabilities to the project-wide help system so users can discover them |
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 system provides richer detail: arguments, relationships to other skills, inputs and outputs, and any other authored metadata. If a skill has multiple capabilities, each one gets its own help entry.
The BMad installer resolves manifests in priority order:
| Layout | When to Use | Where Manifests Live |
|---|---|---|
| Root (default) | Distribution via the BMad installer; all headless installs | <module>/module.yaml, <module>/module-help.csv |
| Setup skill | Multi-skill modules distributed by direct download (no installer) | <module>/{code}-setup/assets/ |
| Self-registering skill | Single-skill modules distributed by direct download | <skill>/assets/ with module-setup.md |
Root placement is the default because it reflects what these files are: registration metadata for the module as a whole, not runtime state for any one skill. The installer picks them up automatically. The setup-skill and self-registering layouts are for the case where users install by copying the folder into their project rather than running the installer; the registration scripts ship inside a skill so the user can trigger registration by running it.
Module registration writes to three files in {project-root}/_bmad/:
| File | Scope | Contains |
|---|---|---|
config.yaml |
Shared, committed to git | Core settings at root level, plus a section per module with metadata and module-specific values |
config.user.yaml |
Personal, gitignored | User-only settings like user_name and communication_language |
module-help.csv |
Shared, committed to git | One row per capability the module exposes |
Core settings (like output_folder and document_output_language) live at the root of config.yaml and are shared across all modules. Each module also gets its own section keyed by its module code.
Each module declares its identity and configurable variables in a module.yaml file. The recommended location is the module root, alongside module-help.csv and the skill folders. For modules distributed by direct download, the file can instead live inside a setup skill's assets/ (multi-skill) or the skill's own assets/ (standalone). This file drives both the prompts shown to the user and the values written to config.
code: mymod
name: 'My Module'
description: 'What this module does'
module_version: 1.0.0
default_selected: false
module_greeting: >
Welcome message shown after setup completes.
my_output_folder:
prompt: 'Where should output be saved?'
default: '{project-root}/_bmad-output/my-module'
result: '{project-root}/{value}'Variables with a prompt field are presented to the user during setup. The default value is used when the user accepts defaults. Adding user_setting: true to a variable routes it to config.user.yaml instead of the shared config.
:::caution[Literal Token]
{project-root} is a literal token in config values. Never substitute it with an actual path. It signals to the consuming tool that the value is relative to the project root.
:::
You may not need any configurable values but still want to register your module with the help system. Registration is still worthwhile when:
- The skill description in SKILL.md frontmatter cannot fully convey what the module offers while staying concise
- You want to express capability sequencing, phase constraints, or other metadata the CSV supports
- An agent has many internal capabilities that users should be able to discover
- Your module has more than about three distinct things it can do
For simpler cases, these alternatives are often sufficient:
| Alternative | What It Provides |
|---|---|
| SKILL.md overview section | A concise summary at the top of the skill body; the --help system scans this section to present user-facing help, so keep it succinct |
| Script header comments | Describe purpose, usage, and flags at the top of each script |
If these cover your discoverability needs, you can skip module-level registration entirely and just ship the skill.
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:
module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs| Column | Purpose |
|---|---|
| module | Module display name. Groups entries in help output |
| skill | Skill folder name (e.g., bmad-agent-builder); must match the actual directory name |
| display-name | User-facing label shown in help menus (e.g., "Build an Agent") |
| menu-code | 1-3 letter shortcode displayed as [CODE] in help, unique across the module, intuitive mnemonic |
| description | What this capability does. Concise, action-oriented, specific enough for bmad-help to route correctly |
| action | Action name within the skill. Distinguishes capabilities when one skill exposes multiple (e.g., build-process, quality-optimizer) |
| args | Arguments the capability accepts (e.g., [-H] [path]), shown in help output |
| phase | When the capability is available: anytime or a workflow phase like 1-analysis, 2-planning |
| after | Capabilities that should complete before this one: format skill-name:action, comma-separated for multiple |
| before | Capabilities that should run after this one, same format as after |
| required | true if this is a blocking gate for phase progression, false otherwise |
| output-location | Config variable name (e.g., output_folder, bmad_builder_reports); bmad-help resolves from config to scan for completion artifacts |
| outputs | File patterns bmad-help looks for in the output location to detect completion (e.g., "quality report", "agent skill") |
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.
module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
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 skillDuring registration, these rows are merged into the project-wide _bmad/module-help.csv, replacing any existing rows for this module (anti-zombie pattern).
Both merge scripts use an anti-zombie pattern: before writing new values for a module, they remove all existing entries for that module's code. This prevents stale configuration or help entries from persisting across module updates. Running setup a second time is always safe.
After config data is migrated and individual files are cleaned up by the merge scripts, a separate cleanup step removes the installer's per-module directory trees from _bmad/. These directories contain skill files that are already installed in the tool's skills directory. They are redundant once the config has been consolidated.
Before removing any directory, the cleanup script verifies that every skill it contains exists at the installed location. Directories without skills (like _config/) are removed directly. The script is idempotent; running setup again after cleanup is safe.
Configuration is for basic, project-level settings: output folders, language preferences, feature toggles. Keep the number of configurable values small.
| Pattern | Configuration Role |
|---|---|
| Agent pattern | Prefer agent memory for per-user preferences. Use config only for values that must be shared across the project |
| Workflow pattern | Use config for output locations and behavior switches that vary across projects |
| Skill-only pattern | Use config sparingly. If the skill works with sensible defaults, skip config entirely |
Extensive workflow customization (step overrides, conditional branching, template selection) is a separate concern and will be covered in a dedicated document.
The Module Builder (bmad-module-builder) automates module creation. It offers three capabilities:
| Capability | Menu Code | What It Does |
|---|---|---|
| Ideate Module | IM | Brainstorm and plan a module through facilitative discovery; produces a plan document |
| Create Module | CM | Package skills as an installable BMad module (setup skill or standalone self-registering) |
| Validate Module | VM | Check that a module's structure is complete, accurate, and properly registered |
Standard flow:
- Run Ideate Module (IM) to brainstorm and plan (optional)
- Build each skill using the Agent Builder (BA) or Workflow Builder (BW)
- Run Create Module (CM) to generate
module.yaml,module-help.csv, and.claude-plugin/marketplace.jsonfor the module - Run Validate Module (VM) to verify everything is wired correctly
If you need direct-download distribution (users install by copying the folder rather than using the installer), the builder can also generate a setup skill or embed self-registration into a single skill. Tell Create Module which layout you want during the conversation.
See What Are Modules for concepts and architecture decisions, or the Builder Commands Reference for detailed capability documentation.