Skip to main content
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: 
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.
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.
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.
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us