Workflow Overview#

Goal: Create a custom BMAD agent skill for specialized domains

Phase: Builder Module

Agent: Builder

Inputs: Agent role, responsibilities, workflows, integration points

Output: Custom SKILL.md file ready for installation

Duration: 20-40 minutes

Pre-Flight#

1. Load context per helpers.md#Combined-Config-Load
2. Explain purpose:

   "I'll help you create a custom agent skill. This extends BMAD with domain-specific capabilities while following BMAD patterns for token optimization."

Agent Creation Process#

Use TodoWrite to track: Gather Requirements → Design Agent → Define Workflows → Specify Integration → Generate Skill → Test → Install

Part 1: Gather Requirements#

Ask user:

Q1: Agent Role

"What role should this agent perform?"

Examples:

• QA Engineer (testing, quality assurance)
• DevOps Engineer (deployment, infrastructure)
• Security Analyst (security audits, pen testing)
• Data Scientist (data analysis, model training)
• Technical Writer (documentation, guides)

Store as: {{agent_role}}

Q2: Domain/Phase

"Which BMAD phase or domain does this agent work in?"

Options:

1. Phase 1 - Analysis
2. Phase 2 - Planning
3. Phase 3 - Solutioning
4. Phase 4 - Implementation
5. Custom domain (specify)

Store as: {{agent_phase}}

Q3: Primary Responsibilities

"What are the 3-7 key responsibilities of this agent?"

Format as bulleted list. Be specific.

Store as: {{responsibilities_list}}

Part 2: Define Core Principles#

Explain:

"Agents follow core principles that guide their approach. Let's define 3-5 principles for your agent."

Ask:

"What principles should guide this agent?"

Examples for QA Engineer:

• Test Early - Find bugs before production
• Comprehensive Coverage - Test all critical paths
• Automate Everything - Manual testing doesn't scale

Examples for DevOps:

• Infrastructure as Code - Everything version controlled
• Automate Deployment - Humans don't deploy, systems do
• Monitor Everything - You can't improve what you don't measure

Format each:

**[Principle Name]** - [Description]

Store as: {{core_principles}}

Part 3: Define Workflows#

Ask:

"What workflows (commands) will this agent execute?"

List 1-5 commands this agent will handle.

Format: /command-name - Description

Example for QA Engineer:

- /create-test-plan - Create comprehensive test plan
- /execute-tests - Run test suite
- /bug-report - Generate bug report
- /test-coverage - Analyze test coverage

Store as: {{available_commands}}

Part 4: Specify Integration Points#

Ask:

"Which other BMAD agents or tools will this agent work with?"

Probe:

• Works after which agents? (receives input from)
• Works before which agents? (hands off to)
• Works alongside which tools? (collaborates with)

Example for QA Engineer:

**Works after:**
- Developer - Receives code for testing
- Product Manager - Receives acceptance criteria

**Works before:**
- Developer - Reports bugs for fixing

**Works with:**
- Test frameworks, CI/CD tools, bug trackers

Store as: {{integration_points}}

Part 5: Domain-Specific Guidance#

Ask:

"Any domain-specific guidance for LLMs executing this agent?"

Examples:

• Specific tools to use (pytest, Jest, Selenium)
• Frameworks to follow (BDD, TDD)
• Standards to apply (OWASP, PCI-DSS)
• Common patterns in this domain

Store as: {{domain_guidance}}

Part 6: Generate Skill File#

Determine file path:

Module: bmb (builder module for custom agents)
Role:  { { agent_role } }   (normalized: lowercase, hyphens)
Path: ~/.claude/skills/bmad/bmb/ { { role-name } } /SKILL.md (user config — 사용자 레벨 설치 위치)

Generate SKILL.md using template:

---
skill_id: bmad-bmb- { { role-name } } 
 name:  { { agent_role } } 
 description:  { { one-line-description } } 
 version: 1.0.0
module: bmb
---

#  { { agent_role } } 

 **Role:**  { { agent_phase } }   specialist

