|
| 1 | +--- |
| 2 | +title: "Module Configuration and the Setup Skill" |
| 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 | +--- |
| 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. |
| 7 | + |
| 8 | +## When You Need Configuration |
| 9 | + |
| 10 | +Most modules should not need configuration at all. Before adding configurable values, consider whether a simpler alternative exists. |
| 11 | + |
| 12 | +| Approach | When to Use | |
| 13 | +| -------- | ----------- | |
| 14 | +| **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 | |
| 15 | +| **Agent memory** | Your module follows the agent pattern and the agent can learn preferences through conversation | |
| 16 | +| **Configuration** | The value genuinely varies across projects and cannot be inferred at runtime | |
| 17 | + |
| 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 | +::: |
| 21 | + |
| 22 | +## What the Setup Skill Does |
| 23 | + |
| 24 | +A setup skill serves two purposes: |
| 25 | + |
| 26 | +| Purpose | What Happens | |
| 27 | +| ------- | ------------ | |
| 28 | +| **Configuration** | Collects user preferences and writes them to shared config files | |
| 29 | +| **Help registration** | Adds the module's capabilities to the project-wide help system so users can discover them | |
| 30 | + |
| 31 | +## Configuration Files |
| 32 | + |
| 33 | +Setup skills write to three files in `{project-root}/_bmad/`: |
| 34 | + |
| 35 | +| File | Scope | Contains | |
| 36 | +| ---- | ----- | -------- | |
| 37 | +| `config.yaml` | Shared, committed to git | Core settings at root level, plus a section per module with metadata and module-specific values | |
| 38 | +| `config.user.yaml` | Personal, gitignored | User-only settings like `user_name` and `communication_language` | |
| 39 | +| `module-help.csv` | Shared, committed to git | One row per capability the module exposes | |
| 40 | + |
| 41 | +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. |
| 42 | + |
| 43 | +## The module.yaml File |
| 44 | + |
| 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. |
| 46 | + |
| 47 | +```yaml |
| 48 | +code: mymod |
| 49 | +name: "My Module" |
| 50 | +description: "What this module does" |
| 51 | +module_version: 1.0.0 |
| 52 | +default_selected: false |
| 53 | +module_greeting: > |
| 54 | + Welcome message shown after setup completes. |
| 55 | +
|
| 56 | +my_output_folder: |
| 57 | + prompt: "Where should output be saved?" |
| 58 | + default: "{project-root}/_bmad-output/my-module" |
| 59 | + result: "{project-root}/{value}" |
| 60 | +``` |
| 61 | +
|
| 62 | +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. |
| 63 | + |
| 64 | +:::caution[Literal Token] |
| 65 | +`{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. |
| 66 | +::: |
| 67 | + |
| 68 | +## Help Registration Without Configuration |
| 69 | + |
| 70 | +You may not need any configurable values but still want to register your module with the help system. This is worth doing when: |
| 71 | + |
| 72 | +- The skill description in SKILL.md frontmatter cannot fully convey what the module offers while staying concise |
| 73 | +- You want to express capability sequencing, phase constraints, or other metadata the CSV supports |
| 74 | +- An agent has many internal capabilities that users should be able to discover |
| 75 | +- Your module has more than about three distinct things it can do |
| 76 | + |
| 77 | +For simpler cases, these alternatives are often sufficient: |
| 78 | + |
| 79 | +| Alternative | What It Provides | |
| 80 | +| ----------- | ---------------- | |
| 81 | +| **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 | |
| 82 | +| **Script header comments** | Describe purpose, usage, and flags at the top of each script | |
| 83 | + |
| 84 | +If these cover your discoverability needs, you can skip the setup skill entirely. |
| 85 | + |
| 86 | +## The module-help.csv File |
| 87 | + |
| 88 | +The CSV asset registers the module's capabilities with the help system. Each row describes one capability that users can discover and invoke. |
| 89 | + |
| 90 | +```csv |
| 91 | +module,agent-name,skill-name,display-name,menu-code,capability,args,description,... |
| 92 | +mymod,,my-skill,My Skill,MS,build-process,,"Does something useful.",... |
| 93 | +``` |
| 94 | + |
| 95 | +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. |
| 96 | + |
| 97 | +## Anti-Zombie Pattern |
| 98 | + |
| 99 | +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. |
| 100 | + |
| 101 | +## Design Guidance |
| 102 | + |
| 103 | +Configuration is for **basic, project-level settings** — output folders, language preferences, feature toggles. Keep the number of configurable values small. |
| 104 | + |
| 105 | +| Pattern | Configuration Role | |
| 106 | +| ------- | ------------------ | |
| 107 | +| **Agent pattern** | Prefer agent memory for per-user preferences. Use config only for values that must be shared across the project | |
| 108 | +| **Workflow pattern** | Use config for output locations and behavior switches that vary across projects | |
| 109 | +| **Skill-only pattern** | Use config sparingly. If the skill works with sensible defaults, skip config entirely | |
| 110 | + |
| 111 | +Extensive workflow customization — step overrides, conditional branching, template selection — is a separate concern and will be covered in a dedicated document. |
| 112 | + |
| 113 | +## Upcoming Tooling |
| 114 | + |
| 115 | +A module scaffolding tool is planned that will generate the setup skill as part of module creation, along with the marketplace manifest format. Until then, use the BMad Builder module's setup skill as a reference implementation. |
| 116 | + |
| 117 | +Once available, you will be able to generate a setup skill from your existing collection of agents, workflows, and skills with a prompt like: |
| 118 | + |
| 119 | +:::note[Example] |
| 120 | +"Create a setup skill for my module in `./my-module-skills/` that mirrors `bmad-builder-setup` — with its own module name and code (my cool module, mcm), config variables for output folder locations, and help entries inferred from the existing skills in the folder." |
| 121 | +::: |
| 122 | + |
| 123 | +A decent LLM will clone the entire `bmad-builder-setup` skill components amd structure — SKILL.md, scripts, tests — updating only the skill name, description, and the two asset files (`module.yaml` and `module-help.csv`) to reflect your module. |
| 124 | +Take the time to ensure the description that triggers it is correct, along with the module.yaml and module-help.csv |
0 commit comments