Agent skill

excalidraw-ai

Create professional Excalidraw diagrams by generating JSON directly. This skill provides the Excalidraw JSON schema reference and professional icon libraries for AI agents to autonomously create diagrams without templates.

View SKILL.md on GitHub Repository
Stars 3
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/jiatastic/open-python-skills/tree/main/skills/excalidraw-ai

SKILL.md

excalidraw-ai

Generate Excalidraw diagrams by writing JSON directly. No templates needed - you have full control over every element.

When to Use This Skill

Use this skill when you need to:

  • Create architecture diagrams, flowcharts, or mind maps
  • Visualize system designs, data flows, or processes
  • Generate diagrams from code analysis or documentation
  • Create custom diagrams with precise control over layout and styling

Excalidraw JSON Schema

An Excalidraw file is a JSON object with this structure:

json
{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [ /* array of element objects */ ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": null
  },
  "files": {}
}

Element Types

Rectangle

json
{
  "id": "unique-id-1",
  "type": "rectangle",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 100,
  "strokeColor": "#1971c2",
  "backgroundColor": "#a5d8ff",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "groupIds": [],
  "angle": 0,
  "seed": 12345,
  "isDeleted": false
}

Ellipse

json
{
  "id": "unique-id-2",
  "type": "ellipse",
  "x": 100,
  "y": 100,
  "width": 150,
  "height": 100,
  "strokeColor": "#7c3aed",
  "backgroundColor": "#ede9fe",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "roughness": 1
}

Diamond

json
{
  "id": "unique-id-3",
  "type": "diamond",
  "x": 100,
  "y": 100,
  "width": 120,
  "height": 120,
  "strokeColor": "#dc2626",
  "backgroundColor": "#fee2e2",
  "fillStyle": "solid"
}

Text

json
{
  "id": "unique-id-4",
  "type": "text",
  "x": 110,
  "y": 140,
  "width": 180,
  "height": 25,
  "text": "Your Label Here",
  "fontSize": 20,
  "fontFamily": 1,
  "textAlign": "center",
  "verticalAlign": "middle",
  "strokeColor": "#1e1e1e",
  "backgroundColor": "transparent"
}

Arrow

json
{
  "id": "unique-id-5",
  "type": "arrow",
  "x": 300,
  "y": 150,
  "width": 100,
  "height": 50,
  "strokeColor": "#1971c2",
  "strokeWidth": 2,
  "points": [[0, 0], [100, 50]],
  "startBinding": {
    "elementId": "source-element-id",
    "focus": 0.5,
    "gap": 5
  },
  "endBinding": {
    "elementId": "target-element-id",
    "focus": 0.5,
    "gap": 5
  },
  "startArrowhead": null,
  "endArrowhead": "arrow"
}

Line

json
{
  "id": "unique-id-6",
  "type": "line",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 0,
  "strokeColor": "#868e96",
  "strokeWidth": 1,
  "points": [[0, 0], [200, 0]],
  "startArrowhead": null,
  "endArrowhead": null
}

Element Properties Reference

Property Type Description
id string Unique identifier (use UUID or similar)
type string rectangle, ellipse, diamond, text, arrow, line
x, y number Position coordinates
width, height number Dimensions
strokeColor string Border/stroke color (hex)
backgroundColor string Fill color (hex) or "transparent"
fillStyle string "solid", "hachure", "cross-hatch"
strokeWidth number Line thickness (1, 2, 4)
strokeStyle string "solid", "dashed", "dotted"
roughness number 0 = sharp, 1 = normal, 2 = sketchy
opacity number 0-100
angle number Rotation in radians
groupIds array Group element IDs together
seed number Random seed for hand-drawn effect

Text Properties

Property Type Description
text string The text content
fontSize number Font size in pixels
fontFamily number 1 = Virgil (hand-drawn), 2 = Helvetica, 3 = Cascadia
textAlign string "left", "center", "right"
verticalAlign string "top", "middle"

Arrow Properties

