excalidraw

Excalidraw Diagram Skill

Generate diagrams by writing .excalidraw files directly. The output is a JSON file in the Excalidraw format that can be opened in the Excalidraw desktop app, web app (excalidraw.com), VS Code extension, or Obsidian plugin.

IMPORTANT: Do NOT use the Excalidraw MCP tools (mcp__claude_ai_Excalidraw__*), even if they are available. We generate the file ourselves for full control over quality and layout. The MCP tools produce lower quality results and require uploading to excalidraw.com.

When to use Excalidraw:

• User explicitly asks for Excalidraw / whiteboard / sketch / hand-drawn style
• Diagrams for brainstorming, early design, or informal communication
• User wants an editable diagram file they can refine in Excalidraw

When another format is better:

• Formal documentation or whitepapers (SVG)
• Pixel-precise positioning (SVG)
• Inline in GitHub markdown (Mermaid)

Consult the design-system skill for color, composition, and quality rules.

Workflow

1. Plan the Layout

Before generating the file:

• Identify all elements (boxes, arrows, labels) and their relationships
• Plan the spatial layout on a grid (estimate x, y, width, height for each)
• Use generous spacing: 40-60px between peer elements, 20-30px padding inside groups

2. Build the Excalidraw JSON

An .excalidraw file is JSON with this top-level structure:

{
  "type": "excalidraw",
  "version": 2,
  "source": "diagrams-plugin",
  "elements": [ ... ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": null
  },
  "files": {}
}

3. Write the File

Save with .excalidraw extension using the Write tool. The user handles viewing/rendering.

Element Format

Required Fields (all elements)

Every element needs: type, id (unique string), x, y, width, height, version, versionNonce, isDeleted, groupIds, boundElements, seed.

Use this template for default fields:

{
  "version": 1,
  "versionNonce": 1,
  "isDeleted": false,
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "groupIds": [],
  "frameId": null,
  "roundness": null,
  "seed": 1,
  "updated": 1,
  "locked": false,
  "link": null
}