BMAD-METHOD/docs/how-to-create-custom-agent-bmad-method.md

title
Create a Custom Agent Using BMAD Method Workflows

Use the BMAD Method workflows to design, build, and deploy a custom AI agent from initial concept to a delightful interactive persona that users love engaging with. This guide follows the development of a Teacher's Assistant agent to illustrate the concepts, but these same workflows apply to any custom agent project.

When to Use This

• You want to create a specialized AI persona for specific domain expertise
• You need an agent that guides users through multi-step processes in your field
• You want to design custom interactive workflows beyond standard BMAD agents
• You need an agent that embodies specific communication styles and knowledge areas
• You're building agents for educational, professional, or specialized use cases

When to Skip This

• Simple modifications to existing agents (use agent customization instead)
• One-off custom prompts or simple AI interactions
• Complex AI systems requiring custom training (this focuses on persona and workflow design)

:::note[Prerequisites]

• BMAD Core Platform installed with BMM module
• Understanding of your target domain and user needs
• Familiarity with BMAD agent interaction patterns
• Access to Brainstorm Agent and Custom Agent Builder workflows :::

:::tip[Quick Path] Initialize project → Brainstorm agent concepts → Define agent persona and capabilities → Build agent structure → Create workflows and menus → Test and refine → Deploy and document. The entire process typically takes 2-4 focused work sessions to go from idea to working custom agent. :::

Understanding Custom Agent Creation

The BMAD Method approaches custom agent creation through systematic design and implementation workflows that ensure your agent delivers real value and delightful user experiences.

Phase	Name	What Happens
1	Ideation	Brainstorm agent purpose, capabilities, personality (collaborative)
2	Design	Define agent persona, communication style, knowledge domains (structured)
3	Architecture	Plan agent workflows, menu systems, interaction patterns (technical)
4	Implementation	Build agent files, configure activation sequences (systematic)
5	Testing	Validate agent behavior, refine personality, test workflows (iterative)
6	Deployment	Integrate agent into BMAD ecosystem, create documentation (production)

Single Agent Method

All steps accomplished through one agent:

/bmad:bmb:agents:agent-builder

The Agent Builder is a comprehensive Expert Agent that guides you through all phases of agent creation in a single workflow session. It handles brainstorming, discovery, type classification, persona development, menu structure, activation planning, and agent compilation without needing multiple specialized agents.

Steps

Step 1: Initialize Your Agent Creation Session

General Process: Start the Agent Builder to begin comprehensive agent development using its step-file architecture.

/bmad:bmb:agents:agent-builder
3. [CA] Create a new BMAD agent with best practices and compliance

Teacher's Assistant Example: When prompted for initial agent concept:

• Agent name: "Teacher's Assistant"
• Primary domain: "Education and learning facilitation"
• Target users: "Students seeking homework help and concept understanding"
• Agent scope: "Socratic questioning, scaffolding techniques, progress tracking"

Your Application: Provide these key elements for any agent:

• Clear agent purpose (e.g., "help therapists with session planning", "guide developers through code reviews", "assist writers with story development")
• Target user definition (e.g., "healthcare professionals", "marketing teams", "creative professionals")
• Domain expertise scope (e.g., "financial planning", "project management", "technical documentation")

Step 2: Brainstorm Agent Concepts and Capabilities

General Process: The Agent Builder includes optional brainstorming in Step 1. When you choose to brainstorm, select from 4 specialized technique approaches:

1. User-Selected Techniques - Browse the complete technique library
2. AI-Recommended Techniques - Customized suggestions based on your goals (includes web research)
3. Random Technique Selection - Discover unexpected creative methods
4. Progressive Technique Flow - Start broad, then systematically narrow focus

Each approach helps you discover your agent's essence - the living personality AND the utility it provides.

Teacher's Assistant Example: Using AI-Recommended Techniques approach, we discovered:

• Core purpose: "Guide students through understanding using educational best practices without providing direct answers"
• Key capabilities: "Socratic questioning, scaffolding techniques, progress tracking, adaptive teaching methods"
• Personality traits: "Patient mentor, educationally rigorous, never gives up on student learning"

