How to Customize BMad

Customize agents, workflows, and modules while preserving update compatibility

Use the .customize.yaml files to tailor agent behavior, personas, and menus while preserving your changes across updates.

When to Use This

• You want to change an agent’s name, personality, or communication style
• You need agents to remember project-specific context
• You want to add custom menu items that trigger your own workflows or prompts
• You want agents to perform specific actions every time they start up

Prerequisites

• BMad installed in your project (see How to Install BMad)
• A text editor for YAML files

Keep Your Customizations Safe

Always use the .customize.yaml files described here rather than editing agent files directly. The installer overwrites agent files during updates, but preserves your .customize.yaml changes.

Steps

1. Locate Customization Files

After installation, find one .customize.yaml file per agent in:

_bmad/_config/agents/
├── core-bmad-master.customize.yaml
├── bmm-dev.customize.yaml
├── bmm-pm.customize.yaml
└── ... (one file per installed agent)

2. Edit the Customization File

Open the .customize.yaml file for the agent you want to modify. Every section is optional — customize only what you need.

Section	Behavior	Purpose
agent.metadata	Replaces	Override the agent’s display name
persona	Replaces	Set role, identity, style, and principles
memories	Appends	Add persistent context the agent always recalls
menu	Appends	Add custom menu items for workflows or prompts
critical_actions	Appends	Define startup instructions for the agent
prompts	Appends	Create reusable prompts for menu actions

Sections marked Replaces overwrite the agent’s defaults entirely. Sections marked Appends add to the existing configuration.

Agent Name

Change how the agent introduces itself:

agent:
  metadata:
    name: 'Spongebob' # Default: "Amelia"

Persona

Replace the agent’s personality, role, and communication style:

persona:
  role: 'Senior Full-Stack Engineer'
  identity: 'Lives in a pineapple (under the sea)'
  communication_style: 'Spongebob annoying'
  principles:
    - 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep'
    - 'Favor composition over inheritance'

The persona section replaces the entire default persona, so include all four fields if you set it.

Memories

Add persistent context the agent will always remember:

memories:
  - 'Works at Krusty Krab'
  - 'Favorite Celebrity: David Hasslehoff'
  - 'Learned in Epic 1 that it is not cool to just pretend that tests have passed'

Menu Items

Add custom entries to the agent’s display menu. Each item needs a trigger, a target (workflow path or action reference), and a description:

menu:
  - trigger: my-workflow
    workflow: 'my-custom/workflows/my-workflow.yaml'
    description: My custom workflow
  - trigger: deploy
    action: '#deploy-prompt'
    description: Deploy to production

Critical Actions

Define instructions that run when the agent starts up:

critical_actions:
  - 'Check the CI Pipelines with the XYZ Skill and alert user on wake if anything is urgently needing attention'

Custom Prompts

Create reusable prompts that menu items can reference with action="#id":

prompts:
  - id: deploy-prompt
    content: |
      Deploy the current branch to production:
      1. Run all tests
      2. Build the project
      3. Execute deployment script

3. Apply Your Changes

After editing, recompile the agent to apply changes:

npx bmad-method install

The installer detects the existing installation and offers these options:

Option	What It Does
Quick Update	Updates all modules to the latest version and recompiles all agents
Recompile Agents	Applies customizations only, without updating module files
Modify BMad Installation	Full installation flow for adding or removing modules

For customization-only changes, Recompile Agents is the fastest option:

npx bmad-method install --action compile-agents --directory .

Troubleshooting

Changes not appearing?

• Run npx bmad-method install and select Recompile Agents to apply changes
• Check that your YAML syntax is valid (indentation matters)
• Verify you edited the correct .customize.yaml file for the agent

Agent not loading?

• Check for YAML syntax errors using an online YAML validator
• Ensure you did not leave fields empty after uncommenting them
• Try reverting to the original template and rebuilding

Need to reset an agent?

• Clear or delete the agent’s .customize.yaml file
• Run npx bmad-method install and select Recompile Agents to restore defaults

Workflow Customization

Customization of existing BMad Method workflows and skills is coming soon.

Module Customization

Guidance on building expansion modules and customizing existing modules is coming soon. For now, see BMad Builder for creating custom agents and workflows.