excalidraw

Editable Excalidraw diagrams

Deliver an editable .excalidraw file. Read the relevant source or existing scene before representing it; distinguish observed architecture from proposed changes.

Resolve ../../scripts/convert.js relative to this skill directory. Use its absolute path with Node.js 18 or newer; the converter has no npm dependencies. Do not depend on the shell's working directory or a particular host's plugin-root environment variable.

Create

Write a skeleton JSON file in the task workspace, then run:

node /resolved/plugin/scripts/convert.js skeleton.json diagram.excalidraw

{
  "type": "excalidraw-skeleton",
  "version": 1,
  "layout": "left-right",
  "elements": [
    {"type": "rectangle", "id": "api", "label": "API", "color": "blue"},
    {"type": "rectangle", "id": "db", "label": "Database", "color": "green"},
    {"type": "arrow", "id": "query", "from": "api", "to": "db", "label": "Queries"}
  ]
}

Supported shapes: rectangle, diamond, ellipse, text, arrow, line, frame. Use grid, top-down, or left-right layout and default, blueprint, warm, or monochrome theme. Explicit coordinates are preserved; supply all shape coordinates for precise layout. IDs remain stable in the output. Elbowed arrow routing is not implemented.

Read the format reference for properties, line points, frames, and style options. Keep labels short enough to fit the boxes; text measurement is approximate, so visually inspect diagrams with long labels or complex routing.

Extend or remove

Read the existing file and use its actual element IDs. The converter accepts additions and removals, preserving the scene's embedded files and app state:

node /resolved/plugin/scripts/convert.js --modify existing.excalidraw additions.json updated.excalidraw

Add new elements using new IDs and connect arrows to either new or existing shapes. Put existing IDs in a top-level remove array to delete them. Removing containers also removes bound labels; arrows remain with detached bindings. Removing a frame leaves its contents unframed. Unknown references and duplicate IDs fail before writing. To change existing properties, edit the scene deliberately and preserve reciprocal bindings, or replace the affected elements and their connectors; do not pass a duplicate ID as an addition.