Authors and updates customization overrides for installed BMad skills, and changes to the document templates their agents write from. Use when the user says 'customize bmad', 'override a skill', 'change agent behavior', 'customize a workflow', or wants a document such as the PRD to ask for, contain or render something different
92%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Translate the user's intent into a correctly-placed TOML override file under {project-root}/_bmad/custom/ for a customizable agent or workflow skill, or into a template file when the change is to a document. 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.
{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.Greet the user. A change to a document, even one naming its skill or agent, goes to Document templates. Otherwise, if the user's invocation already names a target skill AND a specific change, jump to Step 3.
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.
Group the returned agents and workflows for the user; for each show name, description, whether has_team_override or has_user_override is true. Surface any errors[]. For audit/iterate intents, lead with already-overridden entries.
Empty list: show scanned_roots, ask whether skills live elsewhere (offer --extra-root); otherwise stop.
Read the target's customize.toml. Top-level [agent] or [workflow] block defines the surface.
If a team or user override already exists, read it first and summarize what's already overridden before composing.
Cross-cutting intent — walk both surfaces with the user:
bmad-agent-pm.toml with persistent_facts, principles).bmad-ux.toml with activation_steps_prepend).Single-surface heuristic:
*_template, on_complete). Surgical, reliable.When ambiguous, present both with tradeoff, recommend one, let the user decide.
Intent outside the exposed surface (step logic, ordering, anything not in customize.toml): say so; offer activation_steps_prepend/append or persistent_facts as approximations, or, if bmad-toolsmith is installed, recommend it to create a custom skill.
Translate plain-English into TOML against the target's customize.toml fields. If an existing override was read, frame the change as additive.
Merge semantics:
icon, role, *_template, on_complete) — override wins.persistent_facts, activation_steps_prepend/append, principles) — team/user entries append in order.code or id) — matching keys replace, new keys append.Overrides are sparse: only the fields being changed. Never copy the whole customize.toml.
Template swap (*_template scalar): offer to copy the default template to {project-root}/_bmad/custom/{skill-name}-{purpose}-template.md, point the override at the new path, offer to help edit it.
Every document bmad-facilitate writes, John's (bmad-agent-pm) and Mary's (bmad-agent-analyst) included, comes from a markdown template, not from TOML. The format is at https://docs.bmad-method.org/customize/write-a-document-template/.
uv run {project-root}/_bmad/scripts/list_templates.py --libraries-of <bmad-facilitate's folder> --libraries-of <each installed agent whose customize.toml sets template_libraries> --project-root {project-root} --root <folder> --brief, one --root per skills folder. Match the user's words to a template id; when more than one fits, such as prd and prd-light, ask which, or both.html_view). For every document → bmad-facilitate.toml through Steps 4–6: html_view for all, style, doc_standards, reviewers, output. When it could be either, ask, offering this document type first.{project-root}/_bmad/custom/facilitate-templates/<id>-<purpose>.md, or the user's existing extension of that id, updated. Read the template first, its file from the listing with --template <id>, then write only the change under extends: <id> frontmatter:
## section with a comment saying where it goes and what to ask. It is required unless the comment starts optional or include when. To replace a template section, use its heading and say so in the comment.stance, inputs, writing or done when comments, added to the template's.description, not_for, guidance, rubric, methods, output, style, view or html_view frontmatter, replacing the template's.facilitation_order only to reorder or remove the template's own sections; it replaces the whole order, and a template section it leaves out is removed, including one the template adds in a later update. Never set it just to place a new section: the section's comment places it.template id kept. For a different document beside it, such as a PRD for one team, give the copy a new id (prd-billing), its own description and not_for, and agents: naming the agent that should offer it; extensions of the original do not reach it. Either way, say the copy no longer receives updates to the original.~/.bmad/facilitate-templates/.--template <id> in place of --brief: show the template's extensions, merged facilitation_order, removed, view and html_view, and fix any order_problems before finishing.Under {project-root}/_bmad/custom/:
{skill-name}.toml — team, committed. Policies, org conventions, compliance.{skill-name}.user.toml — user, gitignored. Personal tone, private facts, shortcuts.Default by character (policy → team, personal → user), confirm before writing.
Show the full TOML. If the file exists, show a diff. Never silently overwrite.
Wait for explicit yes.
Write. Create {project-root}/_bmad/custom/ if needed.
Verify:
uv run {project-root}/_bmad/scripts/resolve_customization.py --skill <install-path> --project-root {project-root} --key <agent-or-workflow>Show the merged output, point out the changed fields.
Resolver missing or fails: read whichever layers exist — <install-path>/customize.toml (base), {project-root}/_bmad/custom/{skill-name}.toml (team), {project-root}/_bmad/custom/{skill-name}.user.toml (user) — apply base → team → user with the same merge rules (scalars override, tables deep-merge, code/id-keyed arrays merge by key, all other arrays append), describe how the changed fields resolve.
Verify shows override didn't land (field unchanged, merge conflict, file not picked up): re-enter Step 4 with the verify output as context. Usually wrong field name, wrong merge mode (scalar vs array), or wrong scope.
Summarize what changed, where the file lives, how to iterate. Remind the user to commit team overrides.
Otherwise the skill isn't done — finish or tell the user they're exiting incomplete.
{project-root}/_bmad/custom/config.toml) — see the How to Customize BMad guide.customize.toml — open a feature request, or, if bmad-toolsmith is installed, use it to create a custom skill. Offer to help with either.customize.toml — not customizable.bmad-code-org/BMAD-METHOD
e435a22
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.