BMAD-METHOD/docs/modules/bmb-bmad-builder/agent-creation-guide.md

Agent Creation Guide

Create your own custom agents using the BMAD Builder workflow.

Overview

The BMAD Builder (BMB) module provides an interactive workflow that guides you through creating a custom agent from concept to completion. You define the agent's purpose, personality, capabilities, and menu - then the workflow generates a complete, ready-to-use agent file.

Before You Start

Prerequisites:

• BMAD installed with the BMB module
• An idea for what you want your agent to do

Know Before You Go:

• What problem should your agent solve?
• Who will use this agent?
• What should the agent be able to do?

Quick Start

1. Start the Workflow

In your IDE (Claude Code, Cursor, etc.), invoke the create-agent workflow with the agent-builder agent.

2. Follow the Steps

The workflow guides you through:

Step	What You'll Do
Brainstorm (optional)	Explore ideas with creative techniques
Discovery	Define the agent's purpose and goals
Type & Metadata	Choose Simple or Expert, name your agent
Persona	Craft the agent's personality and principles
Commands	Define what the agent can do
Activation	Set up autonomous behaviors (optional)
Build	Generate the agent file
Validation	Review and verify everything works

3. Install Your Agent

Once created, package your agent for installation:

my-custom-stuff/
├── module.yaml          # Contains: unitary: true
├── agents/
│   └── {agent-name}/
│       ├── {agent-name}.agent.yaml
│       └── _memory/              # Expert agents only
│           └── {sidecar-folder}/
└── workflows/           # Optional: custom workflows

See Custom Content Installation for details.

Choosing Your Agent Type

The workflow will help you decide, but here's the quick reference:

Choose Simple Agent When:

• Task is well-defined and focused
• Don't need persistent memory
• Want fast setup and deployment
• Single-purpose assistant (e.g., commit messages, code review)

Example: A "Code Commenter" that reads files and adds helpful comments.

Choose Expert Agent When:

• Domain requires specialized knowledge
• Need persistent memory across sessions
• Agent coordinates complex workflows
• Building ongoing project infrastructure

Example: A "Security Architect" that remembers your design decisions and maintains security standards across the project.

Choose Module Agent When:

• Agent builds other agents or workflows
• Need integration with module system
• Creating professional tooling

Example: A "Team Builder" that helps set up agents for new team members.

The Persona System

Your agent's personality is defined by four fields:

Field	Purpose	Example
Role	What they do	"Senior code reviewer who catches bugs and suggests improvements"
Identity	Who they are	"Friendly but exacting, believes clean code is a craft"
Communication Style	How they speak	"Direct, constructive, explains the 'why' behind suggestions"
Principles	Why they act	"Security first, clarity over cleverness, test what you fix"

Key: Keep each field focused on its purpose. The role isn't personality; the identity isn't job description.

Tips for Success

Start Small

Your first agent should solve one problem well. You can always add more capabilities later.

Learn by Example

Study the reference agents in src/modules/bmb/reference/agents/:

• Simple: commit-poet
• Expert: journal-keeper

Write Great Principles

The first principle should "activate" the agent's expertise:

❌ Weak: "Be helpful and accurate" ✅ Strong: "Channel decades of security expertise: threat modeling begins with trust boundaries, never trust client input, defense in depth is non-negotiable"

Use the Menu System

The workflow provides options at each step:

• [A] Advanced - Get deeper insights and reasoning
• [P] Party - Get multiple agent perspectives
• [C] Continue - Move to the next step

Use these when you need extra input or creative options.

After Creation

Test Your Agent

1. Install your custom module using the BMAD installer
2. Invoke your new agent in your IDE
3. Try each menu command
4. Verify the personality feels right

Iterate

If something isn't right:

1. Edit the agent YAML directly, or
2. Edit the customization file in _bmad/_config/agents/
3. Rebuild using npx bmad-method build <agent-name>

Share

Package your agent as a standalone module (see Installation Guide) and share it with your team or the community.

Further Reading

• Agent Architecture - Deep technical details on agent types
• Agent Customization - Modify agents without editing core files
• Custom Content Installation - Package and distribute your agents

---

Ready? Start the workflow and create your first agent!

← Back to BMB Documentation