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.7 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Module Files | The files that make a BMad module: bmod.toml, roster.toml, retired.toml, migration files, and help, with every key and rule. |
|
Use this page for the exact keys in a module's files. For what a module is and how to choose a registration, see Modules and Registration. Smithy writes these files for you, and validate_manifests.py checks them.
Where the Files Live
| File | Multi-skill module | Single-skill module |
|---|---|---|
bmod.toml with [bmod] |
In the bmod-<code> record folder |
In the skill's folder |
bmod.toml with [skill] |
In each member's folder | The same file, with [skill] empty |
help/help.md |
In the record folder | In the skill's folder |
SKILL.md |
The record has one that only redirects to bmad setup <code> |
The skill's own |
roster.toml, retired.toml, migration-<n>.toml |
In the record folder | Beside bmod.toml |
bmad finds a module by its [bmod] table. Validation requires a multi-skill record folder to be named bmod-<code>, and a single-skill module's folder keeps the skill's name.
bmod.toml
A file holds a [bmod] table, a [skill] table, or both.
[bmod]
| Key | Required | Meaning |
|---|---|---|
code |
Yes | Configuration namespace and the name in bmad setup <code>. Cannot be _config, custom, modules, or scripts |
version |
Yes | The module's version, compared with its source to offer updates |
update_source |
Yes | Where updates come from. Starts with github:, https://, file:, or plugin: |
skills |
Multi-skill | Every member skill |
required_skills |
No | Skills the module needs, see Dependencies |
recommended_skills |
No | Skills that help beside it. Setup reports them and does not insist |
pre_install_message |
For validation | Shown before an update, or before bmad installs the record itself |
post_install_message |
For validation | Shown after installing |
Setup accepts a record without the install messages, but validate_manifests.py requires both keys, empty if unused.
A github: source is github:<owner>/<repo>/<path>, where <path> is the folder holding the skill folders, such as skills. With no path, the repository root is the skill. Update checks read bmod.toml from the main branch.
[[bmod.config_questions]]
Each entry is one question for bmad setup <code>, asked in file order.
| Key | Required | Meaning |
|---|---|---|
key |
Yes | Dotted key, read as modules.<code>.<key>. Must not be the code or start with <code>. |
prompt |
Yes | The question text |
default |
Yes | The default answer, with {project-root} kept literal |
scope |
No | team, the default, or user for a personal answer that is not committed |
No other keys are allowed.
[[bmod.knowledge]]
Optional. Lists extra help documents inside the record folder, with path and skills. skills is "*", the default, or a list of skill names.
[skill]
| Key | Required | Meaning |
|---|---|---|
bmod |
In a member file | The record folder, such as bmod-acme |
source |
In a member file | Must equal the record's update_source |
required_skills |
No | What this skill alone requires |
recommended_skills |
No | What helps beside this skill |
scripts |
No | Paths written like scripts/foo.py that setup installs to _bmad/<code>/scripts/ |
In a single-skill module, leave [skill] empty unless it declares scripts, because the record in the same file already names the module's one skill.
Dependencies
A plain name is a skill from the same source. A table names a skill from elsewhere.
required_skills = [
"acme-release-notes",
{ skill = "bmad", version = "6.13.0", source = "github:bmad-code-org/BMAD-METHOD/skills" },
]
version is optional. Module-wide needs go in [bmod], including all of a single-skill module's needs. One member's needs go in its [skill] table.
Examples
A record:
[bmod]
code = "acme"
version = "1.0.0"
update_source = "github:acme/skills/skills"
skills = ["acme-release-notes", "acme-agent-scout"]
required_skills = [{ skill = "bmad", version = "6.13.0", source = "github:bmad-code-org/BMAD-METHOD/skills" }]
pre_install_message = ""
post_install_message = ""
[[bmod.config_questions]]
key = "release_folder"
prompt = "Where should release notes go?"
default = "{project-root}/docs/releases"
A member:
[skill]
bmod = "bmod-acme"
source = "github:acme/skills/skills"
A single-skill module:
[bmod]
code = "acme"
version = "0.1.0"
update_source = "github:acme/acme-release-notes/skills"
required_skills = [{ skill = "bmad", version = "6.13.0", source = "github:bmad-code-org/BMAD-METHOD/skills" }]
pre_install_message = ""
post_install_message = ""
[skill]
Reading Answers
A skill reads a setup answer with one call, listing every key it needs.
uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key modules.acme.release_folder
roster.toml
Required when a member is an agent. It is how bmad and party mode know who is available. A member with skill is an agent, present only while that skill is installed. A member without skill is a guest who exists only in groups.
[[members]]
code = "acme-agent-scout"
skill = "acme-agent-scout"
name = "Scout"
icon = "🔭"
title = "Release Scout"
persona = "Two sentences on who this agent is."
[[groups]]
id = "release-team"
name = "Release Team"
scene = "A release readiness meeting."
members = ["acme-agent-scout"]
memory = false
retired.toml
Lists skills the module no longer ships. bmad setup offers to delete any still installed, and moves a renamed skill's _bmad/custom/ files to the new name. A retired name is never reused, and a name can appear only once.
renamed = [{ from = "acme-notes", to = "acme-release-notes" }]
removed = ["acme-old-check"]
migration-<n>.toml
A module ships a migration beside its bmod.toml, and bmad migrate runs them in <n> order. The file has a [migration] table with module, from, to, title, summary, detect, guide, and a checklist array. A file missing any of these is not listed. The file holds the rules, and bmad follows them.
Help Files
help/help.md covers the whole module and is read by the bmad skill. Every other help/*.md is a topic file, read only when help.md names it. See Write the Help.
Validate
In a repository with skills/*/bmod.toml:
uv run {project-root}/_bmad/scripts/validate_manifests.py --project-root <repo>
It covers manifests, membership, versions, retired names, help topics, and the roster.