> ## 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.

# 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

<Note>
  **Prerequisites**

  * BMad installed in your project (see [How to Install BMad](./install-bmad))
  * A text editor for YAML files
</Note>

<Warning>
  **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.
</Warning>

## Steps

### 1. Locate Customization Files

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

```text theme={null}
_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:

```yaml theme={null}
agent:
  metadata:
    name: 'Spongebob' # Default: "Amelia"
```

#### Persona

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

```yaml theme={null}
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:

```yaml theme={null}
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`:

```yaml theme={null}
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:

```yaml theme={null}
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"`:

```yaml theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](https://github.com/bmad-code-org/bmad-builder) for creating custom agents and workflows.