Property Type Description
points array Array of [x, y] coordinates relative to element origin
startBinding object Connection to source element
endBinding object Connection to target element
startArrowhead string null, "arrow", "bar", "dot", "triangle"
endArrowhead string null, "arrow", "bar", "dot", "triangle"

Color Palette Reference

Component-Based Colors (Recommended for Architecture Diagrams)

Component Type Stroke Background Use For
Database #7c3aed #ede9fe PostgreSQL, MySQL, MongoDB
Cache #dc2626 #fee2e2 Redis, Memcached
Queue #16a34a #dcfce7 Kafka, RabbitMQ, SQS
Load Balancer #0891b2 #cffafe Nginx, HAProxy, ALB
Gateway #475569 #f1f5f9 API Gateway, Kong
CDN #06b6d4 #e0f2fe CloudFront, Fastly
Auth #e11d48 #ffe4e6 OAuth, IAM, Cognito
Storage #d97706 #fef3c7 S3, Blob Storage
Service #2563eb #dbeafe Backend services, APIs
Container #0284c7 #bae6fd Docker, Kubernetes
Function #f59e0b #fef3c7 Lambda, Serverless
Monitoring #84cc16 #ecfccb Prometheus, Grafana
Web App #4f46e5 #e0e7ff React, Vue, Frontend
Mobile #6366f1 #eef2ff iOS, Android

Theme Colors

Modern (Default)

  • Primary: #1971c2 / #e7f5ff
  • Neutral: #64748b / #f1f5f9

Sketchy (Hand-drawn)

  • Primary: #495057 / #f8f9fa
  • Use roughness: 2 and fontFamily: 3

Technical

  • Primary: #2f9e44 / #ebfbee
  • Use strokeStyle: "dashed" for connections

Icon Libraries (305 Components Total)

Professional icons are available in .excalidrawlib files in the assets/ directory:

Library Components Content
aws-architecture-icons.excalidrawlib 248 AWS service icons (Lambda, S3, EC2, RDS, DynamoDB, SQS, etc.)
system-design.excalidrawlib 24 System design elements (server, database, storage, etc.)
drwnio.excalidrawlib 18 Draw.io style icons
system-design-template.excalidrawlib 8 Pre-built templates (steps, flow, db, etc.)
software-architecture.excalidrawlib 7 Software architecture components

Using Library Components

Library files contain element arrays that can be embedded directly into your diagram. Each library item is an array of Excalidraw elements that form a component.

To use: Parse the library JSON, find the component you need, adjust positions, and include in your diagram's elements array.

Layout Guidelines

Architecture Diagram Layout

Organize components in layers (top to bottom):

Layer 1: Client/External (y: 100)
Layer 2: Edge/CDN (y: 280)
Layer 3: Gateway/Load Balancer (y: 460)
Layer 4: Services (y: 640)
Layer 5: Data/Cache (y: 820)
Layer 6: Infrastructure (y: 1000)

Spacing recommendations:

  • Horizontal spacing between components: 240px
  • Vertical spacing between layers: 180px
  • Component width: 180-220px
  • Component height: 80-100px

Flowchart Layout

Arrange left-to-right or top-to-bottom:

  • Step spacing: 200px
  • Use rectangles for processes
  • Use diamonds for decisions
  • Use ellipses for start/end

Mind Map Layout

Radial layout from center:

  • Center node at (400, 300)
  • Child nodes at radius 250px
  • Distribute evenly using angle calculations

Complete Example