Your Application: Define these elements for any agent:

• Core purpose: What main problem does your agent solve for users?
• Key capabilities: What specific tasks should your agent excel at?
• Personality traits: How should your agent communicate and behave?

Step 2a: Discovery Conversation Phase

General Process: After brainstorming, the workflow includes a comprehensive discovery conversation that establishes your agent's scope, context, target users, and special features. This prevents re-asking questions in later development phases and generates a comprehensive agent plan document.

Teacher's Assistant Example: Discovery conversation explored:

• Target Scope: All educational interactions across grade levels and subjects
• Primary Context: Home tutoring and independent study environments
• Communication Strategy: Age-appropriate language complexity while maintaining concept integrity
• Persistence Philosophy: "No giving up allowed" - always find alternative approaches
• Progress Tracking: Subject-specific learning profiles with technique effectiveness monitoring
• Validation Approaches: Student explanation + pop-quiz verification of understanding

Your Application: The discovery phase will explore for any agent:

• Target Scope: Who specifically will use your agent and in what contexts?
• Primary Context: Where and how will your agent be used most frequently?
• Communication Strategy: How should your agent adapt its communication style?
• Core Philosophy: What principles guide your agent's decision-making?
• Special Features: What unique capabilities set your agent apart?

Step 3: Determine Agent Type and Define Metadata

General Process: The workflow systematically classifies your agent and defines all required metadata properties:

• Simple Agent: Single-purpose, stateless, all-in-one file (~250 lines max)
• Expert Agent: Persistent memory, sidecar folder, domain-specific expertise
• Module Agent: Extends existing BMAD modules or requires multiple interconnected agents

Teacher's Assistant Example:

• Classification: Expert Agent (requires persistent memory for learning profiles)
• Rationale: Student progress tracking, technique effectiveness monitoring, evolving teaching strategies
• Metadata Properties:
  • ID: teachers-assistant
  • Name: Sophia Chen
  • Title: Educational Learning Facilitator
  • Icon: 🎓
  • Module: stand-alone
  • Has Sidecar: true

Your Application: For any agent, the system will determine:

• Agent Type: Based on memory requirements and complexity needs
• Technical Properties: ID (kebab-case), persona name, professional title
• Visual Identity: Appropriate emoji icon for your domain
• Ecosystem Placement: Stand-alone vs integration with existing modules

Step 4: Develop Four-Field Persona System

General Process: The workflow uses a sophisticated four-field persona system that creates distinct, non-overlapping personality dimensions:

• Role: WHAT they do (capabilities, expertise, knowledge areas)
• Identity: WHO they are (background, experience, character)
• Communication Style: HOW they speak (tone, patterns, voice)
• Principles: WHY they act (decision framework, values, constraints)

Teacher's Assistant Example:

persona:
  role: >
    Educational learning facilitator specializing in Socratic questioning, scaffolding techniques,
    and progress-based teaching that guides students to discover answers rather than providing direct instruction.    

  identity: >
    Master educator with deep knowledge of educational psychology, constructivist learning theory,
    and adaptive teaching methods. Passionate advocate for authentic learning through struggle and self-discovery.    

  communication_style: >
    Speaks like a patient mentor using strategic questioning, encouraging language, and age-appropriate
    complexity while maintaining conceptual integrity.    

  principles:
    - Channel expert educational psychology wisdom: draw upon Zone of Proximal Development, scaffolding techniques, metacognitive strategies, and research-backed methods that facilitate genuine understanding
    - Never provide direct answers - guide students to discover solutions through strategic questioning and multiple explanation pathways
    - Authentic learning requires productive struggle - frustration signals growth, not failure
    - Track what works for each student and adapt techniques accordingly - analogies for some, examples for others
    - Academic boundaries are sacred - redirect non-educational conversations back to learning focus

Your Application: For any agent, you'll develop:

• Role: Professional capabilities and expertise your agent provides
• Identity: Background, experience, and character that makes them credible
• Communication Style: How your agent speaks and interacts with users
• Principles: Decision framework and values that guide behavior

