Excalidraw Diagram Generator

Excalidraw Diagram Generator

A skill for generating Excalidraw-format diagrams from natural language descriptions. This skill helps create visual representations of processes, systems, relationships, and ideas without manual drawing.

• Leverage native parallel subagent dispatch and 200k+ context windows where available.

Activation Conditions

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

Use this skill when users request:

• "Create a diagram showing..."
• "Make a flowchart for..."
• "Visualize the process of..."
• "Draw the system architecture of..."
• "Generate a mind map about..."
• "Create an Excalidraw file for..."
• "Show the relationship between..."
• "Diagram the workflow of..."

Supported diagram types:

• 📊 Flowcharts: Sequential processes, workflows, decision trees
• 🔗 Relationship Diagrams: Entity relationships, system components, dependencies
• 🧠 Mind Maps: Concept hierarchies, brainstorming results, topic organization
• 🏗️ Architecture Diagrams: System design, module interactions, data flow
• 📈 Data Flow Diagrams (DFD): Data flow visualization, data transformation processes
• 🏊 Business Flow (Swimlane): Cross-functional workflows, actor-based process flows
• 📦 Class Diagrams: Object-oriented design, class structures and relationships
• 🔄 Sequence Diagrams: Object interactions over time, message flows
• 🗃️ ER Diagrams: Database entity relationships, data models

Prerequisites

• Clear description of what should be visualized
• Identification of key entities, steps, or concepts
• Understanding of relationships or flow between elements

Step-by-Step Workflow

Step 1: Understand the Request

Analyze the user's description to determine:

1. Diagram type (flowchart, relationship, mind map, architecture)
2. Key elements (entities, steps, concepts)
3. Relationships (flow, connections, hierarchy)
4. Complexity (number of elements)

Step 2: Choose the Appropriate Diagram Type

| User Intent | Diagram Type | Example Keywords | |-------------|--------------|------------------| | Process flow, steps, procedures | Flowchart | "workflow", "process", "steps", "procedure" | | Connections, dependencies, associations | Relationship Diagram | "relationship", "connections", "dependencies", "structure" | | Concept hierarchy, brainstorming | Mind Map | "mind map", "concepts", "ideas", "breakdown" | | System design, components | Architecture Diagram | "architecture", "system", "components", "modules" | | Data flow, transformation processes | Data Flow Diagram (DFD) | "data flow", "data processing", "data transformation" | | Cross-functional processes, actor responsibilities | Business Flow (Swimlane) | "business process", "swimlane", "actors", "responsibilities" | | Object-oriented design, class structures | Class Diagram | "class", "inheritance", "OOP", "object model" | | Interaction sequences, message flows | Sequence Diagram | "sequence", "interaction", "messages", "timeline" | | Database design, entity relationships | ER Diagram | "database", "entity", "relationship", "data model" |

Step 3: Extract Structured Information

For Flowcharts:

• List of sequential steps
• Decision points (if any)
• Start and end points

For Relationship Diagrams:

• Entities/nodes (name + optional description)
• Relationships between entities (from → to, with label)

For Mind Maps:

• Central topic
• Main branches (3-6 recommended)
• Sub-topics for each branch (optional)

For Data Flow Diagrams (DFD):

• Data sources and destinations (external entities)
• Processes (data transformations)
• Data stores (databases, files)
• Data flows (arrows showing data movement from left-to-right or from top-left to bottom-right)
• Important: Do not represent process order, only data flow

For Business Flow (Swimlane):

• Actors/roles (departments, systems, people) - displayed as header columns
• Process lanes (vertical lanes under each actor)
• Process boxes (activities within each lane)
• Flow arrows (connecting process boxes, including cross-lane handoffs)

For Class Diagrams:

• Classes with names
• Attributes with visibility (+, -, #)
• Methods with visibility and parameters
• Relationships: inheritance (solid line + white triangle), implementation (dashed line + white triangle), association (solid line), dependency (dashed line), aggregation (solid line + white diamond), composition (solid line + filled diamond)
• Multiplicity notations (1, 0..1, 1.., )

For Sequence Diagrams:

• Objects/actors (arranged horizontally at top)
• Lifelines (vertical lines from each object)
• Messages (horizontal arrows between lifelines)
• Synchronous messages (solid arrow), asynchronous messages (dashed arrow)
• Return values (dashed arrows)
• Activation boxes (rectangles on lifelines during execution)
• Time flows from top to bottom

For ER Diagrams:

• Entities (rectangles with entity names)
• Attributes (listed inside entities)
• Primary keys (underlined or marked with PK)
• Foreign keys (marked with FK)
• Relationships (lines connecting entities)
• Cardinality: 1:1 (one-to-one), 1:N (one-to-many), N:M (many-to-many)
• Junction/associative entities for many-to-many relationships (dashed rectangles)

Step 4: Generate the Excalidraw JSON

Create the .excalidraw file with appropriate elements:

Available element types:

• rectangle: Boxes for entities, steps, concepts
• ellipse: Alternative shapes for emphasis
• diamond: Decision points
• arrow: Directional connections
• text: Labels and annotations

Key properties to set:

• Position: x, y coordinates
• Size: width, height
• Style: strokeColor, backgroundColor, fillStyle
• Font: fontFamily: 5 (Excalifont - required for all text elements)
• Text: Embedded text for labels
• Connections: points array for arrows

Important: All text elements must use fontFamily: 5 (Excalifont) for consistent visual appearance.

Step 5: Format the Output

Structure the complete Excalidraw file:

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    // Array of diagram elements
  ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": 20
  },
  "files": {}
}

