Excalidraw Render

Create professional Excalidraw diagrams — flowcharts, architecture diagrams, workflows, systems, processes, or concepts. Use when user asks to "create a diag...

Security Scan

The skill's code, instructions, and requirements are coherent with its stated purpose (rendering Excalidraw diagrams to PNG/PDF); it installs tooling via npm/Playwright and builds a local bundle, which is expected for this functionality.

Purpose & Capability

Name/description (Excalidraw Render) match the files and runtime behaviour: Python render scripts using Playwright + Chromium, an npm-based setup.sh that bundles Excalidraw and installs a CLI, and documentation for creating .excalidraw JSON. Required binaries (python3, node, npm, uv) are reasonable for this skill.

Instruction Scope

SKILL.md confines the agent to diagram-generation tasks and mandates rendering/visual inspection. The runtime instructions reference only local files and the Excalidraw rendering flow. Note: there are two HTML templates in the repo — one uses a CDN (esm.sh) and one uses a local bundle; the primary Python render script requires the local bundle and fails if it's missing, which avoids runtime CDN fetches, but the presence of the CDN template in references is a minor surface to be aware of.

Install Mechanism

There is no registry install spec, but setup.sh builds a local Excalidraw bundle using npm/esbuild and installs @swiftlysingh/excalidraw-cli (attempts global install, falls back to a local install). Playwright/Chromium installation is required for rendering. This is a common approach for bundling front-end libs, but it involves network downloads from npm (and Playwright's browser download) and optionally a global npm install; treat these as normal but potentially impactful system changes.

Credentials

The skill requests no environment variables, no credentials, and no config paths. The lack of secrets or unrelated env access is proportionate to a rendering/diagramming tool.

Persistence & Privilege

always is false and the skill does not request elevated platform privileges. Setup may modify the local skill directory (writes a bundled JS file) and may perform a global npm install if available — this is normal for a build/install script but not a permanent platform-wide privilege requested by the skill manifest.

Assessment

This skill appears coherent and does what it says, but before installing or running setup.sh: 1) Inspect setup.sh (it runs npm installs and may attempt a global npm install) and decide whether you prefer the local install fallback. 2) Expect network downloads (npm packages and Playwright Chromium). 3) Prefer the path that uses the local bundle (the main render script enforces this) to avoid runtime CDN fetches; if you must use the CDN template, understand it will fetch code during rendering. 4) Run setup in a trusted or isolated environment if you are uncomfortable with npm/global installs. 5) No credentials are requested by the skill; if any future changes add env vars with TOKEN/KEY/PASSWORD names, review them carefully before granting access.

Excalidraw Diagram Creator

Generate .excalidraw files — from quick flowcharts to comprehensive technical diagrams.

⚠️ Golden Rule

Every diagram MUST be rendered to PNG and visually inspected before delivery. Look at the actual image — check that text fits inside boxes, no elements overlap, arrows connect correctly, and spacing is balanced. Fix the JSON and re-render until it looks professional. See the Render & Validate section. No exceptions.

---

Depth Gate (Do This First)

Need	Approach	Time
Simple flowchart, decision tree, linear process	Quick Path — CLI DSL	~1 min
Architecture, multi-zoom technical, evidence artifacts	Full Path — hand-crafted JSON	~10 min

---

Quick Path: CLI DSL Flowcharts

For straightforward flows, use @swiftlysingh/excalidraw-cli (installed locally by setup.sh):

excalidraw-cli create --inline "DSL" -o output.excalidraw

Note: If excalidraw-cli is not in your PATH after setup, use: "$SKILL_DIR/.npm/node_modules/.bin/excalidraw-cli" or re-run setup.sh.

DSL Syntax

Syntax	Shape	Use For
[Label]	Rectangle	Process steps
{Label?}	Diamond	Decisions
(Label)	Ellipse	Start/End
[[Label]]	Database	Data storage
->	Arrow	Connection
-> "text" ->	Labeled arrow	Conditional
-->	Dashed arrow	Optional path

Directives: @direction LR|TB|RL|BT, @spacing 60

DSL Example

excalidraw-cli create --inline "$(cat <<'EOF'
@direction TB
(Start) -> [Receive Request] -> {Authenticated?}
{Authenticated?} -> "yes" -> [Process Request] -> (Success)
{Authenticated?} -> "no" -> [Return 401] -> (End)
EOF
)" -o auth-flow.excalidraw

CLI options: -d LR (direction), -s 80 (spacing), --format dot (DOT/Graphviz input).

After generation, always render and validate (see Render section below). Fix overlaps or clipping in the JSON if needed.

---

Full Path: Hand-Crafted JSON Diagrams

For comprehensive, professional diagrams. Read these references as needed:

• references/color-palette.md — All colors (read FIRST, every time)
• references/element-templates.md — Copy-paste JSON for each element type
• references/json-schema.md — Full property reference
• references/layout-rules.md — Anti-overlap spacing and text-sizing rules ⚠️ READ THIS

Design Process

1. Assess depth — simple/conceptual vs. comprehensive/technical
2. Research (technical diagrams) — look up real specs, event names, API formats
3. Map concepts to visual patterns — see Pattern Library below
4. Sketch mentally — trace how the eye moves through the diagram
5. Generate JSON section-by-section — see Large Diagram Strategy
6. Render & validate — MANDATORY loop (see below)

