Reference
Module Files
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
Section titled “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
Section titled “bmod.toml”A file holds a [bmod] table, a [skill] table, or both.
[bmod]
Section titled “[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]]
Section titled “[[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]]
Section titled “[[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]
Section titled “[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
Section titled “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/core-tools" },]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
Section titled “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/core-tools" }]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/core-tools" }]pre_install_message = ""post_install_message = ""
[skill]Reading Answers
Section titled “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_folderroster.toml
Section titled “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 = falseretired.toml
Section titled “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
Section titled “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
Section titled “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
Section titled “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.