Distribute Your Module
This guide walks through publishing a BMad module to a Git repository with a .claude-plugin/marketplace.json manifest so anyone can install it in one command.
When to Use This
Section titled “When to Use This”- You have a module ready to share publicly or within your organization
- Others should be able to install it via the BMad installer
- The repository may host one module or several
When to Skip This
Section titled “When to Skip This”- The module is for personal use in a single project. Keep the skills in your project.
- The module isn’t stable yet. Distribute once it is.
Step 1: Configure the Plugin Manifest
Section titled “Step 1: Configure the Plugin Manifest”Modules are discovered through a .claude-plugin/marketplace.json manifest at the repository root. Create Module generates this file for you. Verify and complete it before publishing.
This format works for any skills-capable platform, not just Claude, we just utilize the claude file as a convention to support any skills based platform.
A minimal manifest for a single module:
{ "name": "my-module", "owner": { "name": "Your Name" }, "license": "MIT", "homepage": "https://github.com/your-github/my-module", "repository": "https://github.com/your-github/my-module", "keywords": ["bmad", "your-domain"], "plugins": [ { "name": "my-module", "source": "./", "description": "What your module does in one sentence.", "version": "1.0.0", "author": { "name": "Your Name" }, "skills": [ "./skills/my-agent", "./skills/my-workflow" ] } ]}| Field | Purpose |
|---|---|
| name | Package identifier, lowercase and hyphenated |
| plugins[].source | Path from repo root to the module’s skill folder parent |
| plugins[].skills | Array of relative paths to each skill directory |
| plugins[].version | Semantic version; bump on each release |
For repositories that ship multiple modules, add an entry to the plugins array for each one, pointing to its own skill directories.
Step 2: Structure Your Repository
Section titled “Step 2: Structure Your Repository”Organize the repository so skills can be located relative to marketplace.json.
Single-module repository
Section titled “Single-module repository”my-module/├── .claude-plugin/│ └── marketplace.json├── skills/│ ├── my-agent/│ │ ├── SKILL.md│ │ ├── prompts/│ │ └── scripts/│ ├── my-workflow/│ │ ├── SKILL.md│ │ └── prompts/│ └── mymod-setup/ # Generated by Create Module (CM)│ ├── SKILL.md│ ├── assets/│ │ ├── module.yaml│ │ └── module-help.csv│ └── scripts/│ ├── merge-config.py│ ├── merge-help-csv.py│ └── cleanup-legacy.py├── README.md└── LICENSEStandalone single-skill module
Section titled “Standalone single-skill module”my-skill/├── .claude-plugin/│ └── marketplace.json├── skills/│ └── my-skill/│ ├── SKILL.md│ ├── assets/│ │ ├── module-setup.md│ │ ├── module.yaml│ │ └── module-help.csv│ ├── references/│ └── scripts/│ ├── merge-config.py│ └── merge-help-csv.py├── README.md└── LICENSEMulti-module marketplace repository
Section titled “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└── LICENSEStep 3: Verify the Manifest
Section titled “Step 3: Verify the Manifest”Before publishing, confirm the manifest is accurate.
Check skill paths
Section titled “Check skill paths”Every path in the skills array must point to a directory containing a SKILL.md file.
Check module registration files
Section titled “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.
Run Validate Module
Section titled “Run Validate Module”"Validate my module at ./skills"Validate Module (VM) checks for missing files, orphan entries, and other structural problems. Fix anything it flags before publishing.
Step 4: Publish
Section titled “Step 4: Publish”Push your repository to a Git host (GitHub, GitLab, Bitbucket, or self-hosted). Once the repo is accessible, anyone with permission can install it.
Installing your module
Section titled “Installing your module”Users install custom modules through the BMad installer:
# Interactive: the installer prompts for a custom source URL or pathnpx bmad-method install
# Non-interactive: specify the source directlynpx bmad-method install --custom-source https://github.com/your-org/my-module --tools claude-code --yesThe installer accepts HTTPS URLs, SSH URLs, URLs with deep paths (e.g., /tree/main/subdir), and local file paths.
Private or organization modules
Section titled “Private or organization modules”For private repos, users need Git access to clone. The installer uses whatever Git authentication is configured on the machine.
Versioning
Section titled “Versioning”Tag releases with semantic versions. Installs pull from the default branch unless the user specifies a tag or branch.
What You Get
Section titled “What You Get”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 - Browse your module’s capabilities through the help system
- Get configuration prompts defined in
module.yaml
Step 5: List in the Marketplace (Optional)
Section titled “Step 5: List in the Marketplace (Optional)”Submit your module to the BMad Plugins Marketplace for visibility alongside official modules. A listing isn’t required for installation, but it adds discoverability and a trust tier badge after review.
See the marketplace CONTRIBUTING.md for the submission process.
- Include a
README.mdcovering what the module does, how to install it, and any external dependencies - Add a
LICENSEfile. MIT is common for open-source BMad modules. - Keep the
marketplace.jsonversion in sync with your release tags - External dependencies (CLI tools, MCP servers) should be documented in the README and detected by your setup skill
- Run
Validate Module (VM)before each release to catch regressions