Agent Metadata Properties
| Property |
Format |
Rules |
id |
_bmad/agents/{agent-name}/{agent-name}.md |
Compiled output path; must match filename |
name |
"First Last" or "Name Title" |
Persona's identity (NOT title/filename) |
title |
"Role Name" (kebab-cased to filename) |
Determines filename: title → {title}.agent.yaml |
icon |
Single emoji only |
One emoji exactly |
module |
stand-alone, bmm, cis, bmgd, or custom |
Lowercase, hyphenated for stand-alone |
hasSidecar |
true or false |
true = expects {agent-name}-sidecar/ folder |
Field Rules
id
id: _bmad/agents/commit-poet/commit-poet.md
- Unique identifier for future lookup
- Conventionally matches filename pattern
name
# ✅ CORRECT
name: 'Inkwell Von Comitizen'
name: 'Dr. Demento'
name: 'Clarity'
# ❌ WRONG
name: 'commit-poet' # That's the filename
name: 'Code Review Specialist' # That's the title
title
# ✅ CORRECT
title: 'Commit Message Artisan'
title: 'Strategic Business Analyst'
title: 'Code Review Specialist'
# ❌ WRONG
title: 'Inkwell Von Comitizen' # That's the name
title: 'Writes git commits' # Full sentence, not functional title
- Derives filename via kebab-case
role field (separate) expands on what agent does in 1-2 sentences
icon
# ✅ CORRECT
icon: '🔧'
icon: '🧙♂️'
icon: '📜'
# ❌ WRONG
icon: '🔧📜' # Multiple emojis
icon: 'wrench' # Text, not emoji
icon: '' # Empty
module
| Value |
Meaning |
stand-alone |
Independent agent |
bmm |
Business Management Module |
cis |
Continuous Innovation System |
bmgd |
BMAD Game Development |
{custom} |
Any custom module code |
# ✅ CORRECT
module: stand-alone
module: bmm
# ❌ WRONG
module: standalone # Missing hyphen
module: 'BMM' # Uppercase
hasSidecar
# Simple Agent
hasSidecar: false
# Expert Agent (has sidecar folder)
hasSidecar: true
- If
true: compiler expects {agent-name}-sidecar/ folder
Name Confusion Prevention
| Question |
Answer |
| What's the file called? |
Derived from title: "Commit Message Artisan" → commit-message-artisan.agent.yaml |
| What's the persona called? |
name — "Inkwell Von Comitizen" |
| What's their job title? |
title — "Commit Message Artisan" |
| What do they do? |
role — 1-2 sentences expanding on title |
| What's the unique key? |
id — _bmad/agents/{name}/{name}.md |
Common Anti-Patterns
# ❌ name = title (duplicate)
name: 'Commit Message Artisan'
title: 'Commit Message Artisan'
# ✅ Fix: separate identity from role
name: 'Inkwell Von Comitizen'
title: 'Commit Message Artisan'
# ❌ id path mismatch
# File: my-agent.agent.yaml
id: _bmad/agents/different-agent/different-agent.md
# ✅ Fix: match filename
id: _bmad/agents/my-agent/my-agent.md
# ❌ Wrong module format
module: Standalone
module: STAND_ALONE
# ✅ Fix: lowercase, hyphenated
module: stand-alone
1fdfefe631