Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bmad-code-org/BMAD-METHOD/llms.txt

Use this file to discover all available pages before exploring further.

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
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.
SectionBehaviorPurpose
agent.metadataReplacesOverride the agent’s display name
personaReplacesSet role, identity, style, and principles
memoriesAppendsAdd persistent context the agent always recalls
menuAppendsAdd custom menu items for workflows or prompts
critical_actionsAppendsDefine startup instructions for the agent
promptsAppendsCreate 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'
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:
OptionWhat It Does
Quick UpdateUpdates all modules to the latest version and recompiles all agents
Recompile AgentsApplies customizations only, without updating module files
Modify BMad InstallationFull 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us