Step 6: Save and Provide Instructions

1. Save as .excalidraw
2. Inform user how to open:

• Visit https://excalidraw.com
• Click "Open" or drag-and-drop the file
• Or use Excalidraw VS Code extension

Best Practices

Element Count Guidelines

| Diagram Type | Recommended Count | Maximum | |--------------|-------------------|---------| | Flowchart steps | 3-10 | 15 | | Relationship entities | 3-8 | 12 | | Mind map branches | 4-6 | 8 | | Mind map sub-topics per branch | 2-4 | 6 |

Layout Tips

1. Start positions: Center important elements, use consistent spacing
2. Spacing:

• Horizontal gap: 200-300px between elements
• Vertical gap: 100-150px between rows

1. Colors: Use consistent color scheme

• Primary elements: Light blue (#a5d8ff)
• Secondary elements: Light green (#b2f2bb)
• Important/Central: Yellow (#ffd43b)
• Alerts/Warnings: Light red (#ffc9c9)

1. Text sizing: 16-24px for readability
2. Font: Always use fontFamily: 5 (Excalifont) for all text elements
3. Arrow style: Use straight arrows for simple flows, curved for complex relationships

Complexity Management

If user request has too many elements:

• Suggest breaking into multiple diagrams
• Focus on main elements first
• Offer to create detailed sub-diagrams

Example response:

"Your request includes 15 components. For clarity, I recommend:
1. High-level architecture diagram (6 main components)
2. Detailed diagram for each subsystem

Would you like me to start with the high-level view?"

Anti-Patterns

• Starting from a generic template without adapting it: The output may look polished but still miss the real audience or medium.
• Ignoring final render or export review: Layout bugs often appear only after the asset is opened in its destination tool.
• Fixing content and presentation in one pass: It becomes hard to tell whether a problem is structural or visual.

Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Excalidraw Diagram Generator implementation names the target runtime, framework version, and affected files.
2. Pass/fail: Build, lint, test, or equivalent local validation is run for the changed surface.
3. Pass/fail: Edge cases for errors, dependency drift, and environment differences are addressed or explicitly out of scope.
4. Pressure-test scenario: Apply the workflow to a change that passes happy-path tests but fails one boundary condition.
5. Success metric: Zero untested success claims; every implementation claim maps to a command or artifact.

Example Prompts and Responses

Example 1: Simple Flowchart

User: "Create a flowchart for user registration"

Agent generates:

1. Extract steps: "Enter email" → "Verify email" → "Set password" → "Complete"
2. Create flowchart with 4 rectangles + 3 arrows
3. Save as user-registration-flow.excalidraw

Example 2: Relationship Diagram

User: "Diagram the relationship between User, Post, and Comment entities"

Agent generates:

1. Entities: User, Post, Comment
2. Relationships: User → Post ("creates"), User → Comment ("writes"), Post → Comment ("contains")
3. Save as user-content-relationships.excalidraw

Example 3: Mind Map

User: "Mind map about machine learning concepts"

Agent generates:

1. Center: "Machine Learning"
2. Branches: Supervised Learning, Unsupervised Learning, Reinforcement Learning, Deep Learning
3. Sub-topics under each branch
4. Save as machine-learning-mindmap.excalidraw

Troubleshooting

| Issue | Solution | |-------|----------| | Elements overlap | Increase spacing between coordinates | | Text doesn't fit in boxes | Increase box width or reduce font size | | Too many elements | Break into multiple diagrams | | Unclear layout | Use grid layout (rows/columns) or radial layout (mind maps) | | Colors inconsistent | Define color palette upfront based on element types |

Advanced Techniques

Grid Layout (for Relationship Diagrams)

const columns = Math.ceil(Math.sqrt(entityCount));
const x = startX + (index % columns) * horizontalGap;
const y = startY + Math.floor(index / columns) * verticalGap;

Radial Layout (for Mind Maps)

const angle = (2 * Math.PI * index) / branchCount;
const x = centerX + radius * Math.cos(angle);
const y = centerY + radius * Math.sin(angle);

Auto-generated IDs

Use timestamp + random string for unique IDs:

const id = Date.now().toString(36) + Math.random().toString(36).substr(2);

Output Format

Always provide:

1. ✅ Complete .excalidraw JSON file
2. 📊 Summary of what was created
3. 📝 Element count
4. 💡 Instructions for opening/editing

Example summary:

Created: user-workflow.excalidraw
Type: Flowchart
Elements: 7 rectangles, 6 arrows, 1 title text
Total: 14 elements

To view:
1. Visit https://excalidraw.com
2. Drag and drop user-workflow.excalidraw
3. Or use File → Open in Excalidraw VS Code extension

Validation Checklist

Before delivering the diagram:

• [ ] All elements have unique IDs
• [ ] Coordinates prevent overlapping
• [ ] Text is readable (font size 16+)
• [ ] All text elements use fontFamily: 5 (Excalifont)
• [ ] Arrows connect logically
• [ ] Colors follow consistent scheme
• [ ] File is valid JSON
• [ ] Element count is reasonable (/reference.md`

1. If library exists: Proceed to use icons (see AI Assistant Workflow below)
2. If library does NOT exist: Respond with setup instructions:

``` To use [AWS/GCP/Azure/etc.] architecture icons, please follow these steps:

1. Visit https://libraries.excalidraw.com/
2. Search for "[AWS Architecture Icons/etc.]" and download the .excalidrawlib file
3. Create directory: skills/excalidraw-diagram-generator/libraries/[icon-set-name]/
4. Place the downloaded file in that directory
5. Run the splitter script:

python skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/[icon-set-name]/

This will split the library into individual icon files for efficient use. After setup is complete, I can create your diagram using the actual AWS/cloud icons.

Alternatively, I can create the diagram now using simple shapes (rectangles, ellipses) which you can later replace with icons manually in Excalidraw. ```

User Setup Instructions (Detailed)

Step 1: Create Library Directory

mkdir -p skills/excalidraw-diagram-generator/libraries/aws-architecture-icons

Step 2: Download Library

• Visit: https://libraries.excalidraw.com/
• Search for your desired icon set (e.g., "AWS Architecture Icons")
• Click download to get the .excalidrawlib file
• Example categories (availability varies; confirm on the site):
• Cloud service icons
• UI/Material icons
• Flowchart symbols

Step 3: Place Library File

• Rename the downloaded file to match the directory name (e.g., aws-architecture-icons.excalidrawlib)
• Move it to the directory created in Step 1

Step 4: Run Splitter Script

python skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/

Step 5: Verify Setup After running the script, verify the following structure exists:

skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/
  aws-architecture-icons.excalidrawlib  (original)
  reference.md                          (generated - icon lookup table)
  icons/                                (generated - individual icon files)
    API-Gateway.json
    CloudFront.json
    EC2.json
    Lambda.json
    RDS.json
    S3.json
    ...

AI Assistant Workflow

When icon libraries are available in libraries/:

RECOMMENDED APPROACH: Use Python Scripts (Efficient & Reliable)

The repository includes Python scripts that handle icon integration automatically:

1. Create base diagram structure:

• Create .excalidraw file with basic layout (title, boxes, regions)
• This establishes the canvas and overall structure

1. Add icons using Python script:

``bash python skills/excalidraw-diagram-generator/scripts/add-icon-to-diagram.py \ [--label "Text"] [--library-path PATH] ``

• Edit via .excalidraw.edit is enabled by default to avoid overwrite issues; pass --no-use-edit-suffix to disable.

Examples: ```bash # Add EC2 icon at position (400, 300) with label python scripts/add-icon-to-diagram.py diagram.excalidraw EC2 400 300 --label "Web Server"

# Add VPC icon at position (200, 150) python scripts/add-icon-to-diagram.py diagram.excalidraw VPC 200 150

# Add icon from different library python scripts/add-icon-to-diagram.py diagram.excalidraw Compute-Engine 500 200 \ --library-path libraries/gcp-icons --label "API Server" ```

1. Add connecting arrows:

``bash python skills/excalidraw-diagram-generator/scripts/add-arrow.py \ [--label "Text"] [--style solid|dashed|dotted] [--color HEX] ``

• Edit via .excalidraw.edit is enabled by default to avoid overwrite issues; pass --no-use-edit-suffix to disable.

Examples: ```bash # Simple arrow from (300, 250) to (500, 300) python scripts/add-arrow.py diagram.excalidraw 300 250 500 300

# Arrow with label python scripts/add-arrow.py diagram.excalidraw 300 250 500 300 --label "HTTPS"

# Dashed arrow with custom color python scripts/add-arrow.py diagram.excalidraw 400 350 60

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: PracticalSwan
• Source: PracticalSwan/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.