JSON Structure

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

Core Rules

• fontFamily: 3, roughness: 0, opacity: 100 on all elements
• text property = ONLY readable words (no markup)
• Size containers to fit text — see references/layout-rules.md
• Minimum 40px gap between elements — see references/layout-rules.md
• Default to free-floating text; use containers only when meaningful (<30% text in boxes)

Visual Pattern Library

Concept Behavior	Pattern
One source → many outputs	Fan-out (radial arrows from center)
Many inputs → one output	Convergence (arrows merging)
Hierarchy/nesting	Tree (lines + free-floating text)
Sequence of steps	Timeline (line + dots + labels)
Feedback loop	Spiral/Cycle (arrow returning to start)
Abstract state	Cloud (overlapping ellipses)
Transformation	Assembly line (before → process → after)
Comparison	Side-by-side (parallel structures)
Phase changes	Gap/Break (visual whitespace)

Shape Meaning

Concept	Shape
Labels, descriptions	Free-floating text (no container)
Timeline markers	Small ellipse (12px)
Start/trigger	Ellipse
End/output	Ellipse
Decision	Diamond
Process/action	Rectangle

Evidence Artifacts (Technical Diagrams)

Artifact	Rendering
Code snippets	Dark rect (#1e293b) + syntax-colored text
JSON/data	Dark rect (#1e293b) + green text (#22c55e)
Event sequences	Timeline (line + dots + labels)
UI mockups	Nested rectangles

Large Diagram Strategy

Build JSON one section at a time (Claude has ~32k token output limit):

1. Create base file + first section
2. Add one section per edit — use descriptive IDs ("trigger_rect", "auth_arrow")
3. Namespace seeds by section (100xxx, 200xxx, etc.)
4. Update cross-section bindings as you go
5. Review the whole before rendering

Multi-Zoom (Comprehensive Diagrams)

• Level 1 — Summary flow (simplified overview)
• Level 2 — Section boundaries (labeled regions)
• Level 3 — Detail (evidence artifacts, code snippets, real data)

---

Render & Validate (MANDATORY)

Every diagram must be rendered and visually inspected before delivery. This catches overlap, text clipping, and spacing issues that are invisible in JSON.

Render Command

cd ~/.openclaw/skills/excalidraw-diagram && uv run python render_excalidraw.py <path-to-file.excalidraw>

Outputs a PNG next to the .excalidraw file. Use the Read tool to view it.

First-Time Setup

cd ~/.openclaw/skills/excalidraw-diagram
bash setup.sh                              # builds local Excalidraw bundle (requires node/npm)
uv sync && uv run playwright install chromium

The Loop (repeat until professional)

1. Render the PNG
2. View the image with the Read tool — actually look at it
3. Inspect systematically:
   • Does every label fit cleanly inside its box? (no clipping, no overflow)
   • Are all boxes/shapes clearly separated? (no overlapping edges)
   • Are arrows connecting the right elements without crossing through others?
   • Is spacing even and consistent between similar elements?
   • Is text large enough to read?
   • Does the overall layout look balanced and professional?
4. Fix the JSON for every issue found — widen containers, adjust x/y, add arrow waypoints, increase gaps
5. Re-render and re-view — look at the new PNG
6. Repeat until every issue is resolved (typically 2-4 iterations, sometimes more)

Do not skip this loop. JSON coordinates are approximate — you will almost always find issues on the first render. The visual check IS the quality gate.

Stop When

• No text overflow or overlapping
• Arrows route cleanly
• Consistent spacing, balanced composition
• You'd show it without caveats

---

PNG & PDF Export

PNG (for Word, presentations, sharing)

The render script outputs high-res PNG (2x scale by default):

cd ~/.openclaw/skills/excalidraw-diagram && uv run python render_excalidraw.py diagram.excalidraw --output diagram.png --scale 3

Options: --scale 3 (3x for print), --width 2560 (wider viewport).

PDF (for documents, printing)

Convert PNG to PDF:

# ImageMagick (most common)
convert diagram.png -density 150 diagram.pdf

# Or with a white background and margins
convert diagram.png -gravity center -background white -extent 110%x110% -density 150 diagram.pdf

For multi-page or A4/Letter sizing:

convert diagram.png -resize 1800x -gravity center -background white \
  -extent 2100x2970 -units PixelsPerInch -density 254 diagram-a4.pdf

---

Quality Checklist

Layout & Overlap

• All text fits within containers (used layout-rules.md sizing formula)
• Minimum 40px gap between all elements
• Arrows don't cross through elements
• Even spacing between similar elements
• Balanced composition (no voids or overcrowding)

Visual

• roughness: 0, opacity: 100, fontFamily: 3 everywhere
• Colors from references/color-palette.md
• Text readable at export size
• Clear visual flow (eye path)

Technical (if applicable)

• Real specs/event names/API formats (not placeholders)
• Evidence artifacts included
• Multi-zoom levels present

Export

• Rendered to PNG and visually validated
• PNG/PDF delivered if user needs it