What happens if REFERENCE.md is not loaded before scaffolding?

The scaffold process requires REFERENCE.md to be read first; without it, workflows and patterns may be misaligned with BMAD guidelines.

Can I customize language guard settings for chat and artifacts?

Yes. Edit the language settings in bmad/project.yaml to influence chat language and document_output_language for artifacts.

Where are the new skill files created?

Under skills/, with mandatory files like SKILL.md and agents/openai.yaml; optional templates/scripts can be added as needed.

bmad-builder

npx machina-cli add skill xmm/codex-bmad-skills/bmad-builder --openclaw

Files (1)

SKILL.md

3.2 KB

BMAD Builder

Trigger Intents

bmad:create-skill
bmad:create-workflow

Workflow Variants

create-skill

Scaffold a new BMAD skill folder with minimal required files.

create-workflow

Define workflow contract, artifacts, and trigger semantics for a domain task.

Inputs

capability goal and scope
intended triggers/intents
expected inputs, outputs, and quality checks

Language Guard (Mandatory)

Enforce language selection separately for chat responses and generated artifacts.

Chat language (communication_language) fallback order:

language.communication_language from bmad/project.yaml
English

Rules for chat responses:

Use the resolved chat language for all assistant responses (questions, status updates, summaries, and handoff notes).
Do not switch chat language unless the user explicitly requests a different language in the current thread.

Artifact language (document_output_language) fallback order:

language.document_output_language from bmad/project.yaml
English

Rules for generated artifacts:

Use the resolved artifact language for all generated BMAD documents and structured artifacts.
write prose and field values in the resolved document language
avoid mixed-language requirement clauses with English modal verbs (for example, System shall followed by non-English text)
allow English acronyms/abbreviations in non-English sentences (for example, API, SLA, KPI, OAuth, WCAG)
Keep code snippets, CLI commands, file paths, and identifiers in their original technical form.

Mandatory Reference Load

Before executing create-skill or create-workflow, read REFERENCE.md first. Treat REFERENCE.md as required context before applying scaffold patterns.

Output Contract

new skill scaffold under skills/
required files: SKILL.md, agents/openai.yaml
optional files: templates/, scripts/, resources/

Core Workflow

Define role, trigger semantics, and artifact contract.
Scaffold minimal structure.
Add deterministic scripts only where repeatability is required.
Validate frontmatter and trigger clarity.
Provide usage prompt and handoff rules.

Script Selection

Create scaffold:

bash scripts/scaffold-skill.sh <skill-name>

Validate resulting skill:

bash scripts/validate-skill.sh <skill-dir>

Template Map

templates/skill.template.md
Why: baseline structure for new skill instructions.
templates/workflow.template.md
Why: workflow contract template.
templates/document.template.md
Why: reusable artifact template.

Reference Map

REFERENCE.md
Must read first for extended builder guidance and quality checks.
resources/skill-patterns.md
Use for naming, trigger, and structure patterns.

Quality Gates

skill metadata is valid and discoverable
triggers and outputs are unambiguous
generated structure is minimal and maintainable
no runtime-specific legacy dependencies are introduced

Source

git clone https://github.com/xmm/codex-bmad-skills/blob/main/skills/bmad-builder/SKILL.mdView on GitHub

Overview

BMAD Builder provides a standardized scaffold for new BMAD skills and workflows. It creates minimal required files (like SKILL.md and agents/openai.yaml), enforces language rules, and requires loading REFERENCE.md before scaffolding to ensure quality and consistency.

How This Skill Works

Triggered by bmad:create-skill or bmad:create-workflow, it generates a minimal folder structure under skills/ with a SKILL.md and required artifacts, applies templates if available, and sets up language guards for chat and artifact output. It then validates frontmatter and trigger clarity to ensure the output contract aligns with the defined workflow.

When to Use It

When starting a new BMAD domain skill that needs a minimal, maintainable scaffold
When defining a new workflow for a domain task with a clear contract and artifacts
When you need deterministic, repeatable scaffold patterns for future skills/workflows
When upgrading BMAD projects to ensure consistent structure and naming
When you want to enforce language guards and mandatory references before scaffolding

Quick Start

Step 1: bash scripts/scaffold-skill.sh <skill-name>
Step 2: Open and customize SKILL.md and any templates imported by the scaffold
Step 3: bash scripts/validate-skill.sh <skill-dir>

Best Practices

Read REFERENCE.md first and follow its guidance before scaffolding
Keep the scaffold minimal and maintainable with clearly defined inputs/outputs
Define language rules early and enforce them in both chat responses and artifacts
Use provided templates to ensure consistent structure across skills/workflows
Validate the scaffold with the provided scripts to catch issues early

Example Use Cases

Scaffold a new customer-support-responder skill with a defined workflow contract and artifact templates
Create a data-validation workflow for a domain task with explicit input/output quality checks
Initialize a governance-friendly skill using REFERENCE.md to guide naming and structure patterns
Generate a skill scaffold and then validate it with bash scripts/validate-skill.sh
Use templates/skill.template.md and templates/workflow.template.md to standardize documents

Frequently Asked Questions

Add this skill to your agents