The first principle serves as an "expert activator" that tells the AI to access domain-specific knowledge and frameworks.

Step 5: Commands & Menu Structure Design

General Process: Transform discovered capabilities into structured menu commands following BMAD patterns:

• Capability Review: Analyze all capabilities from the discovery phase
• Command Grouping: Organize related capabilities under logical command areas
• Menu Pattern Application: Follow BMAD Expert Agent menu structure requirements
• Trigger Design: Create intuitive 2-letter codes and fuzzy match patterns
• Handler Definition: Map commands to specific prompts or actions

Teacher's Assistant Example: Created 9 educational commands with Expert Agent architecture:

critical_actions:
  - 'Load COMPLETE file {project-root}/_bmad/_memory/teachers-assistant-sidecar/learning-profiles.md'
  - 'Load COMPLETE file {project-root}/_bmad/_memory/teachers-assistant-sidecar/technique-tracking.md'
  - 'ONLY read/write files in {project-root}/_bmad/_memory/teachers-assistant-sidecar/'

prompts:
  - id: socratic-guidance
    content: |
      <instructions>Guide student through learning using Socratic questioning without giving direct answers</instructions>
      <process>1. Ask strategic questions 2. Use student interests for analogies 3. Encourage discovery 4. Validate understanding</process>      

menu:
  - trigger: LG or fuzzy match on learn-guide
    action: '#socratic-guidance'
    description: '[LG] Learning guidance through Socratic questioning'

  - trigger: QM or fuzzy match on quiz-me
    action: 'Generate pop-quiz on recent or struggling concepts from learning profile'
    description: '[QM] Quiz me on challenging concepts'

  - trigger: SA or fuzzy match on study-aids
    action: '#study-aids-generator'
    description: '[SA] Generate study aids (flashcards, practice problems, guides)'

Your Application: For any agent, you'll create commands organized by:

• Primary Functions: Core capabilities users access most frequently
• Utility Commands: Support functions like help, settings, progress tracking
• Advanced Features: Specialized tools for power users
• Memory Management: For Expert agents with persistent data needs

Design principles include 2-letter triggers, fuzzy matching, action handlers, and proper sidecar integration for Expert agents.

Step 6: Activation Planning

General Process: Define how your agent behaves when it starts up through critical actions and startup sequences:

• Reference Loading: Understanding critical action patterns
• Routing Decision: Determining build path (Simple/Expert/Module) based on architecture
• Activation Needs Discussion: Deciding autonomous vs responsive behavior patterns
• Critical Actions Definition: Specifying startup commands for memory loading and boundaries

Teacher's Assistant Example:

activation:
  hasCriticalActions: true
  rationale: "Agent needs to auto-load student learning context to provide personalized educational guidance"
  criticalActions:
    - 'Load COMPLETE file {project-root}/_bmad/_memory/teachers-assistant-sidecar/learning-profiles.md'
    - 'Load COMPLETE file {project-root}/_bmad/_memory/teachers-assistant-sidecar/technique-tracking.md'
    - 'ONLY read/write files in {project-root}/_bmad/_memory/teachers-assistant-sidecar/'

routing:
  destinationBuild: "step-07b-build-expert.md"
  rationale: "Expert agent requires sidecar memory for persistent learning profiles"

Your Application: For any agent, consider:

• Startup Needs: What must your agent load or initialize when it starts?
• Memory Requirements: Does your agent need persistent data between sessions?
• Security Boundaries: What file access restrictions should be enforced?
• Operational Philosophy: Responsive to prompts vs autonomous background tasks?

Routing logic determines the build path based on your agent's architecture needs.

Step 7: Expert Agent Build and Compilation

General Process: The Agent Builder automatically compiles all phases into the final .agent.yaml file:

1. Generates Agent YAML: Combines persona, menu, activation, and metadata
2. Creates Sidecar Structure: Sets up memory folders for Expert agents
3. Validates Configuration: Ensures BMAD compliance and proper structure
4. Provides Installation: Generates installation guidance

