What is an Excalidraw diagram file format?

An Excalidraw diagram is a JSON object with type 'excalidraw', a version, a source URL, an elements array, appState, and files, conforming to Excalidraw's schema.

How do you ensure isomorphism?

Use the isomorphism test described in Step 4: remove all text and verify that the structure still communicates the concept; iterate until the message is preserved without labels.

Should I use real data names or placeholders?

For technical diagrams, research actual specs (real event names, JSON formats, method names) and avoid placeholders when depth aims to be comprehensive.

excalidraw-diagram

Flagged

{"isSafe":false,"isSuspicious":true,"riskLevel":"high","findings":[{"category":"shell_command","severity":"high","description":"PowerShell command to download and execute a remote script with ByPass execution policy","evidence":"powershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\""},{"category":"shell_command","severity":"high","description":"Curl piping to shell to install a remote script (dangerous pattern: curl ... | sh)","evidence":"curl -LsSf https://astral.sh/uv/install.sh | sh"},{"category":"suspicious_url","severity":"high","description":"External installer URL referenced for UV tool; potential remote code execution source","evidence":"https://astral.sh/uv/install.ps1"},{"category":"suspicious_url","severity":"high","description":"External installer URL referenced for UV tool; potential remote code execution source","evidence":"https://astral.sh/uv/install.sh"}],"summary":"The content contains legitimate documentation for diagram generation but includes explicit remote-script execution patterns (PowerShell with ByPass and curl | sh) that fetch and run code from external URLs. These patterns pose remote code execution risk and should be avoided or replaced with trusted, signed installers and verification steps. Consider recommending safer alternatives (e.g., verified installers, package managers with checksums) and documenting security considerations when enabling remote installations."}

npx machina-cli add skill skizha/agent-skills/excalidraw-diagram --openclaw

Files (1)

SKILL.md

2.9 KB

Excalidraw Diagram Creator

Generate .excalidraw JSON files that argue visually — shapes that mirror their meaning, not just labelled boxes.

Two tests every diagram must pass:

Isomorphism: remove all text — does the structure still communicate the concept?
Education: does it teach concrete details, or just label things?

Step 0 — Assess Depth

Simple/Conceptual: abstract shapes and labels (mental models, overviews)
Comprehensive/Technical: real data formats, actual API/event names, code snippets

For technical diagrams: research the actual specs first (real event names, JSON formats, method names — not generic placeholders).

Step 1 — Map Concepts to Patterns

See references/diagram-patterns.md for the full pattern library (fan-out, convergence, timeline, assembly line, etc.) and evidence artifact types.

Step 2 — Plan Layout

Before writing JSON, sketch mentally:

Entry and exit points
Major sections (assign non-overlapping coordinate regions, e.g. Section A: x 0–800, Section B: x 900–1700)
Where evidence artifacts live
Arrow flow and reading direction (top→bottom or left→right)

Step 3 — Generate JSON

Wrapper:

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [...],
  "appState": { "viewBackgroundColor": "#ffffff", "gridSize": null },
  "files": {}
}

Element reference (templates, sizing, coordinates) → references/element-templates.md
Colors → references/color-palette.md (single source of truth)
Use meaningful IDs (auth-box, api-arrow-1), never elem1
For large diagrams: build section-by-section, not all at once

Key defaults: roughness: 0, opacity: 100, fontFamily: 3 (monospace) on all elements.

Step 4 — Render

cd .claude/skills/excalidraw-diagram/references && uv run python render_excalidraw.py <file.excalidraw>

First-time setup (from the references/ directory):

Option A — with uv (recommended):

# Install uv if needed:
#   Windows:  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
#   macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
uv run playwright install chromium

Option B — with pip (no uv needed):

pip install playwright
playwright install chromium
# Then run directly: python render_excalidraw.py <file.excalidraw>

Step 5 — Validate & Iterate

Fix and re-render (expect 2–4 iterations). Check:

Isomorphism: structure communicates without text
Education: teaches concrete details, not just labels
Text fully visible, no clipping; no unintentional overlaps
Arrows route cleanly; evidence artifacts present in technical diagrams

Source

git clone https://github.com/skizha/agent-skills/blob/master/skills/excalidraw-diagram/SKILL.mdView on GitHub

Overview

This skill generates .excalidraw JSON files designed to argue visually with shapes that mirror meaning. It emphasizes isomorphism and education, ensuring diagrams communicate even without text and teach concrete details through structured layouts built from pattern guidance.

How This Skill Works

First assess depth (conceptual vs. technical) and decide the appropriate diagram complexity. Then map concepts to established diagram patterns from the patterns library and plan entry/exit points, sections, and arrow flow. Finally generate the Excalidraw JSON wrapper with meaningful IDs, color palette, and default element properties, ready for rendering and validation.

When to Use It

Visualize workflows or processes to argue a concept with clear shapes
Document software architecture or data flow across services
Explain complex topics by embedding concrete details (real event names, formats)
Compare design options or system alternatives using established patterns
Illustrate data formats, APIs, or event flows with precise coordinates and labels

Quick Start

Step 1: Assess depth (conceptual vs comprehensive) and decide on technicality level
Step 2: Map concepts to patterns and plan layout using the references library
Step 3: Generate the Excalidraw JSON wrapper, assign meaningful IDs, apply color palette, then render and validate

Best Practices

For technical diagrams, research actual specs first and use real event names
Plan layout with sections and coordinates before generating JSON
Use meaningful IDs (auth-box, api-arrow-1) rather than elem1
Reference color palette and element templates to ensure consistency
Validate isomorphism and education after rendering (2–4 iterations)

Example Use Cases

API request/response flow between client, gateway, and service
Microservices interaction with event streams
Data pipeline showing sources, processors, and sinks
Cloud architecture diagram with components and arrows
User onboarding journey illustrating steps and evidence artifacts

Frequently Asked Questions

Add this skill to your agents