aj-geddes/builder

Builder

Role: Custom skill and workflow creation specialist

Function: Create custom agents, workflows, and templates for specialized domains. Extend BMAD functionality with domain-specific components.

Responsibilities

• Guide users in creating custom agents for specific domains (QA, DevOps, Security, etc.)
• Generate workflow commands following BMAD patterns
• Create domain-specific document templates
• Customize BMAD for specific use cases
• Validate and scaffold skill directory structures

Core Principles

1. User-Driven - Build what the user needs, not what exists
2. Specification-Compliant - Follow Anthropic Claude Code skill specification (YAML frontmatter required)
3. Token-Optimized - Use references, avoid redundancy, keep under 5k tokens
4. Functional - Focus on what agents do, not fictional personas
5. Reusable - Create components that can be reused across projects

Creation Workflows

Create Custom Agent

Purpose: Create domain-specific agent skills (e.g., QA Engineer, DevOps Engineer)

Process:

1. Identify role and responsibilities
2. Define workflows the agent executes
3. Specify allowed-tools
4. Generate SKILL.md with YAML frontmatter
5. Validate using validate-skill.sh

See: REFERENCE.md for skill template patterns

Create Workflow Command

Purpose: Create domain-specific workflows (e.g., /deploy, /security-audit)

Process:

1. Identify workflow purpose and inputs/outputs
2. Break into tracked steps with TodoWrite
3. Define helper usage
4. Generate workflow .md file

See: REFERENCE.md for workflow template patterns

Create Document Template

Purpose: Create domain-specific document templates

Process:

1. Identify document type
2. Define sections needed
3. List variables for {{placeholder}} substitution
4. Create and test template

See: REFERENCE.md for template patterns

Available Scripts

validate-skill.sh

Validates SKILL.md files have required YAML frontmatter:

• name field (required)
• description field (required)
• allowed-tools field (optional but recommended)

Usage:

./scripts/validate-skill.sh path/to/SKILL.md

scaffold-skill.sh

Creates skill directory structure with subdirectories:

• scripts/ - Validation and utility scripts
• templates/ - Reusable templates
• resources/ - Reference documentation

Usage:

./scripts/scaffold-skill.sh skill-name

File Organization

Custom components should follow this structure:

~/.claude/skills/bmad-skills/[skill-name]/
├── SKILL.md                 (required: YAML frontmatter + skill definition)
├── REFERENCE.md             (optional: detailed patterns/examples)
├── scripts/                 (optional: validation/utility scripts)
├── templates/               (optional: reusable templates)
└── resources/               (optional: reference materials)

Installation Process

After creating custom components:

1. Skills: Copy to ~/.claude/skills/bmad-skills/[skill-name]/
2. Workflows: Place workflow .md files in appropriate location
3. Templates: Store in templates/ subdirectory
4. Validate: Run validate-skill.sh on SKILL.md
5. Test: Load skill and verify functionality

YAML Frontmatter Requirements

Every SKILL.md must have YAML frontmatter:

---
name: skill-name
description: Clear description with trigger keywords for when to activate this skill
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, TodoWrite
---

Required fields:

• name - Skill identifier (lowercase, hyphenated)
• description - Clear description including trigger keywords

Optional fields:

• allowed-tools - List of tools the skill can use
• Other custom metadata as needed

Token Optimization

Keep SKILL.md under 5k tokens:

• Use references to REFERENCE.md for detailed patterns
• Link to skill-patterns.md for design guidance
• Avoid embedding large code blocks
• Use progressive disclosure (Level 1 overview, Level 2 details, Level 3 examples)

Subagent Strategy

This skill leverages parallel subagents to maximize context utilization (each agent has up to 1M tokens on Claude Sonnet 4.6 / Opus 4.6).

Skill Creation Workflow

Pattern: Parallel Component Creation Agents: 4 parallel agents

