excalidraw

Excalidraw

Overview

Create diagrams as real .excalidraw JSON, not screenshots, so the user can keep editing them in Excalidraw. Prefer simple editable shapes, text, arrows, frames, and grouped sections over pixel-perfect artwork.

Important boundary: this skill can create editable files and preview pages, but a skill alone cannot create a native inline Excalidraw widget with live editing, checkpoint restoration, or host-provided buttons inside the chat UI. That experience requires an MCP/app/widget integration that exposes operations like read_me, create_view, checkpoint storage, and widget rendering.

Core Workflow

1. Clarify the diagram intent only when the request lacks the actors, nodes, or flow.
2. Decide whether this is a new diagram or an edit to the previous diagram:
   • If the user asks to adjust, change, add, remove, make bigger/smaller, recolor, relabel, simplify, improve, or otherwise revise "this", "that", "the diagram", or "the last one", use the incremental edit workflow below.
   • If the user asks for a new subject, create a new diagram.
3. Default to web-link handoff for new diagrams:
   • Use scripts/create_web_diagram.py and pass the spec through stdin.
   • Let the script create its own temporary folder under /private/tmp.
   • Request network permission during generation so Codex can upload the encrypted scene and return a ready https://excalidraw.com/#json=... link.
   • Return the preview image, the local preview page path, and the ready Excalidraw Web URL.
   • The local preview page must include an Open in Excalidraw button that points directly to the ready web URL.
   • Use --no-web-link only when the user explicitly asks for local-only/offline output or refuses network access.
   • Persist a copy of the latest diagram in the default state directory, or in CODEX_EXCALIDRAW_STATE_DIR when configured, with scripts/session_state.py save so later edits can reuse it.
4. Choose the fastest path:
   • For simple node-and-edge diagrams, use scripts/generate_excalidraw.py.
   • For soccer/football roster or tactical squad diagrams, use scripts/create_tactical_roster.py; do not hand-write the scene unless the template cannot represent the request.
   • For landmark/building elevation diagrams, use scripts/create_building_elevation.py; do not hand-write a building scene unless the template cannot represent the request.
   • For Mermaid or standard diagram syntax, consult references/official-excalidraw.md and prefer the official @excalidraw/mermaid-to-excalidraw path when available.
   • For spatial, editorial, tactical, dashboard-like, swimlane, field/court/map, roster, org chart, comparison, or visually composed diagrams, edit/create the JSON directly using references/format.md; do not force these into generic boxes and arrows.
5. Save output with the .excalidraw extension when a file is needed.
6. Generate a preview when the user expects to see the diagram in chat or browser:
   • Prefer --preview with scripts/generate_excalidraw.py for generated diagrams.
   • For direct JSON edits, create a separate SVG preview, generate a ready web URL when permitted, and use scripts/preview_page.py to create the HTML preview with the Open in Excalidraw button.
7. Validate the result with scripts/validate_scene.py when an .excalidraw file exists. It checks top-level shape, duplicate IDs, invisibly small elements, and text likely to be unreadable.
8. Run the visual quality gate in references/quality-gate.md before delivery. Fix readability or layout problems before showing the user.
9. Save latest-state metadata with scripts/session_state.py save unless the user explicitly asks for a throwaway diagram.
10. Tell the user what is available: preview image first, then the ready Excalidraw Web link and local preview page with the Open in Excalidraw button.