excalidraw-mermaid-safe
Generate Excalidraw-compatible Mermaid flowcharts with parser-safe labels, readable grouped layouts, and conservative color classes. Use when users ask for a Mermaid diagram that imports cleanly in Ex
SKILL.mdskills/excalidraw-mermaid-safe/SKILL.md
GitHubExcalidraw Mermaid Safe
Overview
Create or sanitize Mermaid flowcharts so they reliably parse in Excalidraw. This skill prioritizes parser safety, readability, deterministic validation, and conservative color styling over full Mermaid feature coverage.
Trigger examples:
- "make this mermaid import in excalidraw"
- "colored mermaid compatible with excalidraw"
- "sanitize this broken mermaid for excalidraw"
- "excalidraw diagram from markdown"
Compatibility Contract
- Default output diagram type is
flowchart. - Default direction is
flowchart LRfor readability. - Labels are quoted and sanitized.
- Markdown links and raw URLs are removed from node labels.
- Long labels are truncated before they become hard to scan.
- Styling uses conservative
classDef/classdeclarations. - Unsupported Mermaid diagram families are rejected instead of partially converted.
Decision Protocol
- Use
from-markdownwhen the input is notes, an outline, a status report, or a design summary. - Use
sanitize-mermaidwhen the input is already Mermaid or contains a Mermaid code block. - Use
autowhen the input type is unclear and the file extension or first non-empty line should decide. - Use
groupedlayout for documents with sections; useflatonly for short linear flows. - Keep
--max-nodesat40unless the user explicitly wants a denser map. Prefer summarizing over creating oversized diagrams. - Ask one clarifying question only when the intended diagram type changes the output materially, such as process flow vs. decision map.
Completion Criteria
Before returning a diagram, ensure:
- The output starts with
flowchart. - Static validation passes.
- Raw URLs and Markdown links are not present in node labels.
- The diagram stays under the chosen node cap.
- If the user needs high confidence for Excalidraw import,
excalidraw-strictvalidation passes or you clearly report why it could not run.
Workflow
1) Generate from markdown
python3 scripts/excali_mermaid_safe.py \
--input notes.md \
--output diagram.mmd \
--mode from-markdown \
--palette safe \
--layout grouped \
--max-nodes 40 \
--validate static
2) Sanitize existing mermaid
python3 scripts/excali_mermaid_safe.py \
--input broken.mmd \
--output fixed.mmd \
--mode sanitize-mermaid \
--palette safe \
--layout grouped \
--validate static
3) Auto detect mode
scripts/excali_mermaid_safe.sh \
--input input.md \
--output output.mmd \
--mode auto \
--palette safe \
--layout grouped
4) Install parser dependency (one-time)
scripts/bootstrap.sh
5) Enforce strict parser check
scripts/excali_mermaid_safe.sh \
--input notes.md \
--output diagram.mmd \
--mode from-markdown \
--validate excalidraw-strict
CLI
Primary command:
scripts/excali_mermaid_safe.sh \
--input <input.md|input.mmd> \
--output <output.mmd> \
--mode auto \
--palette safe \
--layout grouped
Arguments:
--input: source markdown or mermaid--output: output.mmd--mode:auto|from-markdown|sanitize-mermaid--palette:safe|mono--layout:grouped|flat--max-nodes: integer, default40--validate:none|static|excalidraw|excalidraw-strict, defaultstatic
Helper commands:
scripts/test_fixtures.sh # run deterministic fixture regression tests
scripts/test_fixtures.sh --strict
scripts/doctor.sh # check runtime plus static and optional strict validation
scripts/bootstrap.sh # install optional Node parser dependency
Validation
staticchecks:- first non-empty line starts with
flowchart - no
[[...](...)]labels - no unsupported diagram declarations
- node count does not exceed
--max-nodes
- first non-empty line starts with
excalidrawvalidation:- attempts Node parse using
@excalidraw/mermaid-to-excalidraw - if unavailable, warns and falls back to static success behavior
- attempts Node parse using
excalidraw-strictvalidation:- attempts Node parse using
@excalidraw/mermaid-to-excalidraw - fails if Node is missing, parser package is missing, or parse fails
- depends on upstream Mermaid/Excalidraw packages; treat it as local validation for trusted diagrams unless dependency audit has been reviewed
- attempts Node parse using
scripts/test_fixtures.sh:- regenerates fixture outputs in a temporary directory
- diffs against
assets/fixtures/expected/*.mmd - exits non-zero on behavioral drift
Resources
- Parser compatibility notes:
references/excalidraw-mermaid-compat.md - Style templates:
assets/templates/*.mmd - Regression fixtures:
assets/fixtures/input/*.mdandassets/fixtures/expected/*.mmd
Limitations
- Flowchart-first by design.
- Does not emit Excalidraw JSON scenes.
- Complex Mermaid features may be simplified for parser safety.
- Semantic grouping is heuristic and based on headings, bullets, tables, and common workflow keywords.