Brian
fc6a41c673
* feat(toolsmith): make a single-skill module the default for one skill Registration is settled from the registry and shown in the read-back instead of asked. A skill joins a module only when the user is working on that module, named it, or chose its prefix. A bmod-<code> record folder is never written for one skill. * fix(toolsmith): ask whether a skill is part of a module Single-skill module stays the offered guess, but discovery now asks whether the skill joins a module or more skills are planned. A planned module settles its code and prefix on the first skill, so nothing is renamed later. * feat(toolsmith): read any agent's session logs and offer customization in from-logs The agent finds its own logs and confirms the location instead of assuming Claude Code. A corrected installed skill can be offered as a bmad-customize change instead of a new skill. * refactor(toolsmith): split discover into short sections and cut what a model infers Registration gets its own section, the five things and other enumerable items become lists, and the read-back carries the consumer and bar. * feat(toolsmith): start prose from one sentence and hold one topic to a paragraph The canon, leanness lens and cut roles now default to the one-sentence version of a passage and split mixed topics. The pre-pass reports long paragraphs and sentences. * refactor(toolsmith): cut prompt files to one topic per paragraph and inline ecosystem into ship Every route, mode and shape file is split into short paragraphs, bullets and cases, with what a model would infer removed. ecosystem.md only ever loaded from ship.md, so its content now lives there. * feat(toolsmith): let a memory agent add its name to its description at First Breath * fix(toolsmith): close a Markdown fence only on its own marker in the pre-pass * fix(toolsmith): let a single-skill module grow into a multi-skill module * fix(toolsmith): write dependencies to the table the module shape uses * feat(toolsmith): restore a memory agent's name after an update and skip global installs * docs(toolsmith): bring the help up to date and route to cut mode * refactor(toolsmith): call the read-back the Smithy execution plan and add help on sharing and subagents * docs(toolsmith): write the Toolsmith docs to replace the builder site
6.0 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Modules and Registration | What a BMad module is, what registering a skill gives you, the three ways a skill can register, and when to use configuration or customization. |
|
A module is a set of skills that belong together, with a record that tells the bmad skill about them. Registering a skill with a module is what lets BMad set it up, recommend it, and check it for updates. This page explains the choices. The exact keys are in Module Files.
What Registering Gives You
| With a record | Without one |
|---|---|
bmad setup <code> asks the skill's questions |
Setup never sees the skill |
The bmad skill recommends it from help |
Help does not know it exists |
| Update checks follow its source | You update it yourself |
| Other skills can require it at a minimum version | Other skills can require it by name only |
A skill with no record still works, and it can still read BMad config and customization.
Three Ways to Register
Smithy asks whether a skill is part of a module and whether more are planned, then puts the answer in the execution plan.
| Registration | What it is | Use it when |
|---|---|---|
| Single-skill module | One folder is both the skill and its record | The default for one skill |
| Member of a module | A small bmod.toml names the record, and the record lists the skill |
You are building or expanding that module |
| Plain skill | No bmod.toml |
You want no record, or the project has no _bmad/ folder |
A planned module of several skills starts as a single-skill module under its code and prefix, so nothing is renamed later. Smithy moves the record to a bmod-<code> folder when the second skill arrives, either when you package the skills or when you build the second one into the module. Smithy never writes a record folder for one skill.
A plain skill can register later: convert mode adds a record to one skill, and package mode wraps several.
What a Module Holds
A single-skill module keeps everything in the skill's folder. Its bmod.toml has a [bmod] table and an empty [skill] table, and a help/help.md sits beside it. A skill with nothing to ask has no configuration questions.
A multi-skill module has a record folder, bmod-<code>, beside the skills it ships.
| In the record | Purpose |
|---|---|
SKILL.md |
Tells anyone who opens it to run bmad setup <code>, and does nothing else |
bmod.toml |
Code, version, source, members, dependencies, questions, and install messages |
help/help.md |
What the bmad skill reads to guide users, with optional topic files |
roster.toml |
The module's agents, so bmad and party mode know who is available |
retired.toml |
Skills renamed or removed, so setup can clean up |
Each member has its own small bmod.toml that names the record and its source, and lists what that skill alone requires. A skill belongs to one module. A skill it uses from another module is a dependency, not a member.
Name Skills and Modules
Skills carry the module's code as a prefix: acme-release-notes, and agents acme-agent-scout. bmad finds a module by its [bmod] table, and validation requires a multi-skill record folder to be bmod-<code>. The code is the configuration namespace and what users type in bmad setup <code>.
A prefix of your own tells your skills from BMad's, keeps a module's skills together in listings, and lets you group them in traces and usage reports. Reserve bmad- for skills shipped by the bmad-code-org. A custom skill named bmad- reads as official, and it could collide with a future core skill.
Configuration or Customization
Modules offer two ways to change behavior, and they answer different questions.
| Configuration | Customization | |
|---|---|---|
| Answers | What does this project need to tell the module? | How should this skill behave differently here? |
| Defined in | [[bmod.config_questions]] in the record |
customize.toml in each skill |
| Set by | bmad setup <code> |
bmad-customize |
| Read as | modules.<code>.<key> with resolve_config.py |
{workflow.<key>} or {agent.<key>} after resolve_customization.py |
| Example | A shared path every member reads | An activation step for one skill |
Use a configuration question for a value several skills read the same way. It is asked once, and every member reads the answer. Skip the question when a good default will do, because every question is a cost at setup. See Make a Skill Customizable for the other side.
A scope = "user" question is a personal preference and is not committed. A path the team shares stays team scope.
Write the Help
help/help.md has one reader: the bmad skill, answering a user. Write what each skill gives, when to recommend it, and what to offer next. Leave out what bmad cannot act on, such as install mechanics and manifest keys.
Add a help/<topic>.md for depth, and name it in help.md with when to read it. A topic that help.md does not name is never read.
Depend on Other Skills
Use required_skills for a skill yours invokes, and recommended_skills for one that helps beside it. A plain name is a skill from the same source, and a table names one from elsewhere. Module-wide needs go in the record, and one member's needs go in its own file. Smithy asks during a build, and names anything you need to install.
Add to the BMad Method
Two different things are often called this.
- Contribute to the method. Open a pull request to the BMAD-METHOD repository. The skill lives under
skills/, takes abmad-name, and itsbmod.tomlnamesbmod-method. - Extend the method in your project. Make your own module with your own prefix, whose skills require or recommend the method skills they build on. Do not edit the installed method record, because the next update overwrites it.
Build any change to an installed module in its source repository for the same reason.