builder

What this skill does

# 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](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](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](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:**
```bash
./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:**
```bash
./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:

```yaml
---
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](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