Skip to content

docs(modules): lead with root placement for module manifests #80

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bmadcode wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(modules): lead with root placement for module manifests #80

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 21 additions & 26 deletions docs/explanation/module-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,9 @@
---
title: 'Module Configuration and the Setup Skill'
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
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. Multi-skill modules use a dedicated **setup skill** for this. Single-skill standalone modules handle registration themselves on first run.

When you create your own module, you can either add a configuration skill or embed the feature in every skill following the standalone pattern. For modules with more than 1-2 skills, a setup skill is the better choice.
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.

## When You Need Configuration

Expand All @@ -17,8 +15,8 @@ Most modules should not need configuration at all. Before adding configurable va
| **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[Standalone Skills]
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** where 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`.
:::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.
:::

## Configuration vs Customization
Expand All @@ -40,18 +38,21 @@ Module registration serves two purposes:

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.

### Two Registration Paths
### Three Registration Layouts

The BMad installer resolves manifests in priority order:

| Path | When to Use | How It Works |
| --------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **Setup skill** | Multi-skill modules (2+ skills) | A dedicated `{code}-setup` skill handles registration for all skills |
| **Self-registration** | Single-skill standalone modules | The skill itself registers on first run or when user passes `setup`/`configure` |
| 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` |

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.
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.

## Configuration Files

Setup skills write to three files in `{project-root}/_bmad/`:
Module registration writes to three files in `{project-root}/_bmad/`:
Copy link
Copy Markdown

@augmentcode augmentcode Bot Apr 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

docs/explanation/module-configuration.md:55 — This page mentions _bmad/config.toml / config.user.toml earlier, but here it documents config.yaml / config.user.yaml as the registration outputs. Consider making the file format/extension consistent across the page so users don’t write config to the wrong filenames.

Severity: medium

⏳ Generating Fix in Augment link...

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.


| File | Scope | Contains |
| ------------------ | ------------------------ | ----------------------------------------------------------------------------------------------- |
Expand All @@ -63,7 +64,7 @@ Core settings (like `output_folder` and `document_output_language`) live at the

## The module.yaml File

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.
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.

```yaml
code: mymod
Expand Down Expand Up @@ -102,7 +103,7 @@ For simpler cases, these alternatives are often sufficient:
| **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 the setup skill entirely.
If these cover your discoverability needs, you can skip module-level registration entirely and just ship the skill.

## The module-help.csv File

Expand Down Expand Up @@ -175,19 +176,13 @@ The **Module Builder** (`bmad-module-builder`) automates module creation. It off
| **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 |

**For a folder of skills (multi-skill module):**
**Standard flow:**

1. Run **Ideate Module (IM)** to brainstorm and plan
1. Run **Ideate Module (IM)** to brainstorm and plan (optional)
2. Build each skill using the **Agent Builder (BA)** or **Workflow Builder (BW)**
3. Run **Create Module (CM)**. It generates a dedicated `-setup` skill with `module.yaml`, `module-help.csv`, and merge scripts
3. Run **Create Module (CM)** to generate `module.yaml`, `module-help.csv`, and `.claude-plugin/marketplace.json` for the module
4. Run **Validate Module (VM)** to verify everything is wired correctly

**For a single skill (standalone module):**

1. Build the skill using the **Agent Builder (BA)** or **Workflow Builder (BW)**
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
3. Run **Validate Module (VM)** to verify

The Module Builder auto-detects single vs. multi-skill input and recommends the appropriate approach.
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](/explanation/what-are-modules.md)** for concepts and architecture decisions, or the **[Builder Commands Reference](/reference/builder-commands.md)** for detailed capability documentation.
17 changes: 17 additions & 0 deletions docs/explanation/skill-authoring-best-practices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,23 @@ Six dimensions to keep in mind during the build phase. The quality scanners chec

When your skill's users come from varied contexts (different orgs, different domains, different taste in output formats), a `customize.toml` surface lets them override specific fields without forking. It's opt-in per skill, and the decision is deliberate: every knob you ship is a promise the resolver will carry across releases. Before you opt in during the build, read [Customization for Authors](/explanation/customization-for-authors.md) for the decision framework and [How to Make a Skill Customizable](/how-to/make-a-skill-customizable.md) for the mechanics.

## Skills Must Be Self-Runnable

Every skill should run successfully whenever a user has it installed, whether they used the BMad installer or simply dropped the skill folder into their project. A skill that depends on installer-only setup to function is fragile; it breaks in the direct-download case and silently misleads anyone who copies it into a new project.

The module manifests (`module.yaml` and `module-help.csv`) are registration metadata, not a runtime dependency. They integrate the skill into shared config and `bmad-help`. They are not part of how the skill operates.

What this means in practice:

| Need | Where It Belongs |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Cross-project value** (output folder, language) | Read from config if present; otherwise prompt the user or fall back to a sensible default |
| **Per-skill behavior overrides** | Use the [customization surface](/explanation/customization-for-authors.md), not config |
| **First-run onboarding** (memory agents) | Initialize from the skill itself on first activation; never assume an installer ran |
| **Installer-only concerns** | Keep narrow: agent registration, `bmad-help` registration, optional cross-project config collection |

If a skill needs a value at runtime and config has not been set, it should ask the user, not fail. This keeps the same skill viable across both installer-driven and direct-download distributions.

## Common Patterns

### Soft Gate Elicitation
Expand Down
51 changes: 40 additions & 11 deletions docs/explanation/what-are-modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,15 +22,44 @@ This also means you can include remote URL skills in your own module to combine

## What a Module Contains

| Component | Multi-Skill Module | Standalone Module |
| ------------------- | ------------------------------------------------------- | ---------------------------------------------------------- |
| **Skills** | Two or more agents/workflows | A single agent or workflow |
| **Registration** | Dedicated `{code}-setup` skill | Built into the skill itself (`assets/module-setup.md`) |
| **module.yaml** | In the setup skill's `assets/` | In the skill's own `assets/` |
| **module-help.csv** | In the setup skill's `assets/` | In the skill's own `assets/` |
| **Distribution** | Plugin with multiple skill folders | Plugin with single skill folder + `marketplace.json` |
A module is a folder of one or more skills with two registration manifests:

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`.
- **`module.yaml`**: module identity and configuration variables
- **`module-help.csv`**: capability registry consumed by `bmad-help`

