> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/coleam00/excalidraw-diagram-skill/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> A coding agent skill that generates beautiful Excalidraw diagrams from natural language descriptions. Not just boxes-and-arrows — diagrams that argue visually.

The Excalidraw Diagram Skill is a specialized tool for coding agents that transforms natural language descriptions into professional, semantically-rich Excalidraw diagrams.

## What Makes This Different

Most diagramming tools produce uniform card grids and boxes-and-arrows. This skill takes a fundamentally different approach:

### Diagrams that Argue, Not Display

Every shape or group of shapes mirrors the concept it represents:

* **Fan-outs** for one-to-many relationships
* **Timelines** for sequences
* **Convergence** for aggregation
* **No uniform card grids** — each concept gets a unique visual pattern

<Note>
  **The Isomorphism Test**: If you removed all text, would the structure alone communicate the concept? If not, it's not a good diagram.
</Note>

### Evidence Artifacts

Technical diagrams include real, concrete examples:

* **Real code snippets** with syntax highlighting
* **Actual JSON payloads** from specifications
* **Specific event names** instead of generic placeholders
* **UI mockups** showing actual output

This transforms diagrams from simple visualizations into educational tools that teach viewers how systems actually work.

### Built-in Visual Validation

The skill includes a Playwright-based render pipeline that:

1. Renders diagrams to PNG
2. Lets the agent **see its own output**
3. Catches layout issues (overlapping text, misaligned arrows, unbalanced spacing)
4. Fixes problems in a loop before delivering

This render-view-fix cycle is mandatory, ensuring every diagram is visually validated before you see it.

### Brand-Customizable

All colors and brand styles live in a single file (`references/color-palette.md`). Swap it out and every diagram follows your palette — no need to modify the core methodology.

## Core Philosophy

**Diagrams should ARGUE, not DISPLAY.**

A diagram isn't just formatted text. It's a visual argument that shows relationships, causality, and flow that words alone can't express. The shape should BE the meaning.

**The Education Test**: Could someone learn something concrete from this diagram, or does it just label boxes? A good diagram teaches — it shows actual formats, real event names, concrete examples.

## Who Should Use This

This skill is ideal for:

* **Technical architects** documenting complex systems
* **Educators** creating visual explanations
* **Documentation teams** that need diagrams with real code examples
* **Anyone** working with coding agents who want diagrams that go beyond simple flowcharts

## Compatibility

Compatible with any coding agent that supports skills. For agents that read from `.claude/skills/` (like [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [OpenCode](https://github.com/nicepkg/OpenCode)), just drop it in and go.

## What You'll Create

With this skill, you can generate:

* Architecture diagrams with actual API payloads
* Protocol flows showing real event sequences
* Data transformation pipelines with sample input/output
* System integrations with concrete code examples
* Multi-zoom diagrams operating at summary, section, and detail levels simultaneously

<Tip>
  Ready to get started? The next section covers installation and setup.
</Tip>