excalidraw

Excalidraw

Use this skill when the user wants an editable diagram, not just a rendered image.

Typical requests:

• architecture or system diagrams
• flowcharts and process maps
• sequence diagrams
• concept maps and explainers
• hand-drawn style visuals that should stay editable in Excalidraw

Excalidraw files are plain JSON. The default deliverable is a *.excalidraw file in the workspace. The user can drag that file into excalidraw.com to view, edit, or export it.

Default Workflow

1. Plan the diagram before writing JSON: title, nodes, connectors, groups, and rough canvas size.
2. Write a valid Excalidraw elements array.
3. Wrap the array in the standard file envelope.
4. Save the result as *.excalidraw.
5. If the user wants a shareable browser link, run:

node skills/excalidraw/scripts/upload.mjs diagram.excalidraw

The upload helper encrypts the diagram client-side and prints the Excalidraw share URL.

File Envelope

Use this shape unless you are editing an existing file and need to preserve more fields:

{
  "type": "excalidraw",
  "version": 2,
  "source": "hybridclaw",
  "elements": [],
  "appState": {
    "viewBackgroundColor": "#ffffff"
  },
  "files": {}
}

When editing an existing .excalidraw file, preserve appState, files, and any other existing top-level keys unless the user asked for a deliberate reset.

Rules

• Use Excalidraw JSON, not SVG or HTML, unless the user explicitly asked for another format.
• For labeled shapes or arrows, create a separate text element and bind it with containerId plus the container's boundElements.
• Do not invent a "label" property on rectangles, diamonds, ellipses, or arrows. Excalidraw ignores it.
• Place a bound text element immediately after its container in the elements array.
• Use readable sizes: fontSize 16+ for normal labels, 20+ for titles, and at least 120x60 for labeled boxes.
• Leave about 20-30px of space between major elements.
• Prefer short stable ids such as api, text-api, arrow-api-db.
• Avoid emoji and decorative Unicode. Stick to plain text that Excalidraw renders reliably.
• Default to a white background with dark text unless the user explicitly asks for dark mode.
• For arrows, points are offsets relative to the arrow's x and y.