---
title: 'How to Customize BMad'
description: Customize agents and workflows while preserving update compatibility
sidebar:
  order: 8
---

Tailor agent personas, inject domain context, add capabilities, and configure workflow behavior -- all without modifying installed files. Your customizations survive every update.

## When to Use This

- You want to change an agent's name, personality, or communication style
- You need to give an agent persistent facts to recall (e.g. "our org is AWS-only")
- You want to add procedural startup steps the agent must run every session
- You want to add custom menu items that trigger your own skills or prompts
- Your team needs shared customizations committed to git, with personal preferences layered on top

:::note[Prerequisites]

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

## How It Works

Every agent skill ships a `customize.yaml` file with its defaults. This file defines the skill's complete customization surface -- read it to see what's customizable. You never edit this file. Instead, you create sparse override files containing only the fields you want to change.

### Three-Layer Override Model

```text
Priority 1 (wins): _bmad/custom/{skill-name}.user.yaml  (personal, gitignored)
Priority 2:        _bmad/custom/{skill-name}.yaml        (team/org, committed)
Priority 3 (last): skill's own customize.yaml                    (defaults)
```

The `_bmad/custom/` folder starts empty. Files only appear when someone actively customizes.

### Merge Rules (per field)

| Field | Rule |
|---|---|
| `agent.metadata` | shallow merge -- scalar fields override |
| `agent.persona` | full replace -- if present in override, it replaces wholesale |
| `agent.critical_actions` | append -- override items are added after defaults |
| `agent.memories` | append |
| `agent.menu` | merge by `code` -- matching codes replace, new codes append |
| other tables | deep merge |
| other arrays | atomic replace |
| scalars | override wins |

## Steps

### 1. Find the Skill's Customization Surface

Look at the skill's `customize.yaml` in its installed directory. For example, the PM agent:

```text
.claude/skills/bmad-agent-pm/customize.yaml
```

(Path varies by IDE -- Cursor uses `.cursor/skills/`, Cline uses `.cline/skills/`, and so on.)

This file is the canonical schema. Every field you see is customizable.

### 2. Create Your Override File

Create the `_bmad/custom/` directory in your project root if it doesn't exist. Then create a file named after the skill:

```text
_bmad/custom/
  bmad-agent-pm.yaml        # team overrides (committed to git)
  bmad-agent-pm.user.yaml   # personal preferences (gitignored)
```

Only include the fields you want to change. Unmentioned fields inherit from the layer below.

### 3. Customize What You Need

#### Agent Persona

Change any combination of name, title, icon, role, identity, communication style, and principles. Anything under `agent.metadata` merges field-by-field; anything under `agent.persona` replaces the persona wholesale if you include it.

Team override (shallow merge on metadata):

```yaml
# _bmad/custom/bmad-agent-pm.yaml

agent:
  metadata:
    name: Priya
    title: Senior Product Lead
    icon: "🏥"
```

Team override (full persona replacement):

```yaml
agent:
  persona:
    role: "Senior Product Lead specializing in healthcare technology"
    identity: |
      15-year product leader in healthcare technology and digital health
      platforms. Deep expertise in EHR integrations and navigating
      FDA/HIPAA regulatory landscapes.
    communication_style: |
      Precise, regulatory-aware, asks compliance-shaped questions early.
    principles: |
      - Ship nothing that can't pass an FDA audit.
      - User value first, compliance always.
```

Because `agent.persona` is replace-wholesale, include every persona field you want the agent to have -- anything omitted will be blank.

#### Memories

Persistent facts the agent always recalls during the session:

```yaml
agent:
  memories:
    - "Our org is AWS-only -- do not propose GCP or Azure."
    - "All PRDs require legal sign-off before engineering kickoff."
    - "Target users are clinicians, not patients -- frame examples accordingly."
```

Memories append: your items are added after defaults.

#### Critical Actions

Procedural startup steps the agent must execute before presenting its menu:

```yaml
agent:
  critical_actions:
    - "Scan {project-root}/docs/compliance/ and load any HIPAA-related documents as context."
    - "Read {project-root}/_bmad/custom/company-glossary.md if it exists."
```

Critical actions append too. They run top-to-bottom on every activation.

#### Menu Customization

Add new capabilities or replace existing ones using `code` as the merge key. Each menu item has exactly one of `skill` (invokes a registered skill) or `prompt` (executes the text directly).

```yaml
agent:
  menu:
    # Replace the existing CE item with a custom skill
    - code: CE
      description: "Create Epics using our delivery framework"
      skill: custom-create-epics

    # Add a new item (code RC doesn't exist in defaults)
    - code: RC
      description: "Run compliance pre-check"
      prompt: |
        Read {project-root}/_bmad/custom/compliance-checklist.md
        and scan all documents in {planning_artifacts} against it.
        Report any gaps and cite the relevant regulatory section.
```

Items not listed in your override keep their defaults.

#### Referencing Files

When a field's text needs to point at a file (in `memories`, `critical_actions`, or a menu item's `prompt`), use a full path rooted at `{project-root}`. Even if the file sits next to your override in `_bmad/custom/`, spell out the full path: `{project-root}/_bmad/custom/info.md`. The agent resolves `{project-root}` at runtime.

### 4. Personal vs Team

**Team file** (`bmad-agent-pm.yaml`): Committed to git. Shared across the org. Use for compliance rules, company persona, custom capabilities.

**Personal file** (`bmad-agent-pm.user.yaml`): Gitignored automatically. Use for nickname preferences, tone adjustments, personal workflows.

```yaml
# _bmad/custom/bmad-agent-pm.user.yaml

agent:
  metadata:
    name: "Doc P"
  memories:
    - "Always include a rough complexity estimate (low/medium/high) when presenting options."
```

## How Resolution Works

On activation, the agent's SKILL.md runs a shared Node script that does the three-layer merge and returns the resolved `agent` block as JSON:

```bash
node {project-root}/_bmad/scripts/resolve-customization.js \
  --skill {skill-root} \
  --key agent
```

`--skill` points at the skill's installed directory (where `customize.yaml` lives). The skill name is derived from the directory's basename, and the script looks up `_bmad/custom/{skill-name}.yaml` and `{skill-name}.user.yaml` automatically.

Useful invocations:

```bash
# Resolve the full agent block
node {project-root}/_bmad/scripts/resolve-customization.js \
  --skill /abs/path/to/bmad-agent-pm \
  --key agent

# Resolve a single field
node {project-root}/_bmad/scripts/resolve-customization.js \
  --skill /abs/path/to/bmad-agent-pm \
  --key agent.metadata.name

# Full dump (everything under agent plus any other top-level keys)
node {project-root}/_bmad/scripts/resolve-customization.js \
  --skill /abs/path/to/bmad-agent-pm
```

Output is always JSON. If the script is unavailable on a given platform, the SKILL.md tells the agent to read the three YAML files directly and apply the same merge rules.

## Workflow Customization

Some workflows expose their own customization surface (output paths, review settings, section toggles, etc.) via the same `customize.yaml` + override mechanism. The merge rules above apply to any top-level key, not just `agent` -- so a workflow might use `workflow`, `config`, or other keys to organize its fields. Check the workflow's `customize.yaml` for its specific shape.

## Troubleshooting

**Customization not appearing?**

- Verify your file is in `_bmad/custom/` with the correct skill name
- Check YAML indentation (spaces only, no tabs) and make sure block scalars (`|`) are correctly indented
- For agents, customization lives under `agent:` -- keys written below it belong to that key until another top-level key begins
- Remember `agent.persona` is replace-wholesale: include every persona field you want, not just the ones you're changing

**Need to see what's customizable?**

- Read the skill's `customize.yaml` -- every field there is customizable

**Need to reset?**

- Delete your override file from `_bmad/custom/` -- the skill falls back to its built-in defaults