Teacher's Assistant Example: Generated complete Expert agent with this structure:

agents/
└── teachers-assistant/
    ├── teachers-assistant.agent.yaml    # Complete agent definition
    └── teachers-assistant-sidecar/      # Expert agent memory (build location)
        ├── learning-profiles.md         # Student progress and preferences
        ├── technique-tracking.md        # Teaching method effectiveness data
        └── README.md                   # Sidecar documentation

Critical actions use proper path variables: {project-root}/_bmad/_memory/{sidecar-folder}/ for runtime operation.

Your Application: For any agent, this step produces:

• Agent YAML: Complete agent definition with proper BMAD compliance
• Sidecar Structure: Memory folders and files for Expert agents
• Path Configuration: Proper variable usage for portability
• Documentation: README files and installation guidance

Step 8: Celebration and Installation Guidance

General Process: The Agent Builder provides comprehensive installation instructions and celebrates completion. To make any agent installable, create a standalone BMAD content module with:

• Module directory with module.yaml containing unitary: true
• Agent files in agents/agent-name/ structure
• Sidecar folder in _memory/ for Expert agents

Teacher's Assistant Example: Created this installable module structure:

my-educational-agents/
├── module.yaml                              # Contains: unitary: true
├── agents/
│   └── teachers-assistant/
│       ├── teachers-assistant.agent.yaml    # Main agent definition
│       └── _memory/                         # Expert agent memory
│           └── teachers-assistant-sidecar/
│               ├── learning-profiles.md
│               ├── technique-tracking.md
│               └── README.md

Installation methods include new project setup or adding to existing BMAD installations.

Your Application: For any agent, follow these installation principles:

• Module Structure: Use unitary: true for standalone agent modules
• File Organization: Place agent files in proper directory hierarchy
• Memory Management: Include _memory/ structure for Expert agents
• Distribution: Package entire module directory for sharing

Installing and Using Your Custom Agent

After completing agent creation, follow these steps to install and start using your new agent:

Step 1: Create Module Directory Structure

General Process: Transform your agent output into a BMAD-installable module:

# Navigate to your project root
cd /your/project/root

# Create module directory
mkdir -p my-custom-agents

# Create module configuration
echo "unitary: true" > my-custom-agents/module.yaml

# Create agents directory structure
mkdir -p my-custom-agents/agents

Step 2: Organize Agent Files

General Process: Move your completed agent files into the proper module structure:

# Copy agent directory from bmb-creations output
cp -r /path/to/_bmad-output/bmb-creations/your-agent my-custom-agents/agents/

# For Expert agents, organize sidecar structure
mkdir -p my-custom-agents/agents/your-agent/_memory
mv my-custom-agents/agents/your-agent/your-agent-sidecar my-custom-agents/agents/your-agent/_memory/

Teacher's Assistant Example:

my-educational-agents/
├── module.yaml                              # Contains: unitary: true
├── agents/
│   └── teachers-assistant/
│       ├── teachers-assistant.agent.yaml    # Main agent definition
│       └── _memory/                         # Expert agent memory
│           └── teachers-assistant-sidecar/
│               ├── learning-profiles.md
│               ├── technique-tracking.md
│               └── README.md

Step 3: Install Module in BMAD

General Process: Add your custom module to an existing or new BMAD project:

For New Projects:

1. Run BMAD installer: npx @bmad-method/cli init
2. When prompted for local modules, provide the path to your module
3. Installer will automatically integrate your agent

For Existing Projects:

1. Run: npx @bmad-method/cli modify
2. Select "Add local custom module"
3. Provide path to your module directory
4. Confirm installation

Step 4: Activate Your Agent

General Process: Once installed, your agent becomes available through BMAD's command system:

# List available agents (verify your agent appears)
/agents

# Activate your agent using its module path
/bmad:your-module:agents:your-agent

Teacher's Assistant Example:

/bmad:my-educational-agents:agents:teachers-assistant

Step 5: Test Agent Functionality

General Process: Start with basic interactions to verify your agent works correctly:

Initial Activation Test:

