216 lines
6.8 KiB
Markdown
216 lines
6.8 KiB
Markdown
---
|
|
title: 'How to Customize BMad'
|
|
description: Customize agents, workflows, and modules 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 inject domain-specific context (compliance rules, company guidelines)
|
|
- You want to add custom menu items that trigger your own skills or inline instructions
|
|
- You want to configure workflow behavior (output paths, review settings, default modes)
|
|
- 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 TOML files
|
|
:::
|
|
|
|
## How It Works
|
|
|
|
Every skill that supports customization ships a `customize.toml` file with its defaults. This file defines the skill's complete customization surface -- look at 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/customizations/{name}.user.toml (personal, gitignored)
|
|
Priority 2: _bmad/customizations/{name}.toml (team/org, committed)
|
|
Priority 3 (last): skill's own customize.toml (defaults)
|
|
```
|
|
|
|
The `_bmad/customizations/` folder starts empty. Files only appear when someone actively customizes.
|
|
|
|
### Override Rules
|
|
|
|
- **Tables and scalars:** sparse override. Only include the fields you want to change; everything else inherits from the layer below.
|
|
- **Arrays replace atomically.** When you override an array field (like `additional_resources`), include the complete array you want.
|
|
- **Menu items use merge-by-code.** Menu entries with a matching `code` replace that item; new codes add items. Items not mentioned keep their defaults.
|
|
|
|
## Steps
|
|
|
|
### 1. Find the Skill's Customization Surface
|
|
|
|
Look at the `customize.toml` in the skill's source directory. For example, the PM agent's defaults:
|
|
|
|
```text
|
|
src/bmm-skills/2-plan-workflows/bmad-agent-pm/customize.toml
|
|
```
|
|
|
|
This file documents every customizable field with comments and examples.
|
|
|
|
### 2. Create Your Override File
|
|
|
|
Create the `_bmad/customizations/` directory in your project root if it doesn't exist. Then create a file named after the skill:
|
|
|
|
```text
|
|
_bmad/customizations/
|
|
bmad-agent-pm.toml # team overrides (committed to git)
|
|
bmad-agent-pm.user.toml # 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, identity, communication style, and principles:
|
|
|
|
```toml
|
|
# _bmad/customizations/bmad-agent-pm.toml
|
|
|
|
[persona]
|
|
displayName = "Priya"
|
|
title = "Senior Product Lead"
|
|
icon = "🏥"
|
|
|
|
identity = """\
|
|
15-year product leader in healthcare technology and digital health \
|
|
platforms. Deep expertise in EHR integrations and navigating \
|
|
FDA/HIPAA regulatory landscapes."""
|
|
```
|
|
|
|
Fields you omit (like `communicationStyle` and `principles` above) keep their defaults.
|
|
|
|
#### Injected Context
|
|
|
|
Add domain-specific context that loads before or after the agent's core instructions:
|
|
|
|
```toml
|
|
[inject]
|
|
before = """\
|
|
CRITICAL CONTEXT: All product work must comply with:
|
|
- HIPAA Privacy and Security Rules
|
|
- FDA 21 CFR Part 11
|
|
- SOC 2 Type II"""
|
|
|
|
after = """\
|
|
Always remind the user that CRB review is required before \
|
|
development begins on clinical features."""
|
|
```
|
|
|
|
#### Additional Resources
|
|
|
|
Load extra files into the agent's context:
|
|
|
|
```toml
|
|
additional_resources = [
|
|
"_bmad/resources/company-product-playbook.md",
|
|
"_bmad/resources/regulatory-checklist.md",
|
|
]
|
|
```
|
|
|
|
Since `additional_resources` is an array, include the complete list you want -- it replaces, not appends.
|
|
|
|
#### Menu Customization
|
|
|
|
Add new capabilities or replace existing ones using the `code` as the merge key:
|
|
|
|
```toml
|
|
# Replaces existing CE item with a custom skill
|
|
[[menu]]
|
|
code = "CE"
|
|
description = "Create Epics using our delivery framework"
|
|
action = "skill"
|
|
skill = "custom-create-epics"
|
|
|
|
# Adds a new item (code RC doesn't exist in defaults)
|
|
[[menu]]
|
|
code = "RC"
|
|
description = "Run compliance pre-check"
|
|
action = "inline"
|
|
instruction = """\
|
|
Scan all documents in {planning_artifacts} for compliance gaps..."""
|
|
```
|
|
|
|
Items not listed keep their SKILL.md defaults.
|
|
|
|
#### Workflow Configuration
|
|
|
|
Workflows expose config fields specific to their behavior:
|
|
|
|
```toml
|
|
# _bmad/customizations/bmad-product-brief.toml
|
|
|
|
[config]
|
|
alwaysGenerateDistillate = true
|
|
|
|
[config.sections]
|
|
users = { enabled = true, weight = "high" }
|
|
successCriteria = { enabled = true, weight = "high" }
|
|
|
|
[[config.customSections]]
|
|
name = "Regulatory Impact"
|
|
description = "Classify this product under regulatory framework..."
|
|
weight = "high"
|
|
|
|
[review]
|
|
contextualReviewLens = "Regulatory and clinical safety risk reviewer"
|
|
```
|
|
|
|
### 4. Personal vs Team
|
|
|
|
**Team file** (`bmad-agent-pm.toml`): Committed to git. Shared across the org. Use for compliance rules, company persona, custom capabilities.
|
|
|
|
**Personal file** (`bmad-agent-pm.user.toml`): Gitignored automatically. Use for nickname preferences, tone adjustments, personal workflows.
|
|
|
|
```toml
|
|
# _bmad/customizations/bmad-agent-pm.user.toml
|
|
|
|
[persona]
|
|
displayName = "Doc P"
|
|
|
|
[inject]
|
|
after = """\
|
|
When presenting options, always include a rough complexity estimate \
|
|
(low/medium/high) so I can gauge engineering effort at a glance."""
|
|
```
|
|
|
|
## How Resolution Works
|
|
|
|
Customization values are resolved just-in-time when needed -- not all loaded at activation. Each skill includes a `resolve-customization.py` script that handles the three-layer merge:
|
|
|
|
```bash
|
|
# Resolve a single field
|
|
python ./scripts/resolve-customization.py bmad-agent-pm --key persona.displayName
|
|
|
|
# Resolve an entire section
|
|
python ./scripts/resolve-customization.py bmad-agent-pm --key persona
|
|
|
|
# Full dump
|
|
python ./scripts/resolve-customization.py bmad-agent-pm
|
|
```
|
|
|
|
Output is JSON. When the script is unavailable (web platforms, etc.), the LLM reads the TOML files directly using the same priority order.
|
|
|
|
## Troubleshooting
|
|
|
|
**Customization not appearing?**
|
|
|
|
- Verify your file is in `_bmad/customizations/` with the correct skill name
|
|
- Check TOML syntax (comments start with `#`, strings use `"`, multi-line strings use `"""`)
|
|
- Ensure `additional_resources` is at the top of your file, before any `[table]` header -- TOML scoping puts all keys after a `[table]` inside that table
|
|
|
|
**Need to see what's customizable?**
|
|
|
|
- Read the skill's `customize.toml` -- it documents every field with comments and examples
|
|
|
|
**Need to reset?**
|
|
|
|
- Delete your override file from `_bmad/customizations/` -- the skill falls back to its built-in defaults
|