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
Keep Your Customizations SafeAlways 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 |
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'
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'
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:
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 |
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. 