BMAD-METHOD/docs/how-to/customize-bmad.md

title	description	sidebar
How to Customize BMad	Customize agents and workflows while preserving update compatibility	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)
• 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

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:

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

_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):

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

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

Team override (full persona replacement):

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:

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:

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

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.

# _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:

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:

# 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