DOCSEARCHbyAlgolia
Submit Docs

BMad Builder

repository·main·Indexed 41 days ago

https://github.com/bmad-code-org/bmad-builder

A toolkit and BMad Core expansion module for creating AI modules, agents, and workflows. It features a two-tier memory system using 'sanctums' for persistent identity and adheres to the Agent Skills open standard for compatibility with AI tools. Version 2.2.2.

Tokens
147.8K
Snippets
204
Records
603
Agent score
52%

What's inside BMad Builder

  1. Overview of BMad Builder

    main

    BMad Builder is a development pipeline for creating, sharing, and discovering AI modules. It allows developers to build agents with persistent memory, guided workflows, or full module ecosystems.

    Key capabilities include:

    • Persistent Memory: Agents that remember information across sessions.
    • Composability: Modules are designed to work within the broader BMad ecosystem.
    • Agent Skills Compliance: Built on the open Agent Skills standard, ensuring compatibility with over 40 AI tools.
    • Distribution: Modules can be shared via the BMad Marketplace or any compliant public marketplace.

  2. Overview of BMad Builder capabilities

    main

    BMad Builder provides three core skills: the Agent Builder (bmad-agent-builder), the Workflow Builder (bmad-workflow-builder), and the Module Builder (bmad-module-builder).

    Capabilities vary by builder:

    • Build Process (BP): Used by the Agent Builder to build, edit, convert, or fix agents, and by the Workflow Builder to build, edit, convert, or fix workflows and utilities.
    • Quality Optimize (QO): Used by both Agent and Workflow builders to validate and optimize existing assets.
    • Convert (CW): Available only in the Workflow Builder to convert any skill to a BMad-compliant, outcome-driven equivalent, providing a comparison report.

    All capabilities support autonomous/headless operation using the --headless or -H flags.

    | Capability | Menu Code | Agent Builder | Workflow Builder |
| :--- | :--- | :--- | :--- |
| **Build Process** | BP | Build, edit, convert, or fix agents | Build, edit, convert, or fix workflows and utilities |
| **Quality Optimize** | QO | Validate and optimize existing agents | Validate and optimize existing workflows and utilities |
| **Convert** | CW | - | Convert any skill to BMad-compliant, outcome-driven equivalent with comparison report |

  3. Use the Module Builder for planning and packaging

    main

    The Module Builder (bmad-module-builder) is a high-level orchestrator used to plan, scaffold, and validate BMad modules. It manages the transition from individual skills (created via Agent or Workflow builders) into cohesive, installable modules. It supports two primary packaging patterns:

    1. Multi-skill modules: Uses a dedicated setup skill to manage multiple capabilities.
    2. Standalone modules: Uses self-registration files embedded within a single skill.

    Core Capabilities

    CapabilityMenu CodeDescription
    Ideate ModuleIMBrainstorm and plan module architecture and dependencies.
    Create ModuleCMPackage skills into an installable module (supports --headless / -H).
    Validate ModuleVMVerify structural integrity and entry quality.

  4. Use BMad Module Builder for ideation, creation, or validation

    main

    The BMad Module Builder provides three distinct workflows depending on your current stage of development:

    1. Ideate Module (IM): Use this for creative brainstorming. It helps you decide on architecture (agent vs. workflow vs. both) and produces a detailed plan document to guide subsequent building steps.
    2. Create Module (CM): Use this to scaffold the infrastructure required to make skills installable.
      • For multi-skill modules, it generates a dedicated -setup skill.
      • For single skills, it embeds self-registration directly into the skill.
    3. Validate Module (VM): Use this to ensure structural integrity. It checks that every skill has registered capabilities, entries are accurate, and the module structure is complete.

    Arguments:

    • IM: Requires an initial description of your idea.
    • CM/VM: Requires a path to a skills folder or a single SKILL.md file.
    • Headless Mode: Both CM and VM support the --headless or -H flag for non-interactive execution.

  5. Understand the core concepts of BMad Builder

    main

    BMad Builder is built around several hierarchical abstractions that allow you to create complex AI systems. Understanding these building blocks is essential for effective development:

    • Skills: The universal, atomic building block for everything produced in BMad.
    • Agents: Higher-level entities that utilize skills. There are three types: stateless, memory, and autonomous.
    • Workflows: Structured, step-by-step processes and utilities used to orchestrate tasks.
    • Modules: The final, distributable unit. Modules combine agents and workflows into installable and configurable packages.
    • Module Configuration: The mechanism by which modules handle user-specific settings and register help via a setup skill.

  6. Access BMad Builder technical references

    main

    The BMad Builder technical reference documentation is organized into three primary areas for configuring and extending the system:

    • Builder Skills: Details regarding Agent Builder and Workflow Builder skills, commands, and capabilities.
    • Workflow & Skill Patterns: Information on structure types, design patterns, and execution models used within the builder.
    • Eval Format: The complete schema definitions for evals.json and triggers.json, including details on overlays and timeouts.

  7. Understand Agent Quality Principles

    main

    Agent quality is maintained through a 'build-plus-scan' approach. Standards are applied at both build time (to ensure the author meets the standard from the start) and analysis time (to verify against the same standard via various lenses).

    Agents are built on top of a universal core defined in references/prompt-quality-canon.md. While the core provides the baseline for prompt quality, agents add specific layers based on their type and purpose.

  8. Implement the Two-Tier Memory System

    main

    The memory system uses two distinct layers to balance raw detail with long-term utility. This prevents context bloat while ensuring continuous learning across sessions.

    1. Session Logs (Raw, Append-only)

    Purpose: Capture raw, unpolished notes immediately after a session. Storage: Append to sessions/YYYY-MM-DD.md. Multiple sessions on the same day use the same file. Lifecycle: These are not loaded on waking. They serve as raw material for curation and should be pruned after 14 days once their value is extracted into MEMORY.md.

    2. MEMORY.md (Curated, Distilled)

    Purpose: Long-term, high-density knowledge. Storage: MEMORY.md. Lifecycle: This file is loaded on every waking. It must be kept tight and relevant. Maintenance: During the Pulse (autonomous wake) phase, review recent session logs, distill insights into MEMORY.md, and then prune the old session logs.

    ## Session — {time or context}

