BMAD Builder
Function: Scaffold and validate custom planning/orchestration skills for the BMAD Planning & Orchestrator plugin. Produces compliant SKILL.md files, shell scripts, and templates — pre-wired to this plugin's path conventions — and runs scope-violation checks to keep new skills inside the PLAN/ORCHESTRATE boundary.
Scope (PLAN, never build)
This skill produces planning artifacts and skill skeleton files. It does NOT write application code, run tests, lint, check coverage, or execute builds. If a skill being designed is tempted to "implement", "fix the code", "run the suite", or "review the diff" — that is a scope violation. Plan and hand off instead.
Three intents
Always clarify which intent applies before starting.
Create — new planning skill from scratch
Gather requirements (use TodoWrite to track):
- Skill name (lowercase-hyphen, prefixed
bmad-; e.g. bmad-example)
- What planning/orchestration problem it solves
- Trigger phrases users will say
- Allowed tools (subset of: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, TodoWrite)
- Which BMAD track(s) it applies to (Quick Flow / BMad Method / Enterprise)
- Upstream BMAD counterpart (e.g.
bmad-risk-assessment)
Run the scaffold script to create the directory:
bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/scripts/scaffold-skill.sh <skill-name>
This creates skills/<skill-name>/ with scripts/ and templates/ subdirectories and a starter SKILL.md.
Fill the SKILL.md using the skill template:
- Reference:
${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/templates/skill.template.md
- Keep body under 5K tokens; push long reference detail to a sibling
REFERENCE.md in the new skill's own folder
- Use
${CLAUDE_PLUGIN_ROOT} for all paths to bundled scripts/templates
- Artifacts go to
bmad-output/ (honor user-configured folder)
- End with the mandatory attribution footer (see template)
Validate the new skill:
bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/scripts/validate-skill.sh \
${CLAUDE_PLUGIN_ROOT}/skills/<skill-name>/SKILL.md
Fix all errors; review all warnings before declaring done.
Validate — check an existing SKILL.md
Run the validator directly against any SKILL.md path:
bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/scripts/validate-skill.sh <path-to-SKILL.md>
The validator checks:
name field present and lowercase-hyphen
description field present with trigger phrases
allowed-tools field present (warns if missing)
- No dev/lint/build/coverage scope violations in
allowed-tools or body
- File size within the
5K token target (20KB)
- Attribution footer present
Scaffold — directory structure only
Use when you want an empty directory skeleton without generating content:
bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/scripts/scaffold-skill.sh <skill-name>
Then fill SKILL.md manually using the template as a guide.
Scope law for new skills
Every skill created by this builder MUST comply with the Scope Law:
- The plugin PLANS and ORCHESTRATES. It NEVER writes application code, runs tests, lints, checks coverage, builds, or reviews implemented code.
- The last artifact any skill may produce is a ready-for-dev story file or a handoff manifest. Implementation is handed to EXTERNAL dev tools/plugins.
- Acceptance Criteria, Testing STRATEGY, and Dev Notes are planning — allowed. Executing tests or writing implementation code is out of scope.
The validate-skill.sh script enforces this automatically by flagging forbidden terms.
BMAD fidelity reminders
When designing skills, track the BMAD Method conventions:
| Convention |
Rule |
| Scale Tracks |
Quick Flow / BMad Method / Enterprise — user confirms interactively |
| Story size |
~2-8h, one dev-day max; split if larger |
| Delivery tracking |
Stories remaining / completion rate — NO Fibonacci points, velocity, or burndown |
| Story name |
{epic}.{story}.{slug}.story.md |
| Story status |
backlog → ready-for-dev → in-progress → review → done |
| Decision log |
Decisions thread through decision-log.md |
| Project constitution |
project-context.md loaded across skills |
| Three intents |
Create / Update / Validate where applicable |
Available scripts
| Script |
Purpose |
scripts/scaffold-skill.sh <name> |
Creates skills/<name>/ with subdirs and starter SKILL.md |
scripts/validate-skill.sh <SKILL.md> |
Validates frontmatter, scope, size, and attribution footer |
Invoke with the ${CLAUDE_PLUGIN_ROOT} prefix shown above. The orchestrator marks scripts executable; you may also run them via bash.
Templates
| Template |
Use for |
templates/skill.template.md |
Skeleton for a new planning/orchestration SKILL.md |
templates/document.template.md |
Generic planning document (PRD section, brief, spec section, etc.) |
Subagent strategy
For creating a full skill package in parallel:
| Agent |
Task |
Output |
| Agent 1 |
Draft SKILL.md body from gathered requirements |
skills/<name>/SKILL.md |
| Agent 2 |
Write domain scripts (validators, checklists) |
skills/<name>/scripts/ |
| Agent 3 |
Write domain templates |
skills/<name>/templates/ |
| Agent 4 |
Write REFERENCE.md if body exceeds 5K tokens |
skills/<name>/REFERENCE.md |
Coordination: gather requirements first (sequential), write spec to bmad-output/skill-spec.md, then fan out. Main context validates all outputs with validate-skill.sh and assembles the final package.
Notes for LLMs
- Use TodoWrite to track which components have been created.
- Never create a skill that contains test runners, linters, coverage tools, build commands, or diff/code-review steps — validate-skill.sh will flag these.
- Always end SKILL.md with the attribution footer block (the template includes it verbatim).
- Keep SKILL.md under 5K tokens; use REFERENCE.md for lengthy patterns.
- Use
${CLAUDE_PLUGIN_ROOT} for all internal paths — never hardcode ~/.claude or absolute machine paths.
- Output artifacts (non-skill files) go under
bmad-output/ by default.
Part of the BMAD Planning & Orchestrator plugin — a Claude Code harness for the BMAD Method by the BMAD Code Organization (https://github.com/bmad-code-org/BMAD-METHOD). Implements the spirit of bmad-bmb-builder. All methodology credit belongs to the BMAD Code Organization.
1---
2name: bmad-builder
3description: |
4 Meta-skill for scaffolding and validating custom PLANNING/ORCHESTRATION skills within the BMAD Planning & Orchestrator plugin. Produces the full skill directory: SKILL.md, scripts, and templates — all pre-targeted at this plugin's path conventions. Includes a scope-violation checker so newly created skills never drift into dev/lint/build/coverage territory. Use when the user says "create a skill", "scaffold a skill", "build a new planning skill", "add a skill to the orchestrator", "extend BMAD planning", "custom orchestration skill", "validate this skill", "check this skill for scope violations", "new skill for the planner", or "bmad-builder". Supports three intents: Create (new skill skeleton), Validate (check an existing SKILL.md), Scaffold (directory structure only). This skill plans and scaffolds only — it NEVER writes application code, runs tests, lints, or builds.
5allowed-tools: Read, Write, Edit, Bash, Glob, Grep, TodoWrite
6metadata:
7 source: https://skillmd.com/skills/aj-geddes/bmad-builder
8---
9
10# BMAD Builder
11
12**Function:** Scaffold and validate custom planning/orchestration skills for the BMAD Planning & Orchestrator plugin. Produces compliant SKILL.md files, shell scripts, and templates — pre-wired to this plugin's path conventions — and runs scope-violation checks to keep new skills inside the PLAN/ORCHESTRATE boundary.
13
14## Scope (PLAN, never build)
15
16This skill produces planning artifacts and skill skeleton files. It does NOT write application code, run tests, lint, check coverage, or execute builds. If a skill being designed is tempted to "implement", "fix the code", "run the suite", or "review the diff" — that is a scope violation. Plan and hand off instead.
17
18## Three intents
19
20Always clarify which intent applies before starting.
21
22### Create — new planning skill from scratch
23
241. Gather requirements (use TodoWrite to track):
25 - Skill name (lowercase-hyphen, prefixed `bmad-`; e.g. `bmad-example`)
26 - What planning/orchestration problem it solves
27 - Trigger phrases users will say
28 - Allowed tools (subset of: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, TodoWrite)
29 - Which BMAD track(s) it applies to (Quick Flow / BMad Method / Enterprise)
30 - Upstream BMAD counterpart (e.g. `bmad-risk-assessment`)
31
322. Run the scaffold script to create the directory:
33 ```bash
34 bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/scripts/scaffold-skill.sh <skill-name>
35 ```
36 This creates `skills/<skill-name>/` with `scripts/` and `templates/` subdirectories and a starter SKILL.md.
37
383. Fill the SKILL.md using the skill template:
39 - Reference: `${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/templates/skill.template.md`
40 - Keep body under 5K tokens; push long reference detail to a sibling `REFERENCE.md` in the new skill's own folder
41 - Use `${CLAUDE_PLUGIN_ROOT}` for all paths to bundled scripts/templates
42 - Artifacts go to `bmad-output/` (honor user-configured folder)
43 - End with the mandatory attribution footer (see template)
44
454. Validate the new skill:
46 ```bash
47 bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/scripts/validate-skill.sh \
48 ${CLAUDE_PLUGIN_ROOT}/skills/<skill-name>/SKILL.md
49 ```
50 Fix all errors; review all warnings before declaring done.
51
52### Validate — check an existing SKILL.md
53
54Run the validator directly against any SKILL.md path:
55```bash
56bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/scripts/validate-skill.sh <path-to-SKILL.md>
57```
58
59The validator checks:
60- `name` field present and lowercase-hyphen
61- `description` field present with trigger phrases
62- `allowed-tools` field present (warns if missing)
63- No dev/lint/build/coverage scope violations in `allowed-tools` or body
64- File size within the ~5K token target (~20KB)
65- Attribution footer present
66
67### Scaffold — directory structure only
68
69Use when you want an empty directory skeleton without generating content:
70```bash
71bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-builder/scripts/scaffold-skill.sh <skill-name>
72```
73Then fill SKILL.md manually using the template as a guide.
74
75## Scope law for new skills
76
77Every skill created by this builder MUST comply with the Scope Law:
78
79- The plugin PLANS and ORCHESTRATES. It NEVER writes application code, runs tests, lints, checks coverage, builds, or reviews implemented code.
80- The last artifact any skill may produce is a ready-for-dev story file or a handoff manifest. Implementation is handed to EXTERNAL dev tools/plugins.
81- Acceptance Criteria, Testing STRATEGY, and Dev Notes are planning — allowed. Executing tests or writing implementation code is out of scope.
82
83The `validate-skill.sh` script enforces this automatically by flagging forbidden terms.
84
85## BMAD fidelity reminders
86
87When designing skills, track the BMAD Method conventions:
88
89| Convention | Rule |
90|------------|------|
91| Scale Tracks | Quick Flow / BMad Method / Enterprise — user confirms interactively |
92| Story size | ~2-8h, one dev-day max; split if larger |
93| Delivery tracking | Stories remaining / completion rate — NO Fibonacci points, velocity, or burndown |
94| Story name | `{epic}.{story}.{slug}.story.md` |
95| Story status | backlog → ready-for-dev → in-progress → review → done |
96| Decision log | Decisions thread through `decision-log.md` |
97| Project constitution | `project-context.md` loaded across skills |
98| Three intents | Create / Update / Validate where applicable |
99
100## Available scripts
101
102| Script | Purpose |
103|--------|---------|
104| `scripts/scaffold-skill.sh <name>` | Creates `skills/<name>/` with subdirs and starter SKILL.md |
105| `scripts/validate-skill.sh <SKILL.md>` | Validates frontmatter, scope, size, and attribution footer |
106
107Invoke with the `${CLAUDE_PLUGIN_ROOT}` prefix shown above. The orchestrator marks scripts executable; you may also run them via `bash`.
108
109## Templates
110
111| Template | Use for |
112|----------|---------|
113| `templates/skill.template.md` | Skeleton for a new planning/orchestration SKILL.md |
114| `templates/document.template.md` | Generic planning document (PRD section, brief, spec section, etc.) |
115
116## Subagent strategy
117
118For creating a full skill package in parallel:
119
120| Agent | Task | Output |
121|-------|------|--------|
122| Agent 1 | Draft SKILL.md body from gathered requirements | `skills/<name>/SKILL.md` |
123| Agent 2 | Write domain scripts (validators, checklists) | `skills/<name>/scripts/` |
124| Agent 3 | Write domain templates | `skills/<name>/templates/` |
125| Agent 4 | Write REFERENCE.md if body exceeds 5K tokens | `skills/<name>/REFERENCE.md` |
126
127Coordination: gather requirements first (sequential), write spec to `bmad-output/skill-spec.md`, then fan out. Main context validates all outputs with `validate-skill.sh` and assembles the final package.
128
129## Notes for LLMs
130
131- Use TodoWrite to track which components have been created.
132- Never create a skill that contains test runners, linters, coverage tools, build commands, or diff/code-review steps — validate-skill.sh will flag these.
133- Always end SKILL.md with the attribution footer block (the template includes it verbatim).
134- Keep SKILL.md under 5K tokens; use REFERENCE.md for lengthy patterns.
135- Use `${CLAUDE_PLUGIN_ROOT}` for all internal paths — never hardcode `~/.claude` or absolute machine paths.
136- Output artifacts (non-skill files) go under `bmad-output/` by default.
137
138> ---
139> Part of the **BMAD Planning & Orchestrator** plugin — a Claude Code harness for the **BMAD Method** by the **BMAD Code Organization** (https://github.com/bmad-code-org/BMAD-METHOD). Implements the spirit of `bmad-bmb-builder`. All methodology credit belongs to the BMAD Code Organization.