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

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

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

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

Organize the repository so skills can be located 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/
│   └── 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/
│   │   └── moda-setup/
│   └── module-b/
│       └── standalone-skill/
├── README.md
└── LICENSE

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

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

Users install custom modules through the BMad installer:

# Interactive: the installer prompts for a custom source URL or path
npx bmad-method install

# Non-interactive: specify the source directly
npx bmad-method install --custom-source https://github.com/your-org/my-module --tools claude-code --yes

The installer accepts HTTPS URLs, SSH URLs, URLs with deep paths (e.g., /tree/main/subdir), and local file paths.

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

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

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