diff --git a/docs/explanation/module-configuration.md b/docs/explanation/module-configuration.md index 2e98a23..11625c2 100644 --- a/docs/explanation/module-configuration.md +++ b/docs/explanation/module-configuration.md @@ -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 @@ -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 @@ -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.yaml`, `/module-help.csv`| +| **Setup skill** | Multi-skill modules distributed by direct download (no installer) | `/{code}-setup/assets/` | +| **Self-registering skill**| Single-skill modules distributed by direct download | `/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/`: | File | Scope | Contains | | ------------------ | ------------------------ | ----------------------------------------------------------------------------------------------- | @@ -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 @@ -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 @@ -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. diff --git a/docs/explanation/skill-authoring-best-practices.md b/docs/explanation/skill-authoring-best-practices.md index 3dd6c32..5a39ec5 100644 --- a/docs/explanation/skill-authoring-best-practices.md +++ b/docs/explanation/skill-authoring-best-practices.md @@ -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 diff --git a/docs/explanation/what-are-modules.md b/docs/explanation/what-are-modules.md index f257edc..5fd7a51 100644 --- a/docs/explanation/what-are-modules.md +++ b/docs/explanation/what-are-modules.md @@ -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.yaml`, `/module-help.csv`| +| **Setup skill (alternative)** | Multi-skill modules distributed by direct download | `/{code}-setup/assets/` | +| **Self-registering (alternative)** | Single-skill modules distributed by direct download | `/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 @@ -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 @@ -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. diff --git a/docs/how-to/distribute-your-module.md b/docs/how-to/distribute-your-module.md index a7161e9..62fb0b7 100644 --- a/docs/how-to/distribute-your-module.md +++ b/docs/how-to/distribute-your-module.md @@ -74,23 +74,68 @@ For repositories that ship multiple modules, add an entry to the `plugins` array ## Step 2: Structure Your Repository -Organize the repository so skills can be located relative to `marketplace.json`. +Organize the repository so skills can be located relative to `marketplace.json`. The recommended layout places `module.yaml` and `module-help.csv` at the **module root**, alongside the skill folders. This is how the official BMad modules ship today. -### Single-module repository +### Single-module repository (recommended) ``` my-module/ ├── .claude-plugin/ │ └── marketplace.json ├── skills/ +│ ├── module.yaml # Registration manifests at module root +│ ├── module-help.csv │ ├── my-agent/ │ │ ├── SKILL.md │ │ ├── prompts/ │ │ └── scripts/ +│ └── my-workflow/ +│ ├── SKILL.md +│ └── prompts/ +├── README.md +└── LICENSE +``` + +In this layout, the BMad installer reads `module.yaml` and `module-help.csv` directly from the module root. No setup skill is needed; the installer handles agent registration, help registration, and any cross-project config from these two files. + +### Multi-module marketplace repository + +``` +my-marketplace/ +├── .claude-plugin/ +│ └── marketplace.json # Multiple entries in plugins[] +├── modules/ +│ ├── module-a/ +│ │ ├── module.yaml +│ │ ├── module-help.csv +│ │ ├── skill-one/ +│ │ └── skill-two/ +│ └── module-b/ +│ ├── module.yaml +│ ├── module-help.csv +│ └── standalone-skill/ +├── README.md +└── LICENSE +``` + +:::caution[Skill Paths Must Match] +The `skills` array in `marketplace.json` must match the actual directory paths relative to the repository root. If you reorganize your folders, update the manifest. +::: + +### Alternative: Direct-Download Layouts + +If your users install by copying the folder into their project rather than running the BMad installer, the manifests can ship inside a skill so that running the skill triggers registration. The installer also accepts these layouts as fallbacks. + +**Multi-skill direct download (setup skill bundles registration):** + +``` +my-module/ +├── .claude-plugin/ +│ └── marketplace.json +├── skills/ +│ ├── my-agent/ │ ├── my-workflow/ -│ │ ├── SKILL.md -│ │ └── prompts/ -│ └── mymod-setup/ # Generated by Create Module (CM) +│ └── mymod-setup/ # Setup skill carries registration │ ├── SKILL.md │ ├── assets/ │ │ ├── module.yaml @@ -103,7 +148,7 @@ my-module/ └── LICENSE ``` -### Standalone single-skill module +**Single-skill direct download (skill self-registers):** ``` my-skill/ @@ -111,7 +156,7 @@ my-skill/ │ └── marketplace.json ├── skills/ │ └── my-skill/ -│ ├── SKILL.md +│ ├── SKILL.md # Triggers registration on first run │ ├── assets/ │ │ ├── module-setup.md │ │ ├── module.yaml @@ -124,26 +169,7 @@ my-skill/ └── LICENSE ``` -### Multi-module marketplace repository - -``` -my-marketplace/ -├── .claude-plugin/ -│ └── marketplace.json # Multiple entries in plugins[] -├── skills/ -│ ├── module-a/ -│ │ ├── skill-one/ -│ │ ├── skill-two/ -│ │ └── moda-setup/ -│ └── module-b/ -│ └── standalone-skill/ -├── README.md -└── LICENSE -``` - -:::caution[Skill Paths Must Match] -The `skills` array in `marketplace.json` must match the actual directory paths relative to the repository root. If you reorganize your folders, update the manifest. -::: +Choose an alternative layout only when direct-download distribution is a primary requirement. The skills themselves should still be [self-runnable](/explanation/skill-authoring-best-practices.md#skills-must-be-self-runnable) regardless of how registration is handled. ## Step 3: Verify the Manifest @@ -155,7 +181,7 @@ Every path in the `skills` array must point to a directory containing a `SKILL.m ### Check module registration files -Multi-skill modules need `assets/module.yaml` and `assets/module-help.csv` in the setup skill. Standalone modules keep these files in the skill's own `assets/` folder. +For root placement (recommended): `module.yaml` and `module-help.csv` at the module root, alongside the skill folders. For direct-download layouts: in the setup skill's `assets/` (multi-skill) or in the skill's own `assets/` (standalone). ### Run Validate Module @@ -195,10 +221,10 @@ Tag releases with semantic versions. Installs pull from the default branch unles After publishing, users can: -- Install via the BMad installer from any Git URL or local path -- Run the setup skill to register with `bmad-help` +- Install via the BMad installer from any Git URL or local path; the installer reads `module.yaml` and `module-help.csv` from the module root and handles registration automatically - Browse your module's capabilities through the help system - Get configuration prompts defined in `module.yaml` +- For direct-download layouts: run the setup skill (or the self-registering skill with `setup`/`configure`) to register manually ## Step 5: List in the Marketplace (Optional) @@ -211,5 +237,5 @@ See the marketplace [CONTRIBUTING.md](https://github.com/bmad-code-org/bmad-plug - Include a `README.md` covering what the module does, how to install it, and any external dependencies - Add a `LICENSE` file. MIT is common for open-source BMad modules. - Keep the `marketplace.json` version in sync with your release tags -- External dependencies (CLI tools, MCP servers) should be documented in the README and detected by your setup skill +- External dependencies (CLI tools, MCP servers) should be documented in the README and detected by the skills that need them at runtime, not solely by an installer-time check - Run `Validate Module (VM)` before each release to catch regressions diff --git a/docs/reference/builder-commands.md b/docs/reference/builder-commands.md index 2485e01..062aa3d 100644 --- a/docs/reference/builder-commands.md +++ b/docs/reference/builder-commands.md @@ -320,8 +320,8 @@ The Module Builder (`bmad-module-builder`) handles module-level planning, scaffo | Capability | Menu Code | What It Does | | ------------------- | --------- | --------------------------------------------------------------------------------------------------------------- | | **Ideate Module** | IM | Brainstorm and plan a module through creative facilitation | -| **Create Module** | CM | Package skills as an installable module: setup skill for multi-skill, self-registration for standalone | -| **Validate Module** | VM | Check structural integrity and entry quality for both multi-skill and standalone modules | +| **Create Module** | CM | Generate `module.yaml`, `module-help.csv`, and `marketplace.json` at the module root (or bundled into a skill for direct-download distribution) | +| **Validate Module** | VM | Check structural integrity and entry quality | ### Ideate Module (IM) @@ -350,30 +350,30 @@ The plan document uses a resumable template with YAML frontmatter, so long brain ### Create Module (CM) -Packages built skills as an installable BMad module. Auto-detects single-skill vs. multi-skill input and recommends the appropriate approach. Supports `--headless` / `-H`. +Packages built skills as an installable BMad module. Supports `--headless` / `-H`. | Aspect | Detail | | --------------- | ------------------------------------------------------------------------------------------- | | **Interaction** | Guided or headless | | **Input** | Path to a skills folder or single skill (or SKILL.md file), optional plan document | -| **Output** | Setup skill for multi-skill modules, or self-registration files for standalone modules | +| **Output** | `module.yaml`, `module-help.csv`, and `.claude-plugin/marketplace.json` for the module | **What it does:** 1. Reads the SKILL.md files to understand each skill -2. Detects single vs. multi-skill and confirms the packaging approach with the user +2. Confirms the layout with the user (root placement is the default; direct-download alternatives are opt-in) 3. Collects module identity (name, code, description, version, greeting) 4. Defines help CSV entries: capabilities, menu codes, ordering, relationships 5. Captures configuration variables and external dependencies -6. Scaffolds the module infrastructure +6. Writes the manifests and distribution scaffolding -**Multi-skill output:** A dedicated `{code}-setup/` folder with merge scripts, cleanup scripts, and a generic SKILL.md. +**Default output (root placement):** `module.yaml` and `module-help.csv` at the module root, plus `.claude-plugin/marketplace.json`. The BMad installer reads these directly. No setup skill or merge scripts are generated. -**Standalone output:** `assets/module-setup.md`, `assets/module.yaml`, and `assets/module-help.csv` embedded in the skill, plus merge scripts in `scripts/` and a `.claude-plugin/marketplace.json` for distribution. The skill's SKILL.md is updated to check for registration on activation. +**Alternative output (direct-download layouts):** If the author opts in, Create Module can instead bundle the manifests and merge scripts into a `{code}-setup/` skill (multi-skill) or embed self-registration into a single skill's `assets/` folder with a `module-setup.md` reference (standalone). Use these when the module must install by direct download without the BMad installer. ### Validate Module (VM) -Verifies that a module's structure is complete and accurate. Auto-detects multi-skill modules (with setup skill) and standalone modules (with self-registration). Combines a deterministic validation script with LLM-based quality assessment. +Verifies that a module's structure is complete and accurate. Auto-detects the module's layout (root placement, setup skill, or self-registering skill) and adjusts its checks accordingly. Combines a deterministic validation script with LLM-based quality assessment. | Aspect | Detail | | --------------- | ------------------------------------------------------ | @@ -385,7 +385,7 @@ Verifies that a module's structure is complete and accurate. Auto-detects multi- | Check | What It Catches | | ---------------------- | ------------------------------------------------------------------------------------------- | -| Module structure | Missing setup skill or standalone files (`module-setup.md`, merge scripts) | +| Module structure | Missing `module.yaml` or `module-help.csv` at the module root, or for direct-download layouts: missing setup skill files (`module-setup.md`, merge scripts) | | Coverage | Skills without CSV entries, orphan entries for nonexistent skills | | Menu codes | Duplicate codes across the module | | References | Before/after fields pointing to nonexistent capabilities | diff --git a/docs/tutorials/build-your-first-module.md b/docs/tutorials/build-your-first-module.md index 528eedc..bfbd648 100644 --- a/docs/tutorials/build-your-first-module.md +++ b/docs/tutorials/build-your-first-module.md @@ -10,7 +10,7 @@ This tutorial takes you from an initial idea to a working, installable BMad modu - Planning a module with the Ideate Module (IM) capability - Choosing between a single agent and multiple workflows - Building individual skills with the Agent and Workflow Builders -- Scaffolding a setup skill with Create Module (CM) +- Generating module manifests with Create Module (CM) - Validating your module with Validate Module (VM) :::note[Prerequisites] @@ -25,16 +25,14 @@ Already have your skills built? Skip to **Step 3: Scaffold the Module** to packa ## Understanding Modules -A BMad module bundles skills so they're discoverable and configurable. The Module Builder offers two approaches depending on what you're building: +A BMad module is a folder of skills with two registration manifests at its root: -| Approach | When to Use | What Gets Generated | -| --------------------- | -------------------------------------------- | --------------------------------------------------------------- | -| **Setup skill** | Folder of 2+ skills | Dedicated `{code}-setup` skill with config and help assets | -| **Self-registration** | Single standalone skill | Registration embedded in the skill's own `assets/` folder | +- **`module.yaml`**: module identity and configuration variables +- **`module-help.csv`**: capability entries consumed by `bmad-help` -Both produce the same registration artifacts: `module.yaml` (identity and config variables) and `module-help.csv` (capability entries), which register with `bmad-help`. +The recommended layout places these manifests at the **module root**, alongside the skill folders. The BMad installer reads them directly and handles registration. This is what you'll build in this tutorial. -See **[What Are Modules](/explanation/what-are-modules.md)** for the architecture behind these choices. +For modules distributed by direct download (no installer), the manifests can instead ship inside a setup skill or embedded in a standalone skill. Those alternatives are covered in **[What Are Modules](/explanation/what-are-modules.md)**. ## Step 1: Plan Your Module @@ -81,49 +79,31 @@ Build and test each skill before scaffolding the module. The Create Module step Run Create Module (CM) to package your finished skills. :::note[Example] -**You:** "I want to create a module" or provide the path to your skills folder (or a single skill). +**You:** "I want to create a module" or provide the path to your skills folder. -**Builder:** Reads your skills, detects whether this is a multi-skill or single-skill module, confirms the approach, and scaffolds the output. +**Builder:** Reads your skills, gathers module identity and capability entries through conversation, then writes `module.yaml`, `module-help.csv`, and `marketplace.json` for the module. ::: -### Multi-skill modules - -The builder generates a dedicated setup skill: +### Default layout (root placement) ``` -your-skills-folder/ -├── {code}-setup/ # Generated setup skill -│ ├── SKILL.md # Setup instructions -│ ├── scripts/ # Config merge and cleanup scripts -│ │ ├── merge-config.py -│ │ ├── merge-help-csv.py -│ │ └── cleanup-legacy.py -│ └── assets/ -│ ├── module.yaml # Module identity and config vars -│ └── module-help.csv # Capability entries +your-module-folder/ +├── .claude-plugin/ +│ └── marketplace.json # Distribution manifest +├── module.yaml # Module identity and config vars +├── module-help.csv # Capability entries ├── your-agent-skill/ +│ └── SKILL.md ├── your-workflow-skill/ +│ └── SKILL.md └── ... ``` -### Standalone modules - -The builder embeds registration into the skill itself: +This is the layout the BMad installer expects. When a user installs the module via `npx bmad-method install`, the installer reads `module.yaml` and `module-help.csv` directly from the module root and handles agent registration, help registration, and any cross-project config. -``` -your-skill/ -├── SKILL.md # Updated with registration check -├── assets/ -│ ├── module-setup.md # Self-registration reference -│ ├── module.yaml # Module identity and config vars -│ └── module-help.csv # Capability entries -├── scripts/ -│ ├── merge-config.py # Config merge script -│ └── merge-help-csv.py # Help CSV merge script -└── ... -``` +### Alternative: bundle registration inside a skill -A `.claude-plugin/marketplace.json` is also generated at the parent level for distribution. +If your module needs to be installable by direct download (no installer), Create Module can instead bundle the registration manifests and merge scripts into a setup skill (`{code}-setup/assets/`) or embed self-registration into a single skill (`/assets/` with `module-setup.md`). See **[Distribute Your Module](/how-to/distribute-your-module.md)** for the full direct-download layouts. ## Step 4: Validate @@ -144,7 +124,7 @@ Fix any findings and re-validate until clean. ## What You've Built -Your module is ready to distribute. Multi-skill modules install through the setup skill; standalone modules self-register on first run. Either way, capabilities appear in `bmad-help` and configuration is persisted automatically. +Your module is ready to distribute. With the default root layout, users install with `npx bmad-method install` and the BMad installer handles registration. Capabilities appear in `bmad-help` and configuration is persisted automatically. ## Quick Reference @@ -168,7 +148,7 @@ Yes. Build the new skill and re-run Create Module (CM) on the folder. The anti-z ### What if my module only has one skill? -The Module Builder handles this automatically. Give it a single skill and it recommends the **standalone self-registering** approach, where registration embeds directly in the skill and triggers on first run or when the user passes `setup`/`configure`. +That's fine. A module can be a single skill plus `module.yaml` and `module-help.csv` at its root. If you specifically need direct-download distribution, ask Create Module to embed self-registration into the skill instead; the manifests will live in `/assets/` and the skill triggers registration on first run or when the user passes `setup`/`configure`. ### Can my module extend another module? @@ -177,10 +157,10 @@ Yes. Tell the builder during ideation or creation that your module is an expansi ## Getting Help - **[What Are Modules](/explanation/what-are-modules.md)**: Concepts and architecture -- **[Module Configuration](/explanation/module-configuration.md)**: Setup skill internals and config patterns +- **[Module Configuration](/explanation/module-configuration.md)**: Registration internals and config patterns - **[Builder Commands Reference](/reference/builder-commands.md)**: All builder capabilities - **[Discord](https://discord.gg/gk8jAdXWmj)**: Community support :::tip[Key Takeaway] -The workflow is IM, then BA/BW for each skill, then CM to package, then VM to verify. Single-skill modules need no extra setup infrastructure. +The workflow is IM, then BA/BW for each skill, then CM to generate the module manifests, then VM to verify. Root placement is the default and works with the BMad installer; bundled registration is the alternative for direct-download distribution. :::