The recommended placement is at the **module root**, alongside the skill folders:

```
my-module/
├── module.yaml # Recommended: at module root
├── module-help.csv # Recommended: at module root
├── .claude-plugin/
│ └── marketplace.json
├── my-agent/
│ └── SKILL.md
└── my-workflow/
└── SKILL.md
```

This is the layout the BMad installer expects by default, and it's how the official BMad modules (`bmm`, `cis`, etc.) ship today.

### Why Root Placement Is the Default

The manifests are **registration metadata**, not runtime dependencies of any one skill. Putting them at the module root reflects that: they describe the module as a whole, not any individual skill. The installer reads them once at install time to register the module with the project; the skills themselves never read them at runtime.

This keeps every skill in the module **self-runnable**: a user who downloads and drops a single skill folder into a project gets a working skill, with or without module-level registration. See [Skills Must Be Self-Runnable](/explanation/skill-authoring-best-practices.md#skills-must-be-self-runnable) for why this matters.

### Alternative: Bundling Registration Inside a Skill

For authors who want their module installable by direct download (no `npx bmad-method install`), the manifests can be bundled inside a skill so the skill self-registers on first run:

| Pattern | When to Use | Where Manifests Live |
| -------------------------------- | ---------------------------------------------------------- | ------------------------------------------------- |
| **Root placement (default)** | Distribution via the BMad installer; all headless installs | `<module>/module.yaml`, `<module>/module-help.csv`|
| **Setup skill (alternative)** | Multi-skill modules distributed by direct download | `<module>/{code}-setup/assets/` |
| **Self-registering (alternative)** | Single-skill modules distributed by direct download | `<skill>/assets/` with `module-setup.md` |

The BMad installer supports all three locations, with **root placement taking priority** and the others as fallbacks. Choose the alternatives only when direct-download distribution is a primary requirement.

## Agent vs. Workflow vs. Both

Expand Down Expand Up @@ -98,7 +127,7 @@ Some modules depend on tools outside the BMad ecosystem.
| **MCP servers** | Custom or third-party Model Context Protocol servers |
| **Web services** | APIs that require credentials or configuration |

When a module has external dependencies, the setup skill should check for their presence and guide users through installation or configuration.
When a module has external dependencies, the skills that depend on them should check for their presence at runtime and guide the user through installation or configuration. Do not rely on installer-time checks alone, since users who install by direct download skip the installer entirely.

## UI and Visualization

Expand All @@ -111,7 +140,7 @@ Not every module needs a UI. But for complex modules with many capabilities, a v
The Module Builder (`bmad-module-builder`) provides three capabilities for the module lifecycle:

1. **Ideate Module (IM)**: Brainstorm and plan through creative facilitation
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)
3. **Validate Module (VM)**: Verify structural integrity and entry quality for both multi-skill and standalone modules
2. **Create Module (CM)**: Package skills as an installable module by generating `module.yaml`, `module-help.csv`, and a `.claude-plugin/marketplace.json` for the module
3. **Validate Module (VM)**: Verify structural integrity and entry quality

See the **[Builder Commands Reference](/reference/builder-commands.md)** for detailed documentation on each capability.
Loading
Loading