**What happened:** {1-2 sentence summary}

**Key outcomes:**
- {outcome 1}
- {outcome 2}

**Observations:** {skills improving, gaps noticed, techniques that worked}

**Follow-up:** {anything that needs attention next session or during Pulse}

  9. How progressive disclosure works in BMad Skills

    main

    Progressive disclosure is a design pattern used to structure skills so they only load the context necessary for the current task. This minimizes token usage, prevents context pollution, and ensures skills remain functional during long conversations.

    Skills are organized into four layers of increasing complexity and restriction:

    1. Layer 1: Frontmatter vs Body: The name and description in the YAML frontmatter are always in context to help the LLM decide whether to trigger the skill. The actual body of the skill only loads once triggered.
    2. Layer 2: On-Demand Resources: The skill body points to supplementary reference files (e.g., .md files) or scripts (e.g., .py files) that are only loaded when relevant to the user's request.
    3. Layer 3: Dynamic Routing: The skill body acts as a dispatcher, branching the execution path to entirely different prompt flows, scripts, or external skills based on user intent.
    4. Layer 4: Step Files: The most restrictive layer where the agent reads exactly one step file at a time and cannot see ahead. This is used for strict sequential processes where skipping steps is prohibited.

    Best Practice: Start with the lowest level of complexity required. Most production skills use Layers 1-3. Use Layer 4 only for strict compliance or audit workflows.

  10. Extend agent capabilities

    main

    Agents can evolve by learning new capabilities, which are stored in the capabilities/ folder and registered in CAPABILITIES.md. Users describe a desired task, and the agent authors the capability file.

    Capability Types:

    • Prompt: Judgment-based tasks (e.g., brainstorming, analysis).
    • Script: Deterministic tasks (e.g., calculations, file processing).
    • Multi-file: Complex capabilities using templates and references.
    • External skill reference: Pointers to existing installed skills.

  11. How to use the Leanness Scan Lens

    main

    The Leanness lens evaluates whether every line in a skill earns its place by determining if it 'beats its own absence.' It focuses on identifying 'ceremony'—content that is structurally sound but adds no functional value.

    To perform a leanness scan, you must follow these prerequisites:

    1. Load references/prompt-quality-canon.md: This defines the quality bar and the specific tests to apply. Cite these tests in your findings rather than restating them.
    2. Load references/lens-contract.md: This defines the required return mechanics and data format.

    Scope Boundaries:

    • Architecture lens: Handles structure and topology.
    • Determinism lens: Handles intelligence placement.
    • Customization lens: Handles customize.toml.
    • Enhancement lens: Handles missing patterns.
    • Leanness lens: Judges whether present content earns its place.

  12. Evaluate Bootloader (SKILL.md) Weight and Content

    main

    The bootloader (SKILL.md) should be a lean identity seed, ideally around 400 tokens. It is judged by its content rather than strict weight.

    Correct Content (Identity Seed)

    • Identity seed (2-3 sentences of personality DNA).
    • The Three Laws.
    • The Sacred Truth.
    • 'Stay in Character' directive.
    • Persistent Memory directive.
    • The mission.
    • Four-step activation routing.

    Content Leaks (High Severity)

    Flag content that belongs in the sanctum but has leaked into the bootloader:

    • Detailed communication styles.
    • Detailed principles (should be in CREED).
    • Capability menus (should be in CAPABILITIES).
    • Detailed memory guidance (should load on first memory-touch).

    Critical Failures

    • Missing the Three Laws or the Sacred Truth.