Distribute Your Module
Use Smithy’s package mode and a Git repository to publish a module that anyone can add with npx skills add. There is no separate registry or build step.
When to Use This
Section titled “When to Use This”- You have a skill or module ready to share with a team or the public
- You want
bmadto check it for updates - Several projects should use the same version
When to Skip This
Section titled “When to Skip This”- The skill is for one project. Keep it in that project.
- The skill is not stable yet. Test it locally first.
1. Package the Skills
Section titled “1. Package the Skills”Ask Smithy to package them. If you built them with Smithy, they are probably registered already. See Package.
Smithy asks for the update_source if it does not have one. This is where update checks look for your module. Its usual form is github:<owner>/<repo>/<path>, where <path> is the folder holding your skill folders, such as skills. Update checks read bmod.toml from the main branch. A member’s source must match its record’s update_source.
2. Lay Out the Repository
Section titled “2. Lay Out the Repository”Put your skills under skills/. A multi-skill module looks like this:
your-repo/├── skills/│ ├── bmod-acme/│ │ ├── SKILL.md│ │ ├── bmod.toml│ │ ├── help/│ │ │ └── help.md│ │ └── roster.toml│ ├── acme-release-notes/│ │ ├── SKILL.md│ │ └── bmod.toml│ └── acme-agent-scout/│ ├── SKILL.md│ ├── customize.toml│ └── bmod.toml├── README.md└── LICENSEA single-skill module is one folder under skills/, with its help/ folder inside and no bmod-<code> folder. A repository can hold several modules. Give each one its own folder, skills/<code>/, and point its update_source at that folder; then npx skills add owner/repo/skills/<code> installs the whole module. validate_manifests.py requires all the records in a repository to share one version, and every skill folder to have a bmod.toml.
3. Validate
Section titled “3. Validate”Ask Smithy to validate the repository. It runs validate_manifests.py and checks each skill. Fix what it reports before you publish. See Validate.
4. Test a Local Install
Section titled “4. Test a Local Install”Add the module from its folder in a separate test project, then ask bmad to run bmad setup <code>. Run bmad status to confirm the module and version. Check that its questions read well, and that bmad recommends the skills as you intended.
npx skills add ./path/to/your-repo5. Publish
Section titled “5. Publish”Push to your Git host and tag the release. Tell users how to add the module, and to include the record.
npx skills add your-org/your-repoThen they ask bmad to run bmad setup acme. Users can pin to a tag with your-org/your-repo#v1.2.0. See Add Modules.
The repository does not have to be on GitHub: npx skills add takes any Git URL. For update checks from another host, set update_source to the https:// address of the folder holding your skill folders, served as raw files. A public repository appears on skills.sh once people install it with the Skills CLI. A module that ships inside a plugin sets update_source = "plugin:<name>", and its updates come through that plugin’s marketplace.
6. Ship Updates
Section titled “6. Ship Updates”- Bump
versionin the record for every release.bmad setupcompares it with the installed version to offer the update. - Add new skills to the record’s
skillslist. Add a help entry too, and a roster entry for an agent. - Record renames and removals in
retired.toml. Setup offers to delete the old skill and moves its custom files to the new name. Never reuse a retired name. - Ship a migration when users’ files must change. Add a
migration-<n>.tomlbesidebmod.toml, andbmad migratewill run it.
What You Get
Section titled “What You Get”- A module anyone with access can add with
npx skills add - Setup questions asked once per project, with answers kept in the project
- Guidance from the
bmadskill, based on your help files - Update checks against your source
- Clean handling of renamed and removed skills
- Write a README with what the module does, how to add it, and any outside tools it needs.
- Add a
LICENSE. - Use
pre_install_messagefor what users must know before an update, andpost_install_messagefor what to do after installing. - Use
required_skillsfor a skill your module invokes, with asourceand a minimumversionfor one from another repository. - Run a baseline eval before you publish. For a distributed skill, only that shows the skill beats the bare model on real cases.