json
{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    {
      "id": "api-gateway",
      "type": "rectangle",
      "x": 100,
      "y": 100,
      "width": 180,
      "height": 80,
      "strokeColor": "#475569",
      "backgroundColor": "#f1f5f9",
      "fillStyle": "solid",
      "strokeWidth": 2,
      "roughness": 0,
      "opacity": 100,
      "groupIds": ["group-1"],
      "seed": 1234
    },
    {
      "id": "api-gateway-label",
      "type": "text",
      "x": 140,
      "y": 130,
      "width": 100,
      "height": 25,
      "text": "API Gateway",
      "fontSize": 16,
      "fontFamily": 1,
      "textAlign": "center",
      "strokeColor": "#1e1e1e",
      "groupIds": ["group-1"]
    },
    {
      "id": "redis",
      "type": "diamond",
      "x": 100,
      "y": 280,
      "width": 180,
      "height": 100,
      "strokeColor": "#dc2626",
      "backgroundColor": "#fee2e2",
      "fillStyle": "solid",
      "strokeWidth": 2,
      "roughness": 0,
      "seed": 5678
    },
    {
      "id": "redis-label",
      "type": "text",
      "x": 155,
      "y": 320,
      "width": 70,
      "height": 20,
      "text": "Redis",
      "fontSize": 16,
      "fontFamily": 1,
      "textAlign": "center",
      "strokeColor": "#1e1e1e"
    },
    {
      "id": "arrow-1",
      "type": "arrow",
      "x": 190,
      "y": 180,
      "width": 0,
      "height": 100,
      "strokeColor": "#64748b",
      "strokeWidth": 2,
      "points": [[0, 0], [0, 100]],
      "startBinding": {"elementId": "api-gateway", "focus": 0.5, "gap": 5},
      "endBinding": {"elementId": "redis", "focus": 0.5, "gap": 5},
      "endArrowhead": "arrow"
    }
  ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": null
  },
  "files": {}
}

Output

Save your diagram as a .excalidraw or .json file. It can be:

  • Imported directly into excalidraw.com
  • Embedded in documentation or web apps
  • Converted to PNG/SVG using Excalidraw's export features

Tips for AI Agents

  1. Generate unique IDs: Use UUIDs or sequential IDs for each element
  2. Group related elements: Use groupIds to keep shapes and their labels together
  3. Use bindings for arrows: Connect arrows to elements using startBinding and endBinding
  4. Apply consistent styling: Use the color palette for component types
  5. Calculate text positions: Center text within shapes by adjusting x/y based on text length
  6. Set seed values: Use seed: hash(id) for consistent hand-drawn rendering

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

jiatastic/open-python-skills

logfire

Structured observability with Pydantic Logfire and OpenTelemetry. Use when: (1) Adding traces/logs to Python APIs, (2) Instrumenting FastAPI, HTTPX, SQLAlchemy, or LLMs, (3) Setting up service metadata, (4) Configuring sampling or scrubbing sensitive data, (5) Testing observability code.

3 0
Explore
jiatastic/open-python-skills

linting

Python linting with Ruff - an extremely fast linter written in Rust. Use when: (1) Standardizing code quality, (2) Fixing style warnings, (3) Enforcing rules in CI, (4) Replacing flake8/isort/pyupgrade/autoflake, (5) Configuring lint rules and suppressions.

3 0
Explore
jiatastic/open-python-skills

ty-skills

Python type checking expertise using ty - the extremely fast type checker by Astral. Use when: (1) Adding type annotations to Python code, (2) Fixing type errors reported by ty, (3) Migrating from mypy/pyright to ty, (4) Configuring ty for projects, (5) Understanding advanced type patterns (generics, protocols, intersection types), (6) Setting up ty in editors (VS Code, Cursor, Neovim, PyCharm).

3 0
Explore
jiatastic/open-python-skills

pydantic

Pydantic models and validation. Use when: (1) Defining schemas, (2) Validating input/output, (3) Generating JSON schema.

3 0
Explore
jiatastic/open-python-skills

commit-message

Analyze git changes and generate conventional commit messages. Supports batch commits for multiple unrelated changes. Use when: (1) Creating git commits, (2) Reviewing staged changes, (3) Splitting large changesets into logical commits.

3 0
Explore
jiatastic/open-python-skills

python-backend

Python backend development expertise for FastAPI, security patterns, database operations, Upstash integrations, and code quality. Use when: (1) Building REST APIs with FastAPI, (2) Implementing JWT/OAuth2 authentication, (3) Setting up SQLAlchemy/async databases, (4) Integrating Redis/Upstash caching, (5) Refactoring AI-generated Python code (deslopification), (6) Designing API patterns, or (7) Optimizing backend performance.

3 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results