Skip to content

docs: update for universal custom module installer #71

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

Merged
bmadcode merged 1 commit into from
Apr 9, 2026
Merged

docs: update for universal custom module installer #71

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
2 changes: 1 addition & 1 deletion docs/explanation/what-are-modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ At the distribution level, a BMad module is a **plugin**: a package of skills wi
| **Single plugin** | One module (standalone or multi-skill) | `.claude-plugin/marketplace.json` with one plugin entry |
| **Marketplace** | A repo that ships multiple modules | `.claude-plugin/marketplace.json` with multiple plugin entries |

The `.claude-plugin/` convention originates from Claude Code, but the format works across multiple skills platforms. The BMad installer will support installing custom modules directly from GitHub in an upcoming release. Until then, copy the created skill folder into your tool's skills directory (`.claude/skills/`, `.agents/skills/`, etc.). You can also use Anthropic's plugin system if targeting only Claude Code.
The `.claude-plugin/` convention originates from Claude Code, but the format works across multiple skills platforms. The BMad installer supports installing custom modules from any Git host (GitHub, GitLab, Bitbucket, self-hosted) or local file paths. See the [BMad Method install guide](https://docs.bmad-method.org/how-to/install-custom-modules/) for details.
Copy link
Copy Markdown

@augmentcode augmentcode bot Apr 9, 2026

Choose a reason for hiding this comment

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

docs/explanation/what-are-modules.md:17 — This page says “the BMad installer,” but the link and other pages refer to “the BMad Method installer,” which could confuse readers about which tool is meant. Other locations where this applies: docs/how-to/distribute-your-module.md:11, docs/how-to/distribute-your-module.md:174, docs/how-to/distribute-your-module.md:198.

Severity: low

Fix This in Augment

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


The Module Builder generates the appropriate `marketplace.json` during the Create Module (CM) step - but you will want to verify it lists the proper relative paths to the skills you want to deliver with your module.

Expand Down
43 changes: 20 additions & 23 deletions docs/how-to/distribute-your-module.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
---
title: 'Distribute Your Module'
description: Set up a GitHub repository to share your BMad module so others can install it
description: Set up a Git repository to share your BMad module so others can install it
---

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.
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 (manually now, or via the BMad installer once released)
- Others should be able to install it via the BMad installer
- The repository may host one module or several

## When to Skip This
Expand All @@ -19,7 +19,7 @@ This guide walks through publishing a BMad module to GitHub with a `.claude-plug
:::note[Prerequisites]

- A completed, validated BMad module (see **[Build Your First Module](/tutorials/build-your-first-module.md)**)
- A GitHub account with a repository for your module
- A Git repository on any host (GitHub, GitLab, Bitbucket, or self-hosted)
- Git installed locally
:::

Expand All @@ -29,13 +29,13 @@ Start from the [BMad Module Template](https://github.com/bmad-code-org/bmad-modu

## Step 1: Configure the Plugin Manifest

Modules are discovered 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.
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.

:::note[Installer Coming Soon]
The BMad Method installer (`npx bmad-method install --custom-content`) will support installing custom modules from GitHub in an upcoming release. Until then, users install by cloning your repo and copying the skill folders into their tool's skills directory (`.claude/skills/`, `.agents/skills/`, etc.).
:::tip[Installer Support]
The BMad Method installer (`npx bmad-method install`) supports installing custom modules from any Git host or local path. Users can install interactively or via `--custom-source <url-or-path>`. See the [BMad Method install guide](https://docs.bmad-method.org/how-to/install-custom-modules/) for details.
:::

This format works for any skills-capable platform, not just Claude.
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.
Copy link
Copy Markdown

@augmentcode augmentcode bot Apr 9, 2026

Choose a reason for hiding this comment

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

docs/how-to/distribute-your-module.md:38 — This sentence is a run-on and refers to “the claude file,” which is ambiguous and could imply broader platform support of .claude-plugin/marketplace.json than intended. Consider clarifying what is actually cross-platform here (the module layout vs a manifest that some tools may not consume).

Severity: low

Fix This in Augment

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


A minimal manifest for a single module:

Expand Down Expand Up @@ -165,30 +165,27 @@ Multi-skill modules need `assets/module.yaml` and `assets/module-help.csv` in th

Validate Module (VM) checks for missing files, orphan entries, and other structural problems. Fix anything it flags before publishing.

## Step 4: Publish to GitHub
## Step 4: Publish

Push your repository to GitHub. Once the repo is accessible, anyone with permission can use it.
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 (current)
### Installing your module

Users clone or download the repo and copy the skill folders into their tool's skills directory:
Users install custom modules through the BMad installer:

```bash
# Example: copy an agent skill into Claude Code's skills directory
cp -r skills/my-agent ~/.claude/skills/my-agent
```

### Installing (upcoming)

Once the BMad installer supports custom modules, users will install with:
# Interactive: the installer prompts for a custom source URL or path
npx bmad-method install

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

@augmentcode augmentcode bot Apr 9, 2026

Choose a reason for hiding this comment

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

docs/how-to/distribute-your-module.md:181 — The example uses --tools claude-code, but I don’t see --tools documented elsewhere in this repo for npx bmad-method install; if the flag name/value differs, this could mislead users. Can we confirm this matches the current installer CLI?

Severity: medium

Fix This in Augment

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

```

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 GitHub access to clone. The upcoming installer will use whatever GitHub authentication is configured on the machine.
For private repos, users need Git access to clone. The installer uses whatever Git authentication is configured on the machine.

### Versioning

Expand All @@ -198,7 +195,7 @@ Tag releases with semantic versions. Installs pull from the default branch unles

After publishing, users can:

- Copy skill folders into their tool's skills directory (or use the BMad installer once available)
- 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`
Expand Down
6 changes: 3 additions & 3 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,8 @@ Invoke the **Agent Builder** or **Workflow Builder** and describe what you want

The builders produce a complete skill folder. Copy it into your AI tool's skills directory (`.claude/skills/`, `.codex/skills/`, `.agents/skills/`, or wherever your tool looks) and it's immediately usable.

:::note[Installer Coming Soon]
The BMad Method installer (`npx bmad-method install`) will support installing custom modules directly from GitHub repositories in an upcoming release. For now, copy the created skill folder into your tool's skills directory manually.
:::tip[Custom Module Installation]
The BMad Method installer supports installing custom modules from any Git host (GitHub, GitLab, Bitbucket, self-hosted) or local paths. See the [BMad Method install guide](https://docs.bmad-method.org/how-to/install-custom-modules/) for details.
:::

:::tip[No Module Required]
Expand Down Expand Up @@ -87,7 +87,7 @@ Build better skills with these guides, drawn from real-world BMad development.
| Section | Purpose |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **[Build Your First Module](/tutorials/build-your-first-module.md)** | Plan, build, scaffold, and validate a complete module |
| **[Distribute Your Module](/how-to/distribute-your-module.md)** | Share your module via GitHub for anyone to install |
| **[Distribute Your Module](/how-to/distribute-your-module.md)** | Share your module via any Git host for anyone to install |
| **[Concepts](/explanation/)** | Agent types, memory architecture, workflows, skills, and how they relate |
| **[Design Patterns](/explanation/#design-patterns)** | Progressive disclosure, subagent orchestration, authoring best practices |
| **[Reference](/reference/)** | Builder commands, workflow patterns |
Expand Down
Loading