**Function:**  { { summary-of-function } } 

 ## Responsibilities

 { { responsibilities_list } } 

 ## Core Principles

 { { core_principles } } 

 ## Available Commands

 { { available_commands } } 

 ## Workflow Execution

**All workflows follow helpers.md patterns:**

1. **Load Context** - See `helpers.md#Combined-Config-Load`
2. **Check Status** - See `helpers.md#Load-Workflow-Status`
3. **Execute Workflow** - Domain-specific process
4. **Generate Output** - See `helpers.md#Apply-Variables-to-Template`
5. **Update Status** - See `helpers.md#Update-Workflow-Status`
6. **Recommend Next** - See `helpers.md#Determine-Next-Workflow`

## Integration Points

 { { integration_points } } 

 ## Critical Actions (On Load)

When activated:
1. Load project config per `helpers.md#Load-Project-Config`
2. Check workflow status per `helpers.md#Load-Workflow-Status`
3.  { { domain-specific-setup } } 

 ##  { { Domain-Specific Section } } 

 { { domain_guidance } } 

 ## Notes for LLMs

- Use TodoWrite to track workflow tasks
- Reference helpers.md sections for all common operations
-  { { domain-specific-llm-guidance } } 
 - Follow BMAD patterns (functional, token-optimized)
- Update workflow status after completion

## Example Interaction

User: /{{example-command}}

{{agent_role}}: {{example-interaction}}

 **Remember:**  { { key-reminder-for-agent } }

Part 7: Validate and Review#

Display generated skill to user:

Show the skill file content and ask:

"Here's your custom agent skill. Review:"

Agent: {{agent_role}} Responsibilities: {{count}} Commands: {{count}} Module: bmb

Does this look correct? Any changes needed?

If changes: Iterate and regenerate

Part 8: Save Skill File#

Save to project (for review):

./custom-agents/ { { role-name } } /SKILL.md

Instructions for installation:

✓ Custom Agent Created!

Agent:  { { agent_role } } 
 File: ./custom-agents/ { { role-name } } /SKILL.md

## Installation:

1. **Copy to Claude skills directory:**
   

mkdir -p ~/.claude/skills/bmad/bmb/{{role-name}} # install to user config cp ./custom-agents/{{role-name}}/SKILL.md ~/.claude/skills/bmad/bmb/{{role-name}}/ # install to user config

 2. **Restart Claude Code**
   New skills load on restart

3. **Test the agent**
   Create a workflow command for this agent with /create-workflow

## Next Steps:

- Create workflow commands: /create-workflow
- Create templates: /create-template
- Update BMad Master to route to this agent (if needed)

Recommend Next Steps#

✓ Agent skill created!

Next: Create workflow commands

Run /create-workflow to create the commands this agent executes.

Recommended workflows for  { { agent_role } } :
 { { suggested-workflows } }

Helper References#

• Load config: helpers.md#Combined-Config-Load
• Save document: helpers.md#Save-Output-Document

Tips for Effective Custom Agents#

Keep it functional:

• Focus on what the agent DOES
• Avoid persona/character details
• Clear responsibilities

Follow BMAD patterns:

• Reference helpers.md
• Use TodoWrite for workflows
• Token-optimized (no redundancy)
• Integration points defined

Domain-specific but not siloed:

• Agents should work with existing BMAD workflows
• Hand off to other agents when appropriate
• Use standard BMAD status tracking

Token-conscious:

• Use helpers.md references instead of embedding instructions
• Keep skill files focused and minimal
• Leverage existing patterns

Notes for LLMs#

• Use TodoWrite to track 8 agent creation steps
• Follow BMAD skill template strictly
• Ensure integration points are clear
• Generate functional, non-persona-based skills
• Ask clarifying questions for domain details
• Test generated skill structure
• Provide clear installation instructions
• Suggest logical next steps (creating workflows/templates)

Remember: Custom agents extend BMAD's capabilities while maintaining its token-optimized, pattern-based architecture. They should feel native to BMAD, not like external plugins.