Quickstart

Create your first Excalidraw diagram in under 2 minutes using natural language descriptions.

This guide will get you from zero to your first working diagram as quickly as possible.

Your First Diagram

Once the skill is installed, ask your coding agent to create a diagram:

Create an Excalidraw diagram showing how a streaming protocol sends events from a backend to a frontend

The agent will:

1. Analyze the concept and map it to visual patterns
2. Generate Excalidraw JSON with appropriate shapes and flows
3. Render the diagram to PNG using the render pipeline
4. View the rendered image to check for issues
5. Fix any layout problems (overlaps, clipping, misalignments)
6. Re-render and repeat until the diagram looks right

You’ll receive a .excalidraw file and a .png file.

The render-view-fix loop is automatic and mandatory — every diagram is visually validated before delivery.

Example: Simple Conceptual Diagram

For a simple, high-level diagram:

Create a diagram showing the difference between diagrams that "display" information vs diagrams that "argue" visually

The agent will create a side-by-side comparison using abstract shapes and visual contrast.

Example: Comprehensive Technical Diagram

For a detailed technical diagram with real examples:

Create a comprehensive diagram of the AG-UI protocol showing:
- How events stream from an AI agent to a frontend UI
- Real event names from the specification
- Actual code snippets for connecting
- Sample JSON payloads

The agent will:

• Research the actual AG-UI protocol specification
• Include real event names (e.g., RUN_STARTED, STATE_DELTA, A2UI_UPDATE)
• Add code snippets showing how to use the protocol
• Display sample JSON payloads with proper formatting
• Create a multi-zoom diagram with summary flow, section boundaries, and detailed evidence artifacts

For technical diagrams, the agent must research actual specifications before generating JSON. This ensures diagrams are accurate and educational.

Understanding the Output

The .excalidraw File

This is the editable source — a JSON file you can open in Excalidraw to make manual adjustments if needed.

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    // All shapes, arrows, text elements
  ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": 20
  },
  "files": {}
}

The .png File

This is the rendered output — a publication-ready image you can embed in documentation, slides, or articles.

What Makes These Diagrams Different

1. Visual Patterns Mirror Concepts

   Instead of uniform boxes, each concept gets a shape that reflects its behavior:

   • Fan-outs for one-to-many relationships
   • Convergence for aggregation
   • Timelines for sequences
   • Spirals for loops
2. Real Examples, Not Placeholders

   Technical diagrams include:

   • Actual code snippets with syntax highlighting
   • Real event names from specifications
   • Sample JSON payloads
   • Concrete examples instead of generic labels
3. Visual Validation Built-In

   Every diagram is:

   • Rendered to PNG
   • Inspected by the agent for overlaps, clipping, and spacing issues
   • Fixed and re-rendered in a loop
   • Delivered only when it passes visual validation

Common Patterns

Here are some common diagram requests and what the agent will create:

Architecture Diagrams

Create a diagram of our microservices architecture showing:
- Service boundaries
- API contracts between services
- Data flow
- Include real endpoint paths and request/response formats

The agent will create a comprehensive diagram with actual API payloads and clear service boundaries.

Data Flow Diagrams

Show how user data flows through our analytics pipeline:
- Raw input format
- Transformation steps
- Final output structure
- Include sample data at each stage

The agent will use an assembly-line pattern with before/after examples at each transformation.

State Machine Diagrams

Create a diagram of our order processing state machine:
- All possible states
- Transitions between states
- Events that trigger transitions
- Use real state and event names from our codebase

The agent will create a cycle/spiral pattern with specific state names and transition labels.

Comparison Diagrams

Compare our old authentication flow vs the new OAuth implementation side-by-side

The agent will create parallel structures with visual contrast showing the differences.

Tips for Better Diagrams

Be Specific

Instead of “create a diagram of our API”, say “create a diagram showing the authentication flow with real JWT payload structure”

Request Evidence

Ask for “real code examples”, “actual event names”, or “sample JSON payloads” to get educational diagrams

Specify Depth

Use “simple” for conceptual overviews or “comprehensive” for detailed technical diagrams with examples

Name the Pattern

If you know what pattern fits, mention it: “use a fan-out pattern” or “show this as a timeline”

Next Steps

Design Principles

Learn the methodology behind the diagrams

Visual Patterns

Explore the pattern library (fan-out, convergence, timelines, etc.)

Customization

Customize colors to match your brand

Render & Validate

Master the render-view-fix loop

The agent will not create diagrams without visual validation. Every diagram goes through the render-view-fix loop. This is a feature, not a limitation — it ensures quality.