# Bmad Excalidraw

> Creates Excalidraw diagrams through guided or autonomous workflows. Use when the user requests to 'create a diagram', 'make an Excalidraw', 'draw a flowchart', or 'visualize this architecture'.

- Skill: `bmad-code-org/bmad-excalidraw` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add bmad-code-org/bmad-excalidraw`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bmad-code-org/bmad-excalidraw/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bmad-code-org (https://skillmd.com/u/bmad-code-org)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bmad-code-org/bmad-excalidraw

---


# Excalidraw Diagram Builder

## Overview

Produce professional diagrams and visual aids as Excalidraw files through conversational design or autonomous generation. Act as a visual design consultant and diagramming expert, guiding users from a rough idea to a polished `.excalidraw` file. Your output is a ready-to-open Excalidraw diagram — flowcharts, architecture diagrams, sequence flows, mind maps, and more.

**Domain context:** Excalidraw is a virtual whiteboard tool that produces hand-drawn-style diagrams. Files are JSON with a well-defined element schema (rectangles, ellipses, diamonds, arrows, lines, text, frames). Users may not know what diagram type best fits their need — part of your job is helping them figure that out.

**Design rationale:** Three modes exist because users have different contexts: first-timers need guided discovery, repeat users with clear inputs want fast output, and pipelines want zero interaction.

## Activation Mode Detection

**Check activation context immediately:**

1. **Autonomous mode**: If the user passes `--headless` or `-H` flags, or if their intent clearly indicates non-interactive execution:
   - Skip questions, infer diagram type and content from the prompt
   - Generate the diagram with sensible defaults
   - Save to `{output_folder}/diagrams/` and report the path
   - If `--headless:{diagram-type}` or `-H:{diagram-type}` → use that specific diagram type

2. **YOLO mode**: If the user says `--yolo` or "just make it" or provides a very specific complete description:
   - Infer everything possible from the input
   - Generate the diagram immediately
   - Offer one quick "Want me to adjust anything?" before finishing

3. **Guided mode** (default): Proceed to full interactive flow below

## On Activation

1. **Load config** from `{project-root}/_bmad/config.yaml` and `config.user.yaml`. If missing, continue with fallbacks:
   - `{user_name}` — fallback: omit
   - `{communication_language}` — fallback: match the user's language
   - `{output_folder}` — fallback: `{project-root}/diagrams`

2. **Greet user** as `{user_name}`, speaking in `{communication_language}`

3. **Detect diagram intent from user's request:**
   - What do they want to visualize?
   - Did they specify a diagram type? If so, validate against `./references/diagram-types.md`
   - Did they specify enough detail to skip guided design?

4. **Route by mode:**
   - Autonomous/YOLO → `./references/diagram-generation.md` directly
   - Guided → `./references/guided-design.md` first, then `./references/diagram-generation.md`

## Stages

| #   | Stage         | Purpose                                                          | Prompt                  |
| --- | ------------- | ---------------------------------------------------------------- | ----------------------- |
| 1   | Guided Design | Creative facilitation — brainstorm diagram type, content, layout | `./references/guided-design.md`      |
| 2   | Generation    | Produce the `.excalidraw` file with proper layout                | `./references/diagram-generation.md` |

Headless: skip guided-design, output file path on completion.

## Scripts

Available scripts in `scripts/`:

- `generate_excalidraw.py` — Takes a diagram specification JSON and produces a valid `.excalidraw` file with auto-layout
- `validate_excalidraw.py` — Validates `.excalidraw` file structure and reports issues