Distribute Your Module

This guide walks through publishing a BMad module to GitHub with a .claude-plugin/marketplace.json manifest so anyone can install it in one command.

When to Use This

• You have a module ready to share publicly or within your organization
• Others should be able to install it through the BMad installer
• The repository may host one module or several

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.

Prerequisites

• A completed, validated BMad module (see Build Your First Module)
• A GitHub account with a repository for your module
• Git installed locally

Quick Path

Start from the BMad Module Template. Click Use this template on GitHub, add your skills under skills/, update marketplace.json, and push. If you already have a repo with skills, use Create Module (CM) to scaffold the manifest and registration files directly.

Step 1: Configure the Plugin Manifest

The BMad installer discovers modules through a .claude-plugin/marketplace.json manifest at the repository root. Create Module (CM) generates this file for you. Verify and complete it before publishing.

This format works for any skills-capable platform, not just Claude.

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

Organize the repository so the installer can locate skills relative to marketplace.json.

Single-module repository

my-module/
├── .claude-plugin/
│   └── marketplace.json
├── skills/
│   ├── my-agent/
│   │   ├── SKILL.md
│   │   ├── prompts/
│   │   └── scripts/
│   ├── my-workflow/
│   │   ├── SKILL.md
│   │   └── prompts/
│   └── bmad-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
└── LICENSE

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
└── LICENSE

Multi-module marketplace repository

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json          # Multiple entries in plugins[]
├── skills/
│   ├── module-a/
│   │   ├── skill-one/
│   │   ├── skill-two/
│   │   └── bmad-moda-setup/
│   └── module-b/
│       └── standalone-skill/
├── README.md
└── LICENSE

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.

Step 3: Verify the Manifest

Before publishing, confirm the manifest is accurate.

Check skill paths

Every path in the skills array must point to a directory containing a SKILL.md file.

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

"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 to GitHub

Push your repository to GitHub. Once the repo is accessible, anyone with permission can install the module.

Public modules

Anyone can install with:

npx bmad-method install --custom-content https://github.com/your-org/my-module

Private or organization modules

Users with access install the same way. The installer uses whatever GitHub authentication is configured on the machine.

Versioning

Tag releases with semantic versions. Installs pull from the default branch unless the user specifies a tag or branch.

What You Get

After publishing, users can:

• Install your module with --custom-content via the BMad installer
• 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)

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.

Tips

• 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
• Run Validate Module (VM) before each release to catch regressions