BMad Customize

Translate the user's intent into a correctly-placed TOML override file under {project-root}/_bmad/custom/ for a customizable agent or workflow skill. Discover, route, author, write, verify.

Scope v1: per-skill [agent] overrides (bmad-agent-<role>.toml / .user.toml) and per-skill [workflow] overrides (bmad-<workflow>.toml / .user.toml). Central config ({project-root}/_bmad/custom/config.toml) is out of scope, point users at the How to Customize BMad guide.

When the target's customize.toml doesn't expose what the user wants, say so plainly. Don't invent fields.

Preflight

• No {project-root}/_bmad/ → BMad is not set up here. Offer to run the bmad skill's setup, installing bmad first if you do not have it (npx skills add bmad-code-org/BMAD-METHOD --skill bmad). Stop if the user declines.
• {project-root}/_bmad/scripts/resolve_customization.py missing → continue, but Step 6 verify falls back to manual merge.
• Both present → proceed.

Activation

Greet the user. If the user's invocation already names a target skill AND a specific change, jump to Step 3.

Step 1: Classify intent

• Directed, specific skill + specific change → Step 3.
• Exploratory, "what can I customize?" → Step 2.
• Audit/iterate, wants to review or change something already customized → Step 2, lead with skills that have existing overrides; read the existing override in Step 3 before composing.
• Cross-cutting, could live on multiple surfaces → Step 3, choose agent vs workflow explicitly with the user.

Step 2: Discovery

uv run {skill-root}/scripts/list_customizable_skills.py --project-root {project-root}

Use --extra-root <path> (repeatable) if the user has skills installed in additional locations.