/bmad:your-module:agents:your-agent

Basic Conversation Examples:

• "Hi [Agent Name], what can you help me with?"
• "Show me your available commands"
• "Tell me about your capabilities"

Teacher's Assistant Example: Specific conversation starters that test educational capabilities:

• "Help me understand fractions without giving me the answer"
• "LG" (Learning Guidance command)
• "QM" (Quiz Me command)
• "SA" (Study Aids command)

Step 6: Verify Expert Agent Memory (If Applicable)

General Process: For Expert agents with sidecar folders, confirm memory persistence:

1. Start agent and interact with memory commands
2. Update profiles or tracking data
3. Restart agent and verify data persists

Teacher's Assistant Example:

UP (Update Profile command)
LP (Learning Progress command)

Troubleshooting Common Installation Issues

Agent Not Found:

• Verify module.yaml exists with unitary: true
• Check agent file is in agents/agent-name/agent-name.agent.yaml
• Confirm BMAD installation included your module

Sidecar Memory Issues (Expert Agents):

• Ensure _memory/agent-sidecar/ structure exists
• Verify critical_actions reference correct file paths
• Check file permissions for read/write access

Command Not Working:

• Test basic interaction first before specialized commands
• Verify agent activation completed successfully
• Check for any startup errors in agent logs

Sharing Your Agent

To share your agent with others:

1. Package entire module directory: my-custom-agents/
2. Include installation instructions: Reference this guide
3. Provide example interactions: Show how to use key features
4. Document dependencies: Any special requirements or modules

Distribution Options:

• Git Repository: Push module directory to version control
• Archive File: Zip module directory for direct sharing
• BMAD Community: Submit to community agent library (if available)

Your custom agent is now ready for production use and can be shared across BMAD installations!

Summary

The BMAD Agent Builder provides a comprehensive, single-agent solution for creating production-ready BMAD agents. Through its step-file architecture, it guides you through the complete end-to-end process:

1. Brainstorming (optional) - Creative exploration using 4 specialized technique approaches
2. Discovery - Comprehensive capability and context definition with agent-plan documentation
3. Type Classification - Automatic Simple/Expert/Module architecture determination
4. Four-Field Persona - Role, identity, communication style, and principles development
5. Commands & Menu - Structured command interface with BMAD compliance
6. Activation Planning - Critical actions definition and routing determination
7. Agent Build - Complete YAML file generation with sidecar structure
8. Installation Guidance - Module packaging instructions and testing recommendations

Complete Agent Creation in One Session:

/bmad:bmb:agents:agent-builder → [CA] Create a new BMAD agent → Continue through all steps

Process Results:

• Production-Ready Files: Complete .agent.yaml with proper BMAD compliance
• Expert Architecture: Sidecar folder structure with memory files and security boundaries
• Installation Package: Module structure with module.yaml for BMAD integration
• Testing Guidelines: Conversation starters and command validation approaches
• Documentation: Comprehensive agent plan and sidecar README for maintenance

Key Advantages:

• Single Agent Workflow: Complete process without switching between multiple agents
• BMAD Compliance: Automatic adherence to all standards, patterns, and architectural requirements
• Expert Memory Management: Proper sidecar setup with runtime path variables and file boundaries
• Specialized Domain Integration: Research-backed methodology incorporation
• Production Installation: Ready-to-install module structure with proper configuration

Teacher's Assistant Case Study Achievement:

• Expert Agent: 9 educational commands with persistent memory architecture
• Educational Psychology Integration: Socratic method, scaffolding techniques, ZPD assessment
• Complete Workflow: From concept to installable module in single session
• Memory Architecture: Student learning profiles and technique effectiveness tracking
• BMAD Compliance: Full validation and proper sidecar configuration

Time Investment: Typically 2-4 focused work sessions to go from initial idea to production-ready, installable custom agent with comprehensive capabilities and professional-quality implementation.

The BMAD Agent Creation Method transforms agent concepts into production-ready implementations efficiently and systematically, handling all technical complexity while maintaining focus on agent personality and user value delivery.