Skip to content

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.

FileMulti-skill moduleSingle-skill module
bmod.toml with [bmod]In the bmod-<code> record folderIn the skill’s folder
bmod.toml with [skill]In each member’s folderThe same file, with [skill] empty
help/help.mdIn the record folderIn the skill’s folder
SKILL.mdThe record has one that only redirects to bmad setup <code>The skill’s own
roster.toml, retired.toml, migration-<n>.tomlIn the record folderBeside 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.

A file holds a [bmod] table, a [skill] table, or both.

KeyRequiredMeaning
codeYesConfiguration namespace and the name in bmad setup <code>. Cannot be _config, custom, modules, or scripts
versionYesThe module’s version, compared with its source to offer updates
update_sourceYesWhere updates come from. Starts with github:, https://, file:, or plugin:
skillsMulti-skillEvery member skill
required_skillsNoSkills the module needs, see Dependencies
recommended_skillsNoSkills that help beside it. Setup reports them and does not insist
pre_install_messageFor validationShown before an update, or before bmad installs the record itself
post_install_messageFor validationShown 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.

Each entry is one question for bmad setup <code>, asked in file order.

KeyRequiredMeaning
keyYesDotted key, read as modules.<code>.<key>. Must not be the code or start with <code>.
promptYesThe question text
defaultYesThe default answer, with {project-root} kept literal
scopeNoteam, the default, or user for a personal answer that is not committed

No other keys are allowed.

Optional. Lists extra help documents inside the record folder, with path and skills. skills is "*", the default, or a list of skill names.

KeyRequiredMeaning
bmodIn a member fileThe record folder, such as bmod-acme
sourceIn a member fileMust equal the record’s update_source
required_skillsNoWhat this skill alone requires
recommended_skillsNoWhat helps beside this skill
scriptsNoPaths 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.

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.

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]

A skill reads a setup answer with one call, listing every key it needs.

Terminal window
uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key modules.acme.release_folder

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

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"]

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/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.

In a repository with skills/*/bmod.toml:

Terminal window
uv run {project-root}/_bmad/scripts/validate_manifests.py --project-root <repo>

It covers manifests, membership, versions, retired names, help topics, and the roster.