Skip to content

Migrate an Old Module

Use Smithy’s migrate mode to convert an old-format module into the current format, in place. A module built before the bmod format carries a setup skill, a module.yaml, and a module-help.csv, and it does not work with bmad setup.

  • Your module has a <code>-setup skill, or a module-setup.md in a skill’s assets
  • It carries module.yaml and module-help.csv
  • It writes to _bmad/config.yaml or _bmad/module-help.csv, or its skills read _bmad/<code>/config.yaml
  • Smithy’s validate mode reported it as an old-format module

Ask Smithy to migrate the module, and point at the folder holding its skills and setup skill. For a one-skill module, point at the skill’s own folder. Smithy scans the module and asks only for the update_source.

Smithy shows the whole execution plan as tables and waits for your yes. Nothing changes before that.

OldNew
The setup skill, merge scripts, and any bmad-manifest.jsonDeleted, with the setup skill listed as removed in retired.toml
module.yamlbmod-<code>/bmod.toml, with one question per config key
Agentsroster.toml
module-help.csvhelp/help.md, with a topic file for a skill that has many rows
Each skillA bmod.toml with a [skill] table
A folder with one skillA single-skill module, with no bmod-<code> folder

The skills’ content converts too. The execution plan maps each old config read and each old placeholder, such as {planning_artifacts} or {communication_language}, to its current form. Each skill reads every key it uses in one resolve_config.py call when it activates, and placeholders for keys that still exist, such as {output_folder}, stay as they are.

  • output_folder becomes core.output_folder.
  • planning_artifacts and implementation_artifacts become the initiative folder, {output_folder}/{active_initiative}. A document goes in <type>-<slug>/<type>-<slug>.md under it.
  • project_knowledge has no current key. Smithy asks whether the module needs its own question for it, or names the project’s docs folder in the text.
  • user_name, communication_language, document_output_language, and user_skill_level have no current key. Their reads are removed, and a sentence built on one of their placeholders is rewritten without it.
  • A module key becomes modules.<code>.<key>. A key that repeats the code must be renamed.
  • Fallbacks to the old per-module file are removed.

The execution plan also lists what cannot convert:

Old featureWhat happens
Select questionsBecome one string, with the options in the prompt, or are dropped
Validation, directories, and post-install notesHave no equivalent, so the skill handles them or they go
Headless and inline-argument setupRemoved, because bmad setup has neither
Answers in _bmad/config.yamlNot carried over, so bmad setup <code> asks again

Smithy writes the new files, rewrites each config read and placeholder, and removes each skill’s step that ran the setup skill. Where one skill’s output path changes, it updates every skill that reads that path. It lists the skills a member invokes from other modules as dependencies, and replaces retired skill names with their successors. It then deletes the listed files and nothing else.

Smithy runs the validators on the result and fixes what they find, then finishes with its ship step.

Ask bmad to run bmad setup <code>. Answer the questions again, because old answers are not carried over.

  • A module that bmad can set up, recommend, and update
  • Skills that read their configuration through resolve_config.py
  • A list of what could not convert, so you can decide how to handle it
  • Commit before you start, so you can read the whole change as a diff.
  • Update your README to replace any old install steps with npx skills add. See Distribute Your Module.
  • Check .claude-plugin/marketplace.json if your repository has one. The current install path does not need it.