6.4 KiB

Raw Blame History

Simple Agent Architecture

Self-contained agents with prompts, menus, and optional install-time customization.

When to Use

Single-purpose utilities (commit message generator, code formatter)
Self-contained logic with no external dependencies
Agents that benefit from user customization (style, tone, preferences)
Quick-to-build standalone helpers

YAML Structure

agent:
  metadata:
    id: _bmad/agents/{agent-name}/{agent-name}.md
    name: 'Persona Name'
    title: 'Agent Title'
    icon: 'emoji'
    type: simple

  persona:
    role: |
      First-person description of primary function (1-2 sentences)      

    identity: |
      Background, experience, specializations in first-person (2-5 sentences)
      {{#if custom_variable}}
      Conditional identity text based on install_config
      {{/if}}      

    communication_style: |
      {{#if style_choice == "professional"}}
      Professional and systematic approach...
      {{/if}}
      {{#if style_choice == "casual"}}
      Friendly and approachable tone...
      {{/if}}      

    principles:
      - Core belief or methodology
      - Another guiding principle
      - Values that shape decisions

  prompts:
    - id: main-action
      content: |
        <instructions>
        What this prompt does
        </instructions>

        <process>
        1. Step one
        {{#if detailed_mode}}
        2. Additional detailed step
        {{/if}}
        3. Final step
        </process>        

    - id: another-action
      content: |
        Another reusable prompt template        

  menu:
    - trigger: inline
      action: 'Direct inline prompt text'
      description: 'Execute inline action'

    - multi: "[DF] Do Foo or start [CH] Chat with expert"
      triggers:
        - do-foo
            - input: [DF] or fuzzy match on do foo
            - action: '#main-action'
            - data: what is being discussed or suggested with the command, along with custom party custom agents if specified
            - type: action
        - expert-chat:
            - input: [CH] or fuzzy match validate agent
            - action: agent responds as expert based on its persona to converse
            - type: action

  install_config:
    compile_time_only: true
    description: 'Personalize your agent'
    questions:
      - var: style_choice
        prompt: 'Preferred communication style?'
        type: choice
        options:
          - label: 'Professional'
            value: 'professional'
          - label: 'Casual'
            value: 'casual'
        default: 'professional'

      - var: detailed_mode
        prompt: 'Enable detailed explanations?'
        type: boolean
        default: true

      - var: custom_variable
        prompt: 'Your custom text'
        type: text
        default: ''

Key Components

Metadata

id: Final compiled path (_bmad/agents/{name}/{name}.md for standalone)
name: Agent's persona name displayed to users
title: Professional role/function
icon: Single emoji for visual identification
type: simple - identifies agent category

Persona (First-Person Voice)

role: Primary expertise in 1-2 sentences
identity: Background and specializations (2-5 sentences)
communication_style: HOW the agent interacts, including conditional variations
principles: Array of core beliefs (start with action verbs)

Prompts with IDs

Reusable prompt templates referenced by #id:

prompts:
  - id: analyze-code
    content: |
      <instructions>
      Analyze the provided code for patterns
      </instructions>

Menu items reference these:

menu:
  - trigger: analyze
    action: '#analyze-code'
    description: 'Analyze code patterns'

Two forms of action handlers:

Prompt Reference: action: "#prompt-id" - Executes prompt content
Inline Instruction: action: "Direct text instruction" - Executes text directly

Install Config (Compile-Time Customization)

Questions asked during bmad agent-install:

Question Types:

choice - Multiple choice selection
boolean - Yes/no toggle
text - Free-form text input

Variables become available in Handlebars:

{{#if variable_name}}
Content when true
{{/if}}

{{#if variable_name == "value"}}
Content when equals value
{{/if}}

{{#unless variable_name}}
Content when false
{{/unless}}

What Gets Injected at Compile Time

The tools/cli/lib/agent/compiler.js automatically adds:

YAML Frontmatter

---
name: 'agent name'
description: 'Agent Title'
---

Activation Block
- Load persona step
- Load core config for {user_name}, {communication_language}
- Agent-specific critical_actions as numbered steps
- Menu display and input handling
- Menu handlers (action/workflow/exec/tmpl) based on usage
- Rules section
Auto-Injected Menu Items
- *help always first
- *exit always last
Trigger Prefixing
- Triggers without * get it added automatically

Reference Example

See: ../../reference/agents/simple-examples/commit-poet.agent.yaml

Features demonstrated:

Handlebars conditionals for style variations
Multiple prompt templates with semantic XML tags
Install config with choice, boolean, and text questions
Menu items using both #id references and inline actions

Installation

# Copy to your project
cp /path/to/commit-poet.agent.yaml _bmad/custom/agents/

# Create custom.yaml and install
echo "code: my-agent
name: My Agent
default_selected: true" > custom.yaml

npx bmad-method install
# or: bmad install

The installer:

Prompts for personalization (name, preferences)
Processes Handlebars templates with your answers
Compiles YAML to XML-in-markdown
Creates IDE slash commands
Saves source for reinstallation

Best Practices

Use first-person voice in all persona elements
Keep prompts focused - one clear purpose per prompt
Leverage Handlebars for user customization without code changes
Provide sensible defaults in install_config
Use semantic XML tags in prompt content for clarity
Test all conditional paths before distribution

Validation Checklist

Valid YAML syntax
All metadata fields present (id, name, title, icon, type)
Persona complete (role, identity, communication_style, principles)
Prompts have unique IDs
Install config questions have defaults
File named {agent-name}.agent.yaml

6.4 KiB Raw Blame History