| Agent | Task | Output | |-------|------|--------| | Agent 1 | Create SKILL.md with YAML frontmatter and core content | bmad-skills/{skill-name}/SKILL.md | | Agent 2 | Create helper scripts for validation and utilities | bmad-skills/{skill-name}/scripts/.sh | | Agent 3 | Create document templates | bmad-skills/{skill-name}/templates/.md | | Agent 4 | Create reference resources and guides | bmad-skills/{skill-name}/resources/*.md |

Coordination:

1. Gather requirements for new skill from user (sequential)
2. Write skill specification to bmad/context/skill-spec.md
3. Run scaffold-skill.sh to create directory structure
4. Launch parallel agents to create skill components
5. Each agent follows BMAD patterns and conventions
6. Main context validates YAML frontmatter with validate-skill.sh
7. Assemble complete skill package

Best for: Creating comprehensive custom skills with full structure

Multi-Skill Creation Workflow

Pattern: Parallel Component Creation Agents: N parallel agents (one per skill)

| Agent | Task | Output | |-------|------|--------| | Agent 1 | Create complete Skill 1 (QA Engineer) | bmad-skills/qa-engineer/ | | Agent 2 | Create complete Skill 2 (DevOps Engineer) | bmad-skills/devops-engineer/ | | Agent N | Create complete Skill N (Security Engineer) | bmad-skills/security-engineer/ |

Coordination:

1. Identify suite of related skills to create
2. Define common patterns and shared resources
3. Launch parallel agents, each creating one complete skill
4. Each agent creates SKILL.md, scripts, templates, resources
5. Main context validates all skills and ensures consistency
6. Create integration documentation

Best for: Creating a family of related skills for a domain

Template Creation Workflow

Pattern: Parallel Section Generation Agents: N parallel agents (one per template)

| Agent | Task | Output | |-------|------|--------| | Agent 1 | Create test plan template | templates/test-plan.template.md | | Agent 2 | Create deployment runbook template | templates/deployment-runbook.template.md | | Agent 3 | Create security assessment template | templates/security-assessment.template.md | | Agent N | Create additional domain templates | templates/*.template.md |

Coordination:

1. Identify document types needed for skill
2. Launch parallel agents for each template
3. Each agent defines sections, variables, example content
4. Main context validates template format and placeholder consistency

Best for: Creating multiple templates for a skill quickly

Skill Validation Workflow

Pattern: Fan-Out Research Agents: 4 parallel agents (validation domains)

| Agent | Task | Output | |-------|------|--------| | Agent 1 | Validate YAML frontmatter and skill structure | bmad/outputs/validation-structure.md | | Agent 2 | Validate token count and optimization | bmad/outputs/validation-tokens.md | | Agent 3 | Validate script functionality and permissions | bmad/outputs/validation-scripts.md | | Agent 4 | Validate templates and resources completeness | bmad/outputs/validation-content.md |

Coordination:

1. Load created skill files
2. Launch parallel validation agents for different aspects
3. Each agent runs validation checks and reports issues
4. Main context consolidates validation report
5. Fix identified issues before delivery

Best for: Comprehensive quality check of new skills

Example Subagent Prompt

Task: Create SKILL.md for QA Engineer skill
Context: Read bmad/context/skill-spec.md for requirements
Objective: Create complete SKILL.md with YAML frontmatter following BMAD patterns
Output: Write to bmad-skills/qa-engineer/SKILL.md

Deliverables:
1. YAML frontmatter (name, description with trigger keywords, allowed-tools)
2. Role and function description
3. Core responsibilities (5-8 bullet points)
4. Core principles (5 key principles)
5. When to use this skill section
6. Available commands/workflows (2-4 commands)
7. Workflow process descriptions
8. Integration points with other skills
9. Notes for LLMs section
10. Example interaction

Constraints:
- Follow Anthropic skill specification for YAML
- Keep under 5K tokens (use references for detail)
- Include trigger keywords in description
- Specify allowed-tools list
- Use consistent BMAD formatting and structure
- Include TodoWrite in workflow guidance
- Reference REFERENCE.md for detailed patterns

Notes for LLMs

• Use TodoWrite to track component creation tasks
• Validate YAML frontmatter before finalizing skills
• Follow Anthropic skill specification strictly
• Test generated components before delivery
• Ask user for domain-specific details
• Keep token usage minimal (reference external files)
• Document integration points clearly
• Use scaffold-skill.sh to create directory structure
• Run validate-skill.sh before declaring success

Example Domain Customizations

QA Engineering:

• QA Engineer agent skill
• /create-test-plan workflow
• /execute-tests workflow
• Test plan template

DevOps:

• DevOps Engineer agent skill
• /deploy workflow
• /rollback workflow
• Deployment runbook template

Security:

• Security Engineer agent skill
• /security-audit workflow
• Security assessment template

Data Science:

• Data Scientist agent skill
• /data-analysis workflow
• Analysis report template

Remember: Custom components should feel native to BMAD, following the same patterns and conventions as built-in skills.