Excalidraw Diagram
Generate Excalidraw `.excalidraw` JSON diagrams that visually argue architecture, workflows, and concepts—not bullet slides—for specs and READMEs.
Overview
excalidraw-diagram is an agent skill most often used in Build (also Validate and Launch) that creates Excalidraw JSON diagrams which visually argue workflows, architectures, and concepts.
Install
npx skills add https://github.com/coleam00/excalidraw-diagram-skill --skill excalidraw-diagramWhat is this skill?
- Outputs `.excalidraw` JSON designed to argue visually via structure, flow, and causality—not labeled boxes only
- Isomorphism Test and Education Test: structure and concrete examples must teach without relying on text alone
- Mandatory `references/color-palette.md` as single source of truth for brand fills, strokes, and text colors
- Depth Assessment step before drafting to match diagram complexity to the audience
- Setup and renderer instructions live in README.md when users need local preview
- Single brand color source file: references/color-palette.md for all fills, strokes, and text colors
- Two quality gates named in SKILL.md: Isomorphism Test and Education Test
Adoption & trust: 5.2k installs on skills.sh; 3.5k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your architecture notes are a wall of bullets and nobody—including your agent—can see flow, boundaries, or cause and effect.
Who is it for?
Indie builders who want opinionated visual storytelling for system design, onboarding docs, and product explanations without opening a design tool for every iteration.
Skip if: Pixel-perfect UI mockups, automated Mermaid-only pipelines where JSON hand-editing is unwanted, or diagrams that only need a single static screenshot with no reusable source.
When should I use this skill?
The user wants to visualize workflows, architectures, or concepts as Excalidraw diagrams.
What do I get? / Deliverables
You receive a structured `.excalidraw` file (and iterative edits) that encodes relationships and flow, styled from your color palette, ready to render or embed in docs.
- .excalidraw JSON diagram files
- Brand-consistent color choices per color-palette.md
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Diagram artifacts most often ship as documentation during Build, though the same skill supports early architecture thinking in Validate. Docs subphase covers explainers, architecture figures, and workflow maps saved as portable Excalidraw files.
Where it fits
Map MVP components and data flows before committing to a monolith vs services split.
Produce an onboarding diagram showing how your agent, API, and queue interact with real event names.
Draw webhook and OAuth sequences with concrete endpoints instead of abstract ‘API box’ labels.
Visualize launch checklist dependencies for blog, email, and Product Hunt in one causal figure.
How it compares
Generates editable Excalidraw source with design methodology—not a generic ‘draw a chart’ one-liner or an MCP diagram server.
Common Questions / FAQ
Who is excalidraw-diagram for?
Solo founders and technical writers using Claude Code or Cursor to produce architecture and workflow figures as first-class `.excalidraw` assets.
When should I use excalidraw-diagram?
At Validate when mapping scope and system boundaries; at Build when documenting agent workflows or APIs; at Launch when visualizing distribution funnels; whenever the user asks to visualize workflows, architectures, or concepts.
Is excalidraw-diagram safe to install?
It is primarily file-generation guidance; review the repo README, local renderer steps, and the Security Audits panel on this Prism page before running bundled scripts.
SKILL.md
READMESKILL.md - Excalidraw Diagram
# Excalidraw Diagram Creator Generate `.excalidraw` JSON files that **argue visually**, not just display information. **Setup:** If the user asks you to set up this skill (renderer, dependencies, etc.), see `README.md` for instructions. ## Customization **All colors and brand-specific styles live in one file:** `references/color-palette.md`. Read it before generating any diagram and use it as the single source of truth for all color choices — shape fills, strokes, text colors, evidence artifact backgrounds, everything. To make this skill produce diagrams in your own brand style, edit `color-palette.md`. Everything else in this file is universal design methodology and Excalidraw best practices. --- ## Core Philosophy **Diagrams should ARGUE, not DISPLAY.** A diagram isn't 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 Isomorphism Test**: If you removed all text, would the structure alone communicate the concept? If not, redesign. **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. --- ## Depth Assessment (Do This First) Before designing, determine what level of detail this diagram needs: ### Simple/Conceptual Diagrams Use abstract shapes when: - Explaining a mental model or philosophy - The audience doesn't need technical specifics - The concept IS the abstraction (e.g., "separation of concerns") ### Comprehensive/Technical Diagrams Use concrete examples when: - Diagramming a real system, protocol, or architecture - The diagram will be used to teach or explain (e.g., YouTube video) - The audience needs to understand what things actually look like - You're showing how multiple technologies integrate **For technical diagrams, you MUST include evidence artifacts** (see below). --- ## Research Mandate (For Technical Diagrams) **Before drawing anything technical, research the actual specifications.** If you're diagramming a protocol, API, or framework: 1. Look up the actual JSON/data formats 2. Find the real event names, method names, or API endpoints 3. Understand how the pieces actually connect 4. Use real terminology, not generic placeholders Bad: "Protocol" → "Frontend" Good: "AG-UI streams events (RUN_STARTED, STATE_DELTA, A2UI_UPDATE)" → "CopilotKit renders via createA2UIMessageRenderer()" **Research makes diagrams accurate AND educational.** --- ## Evidence Artifacts Evidence artifacts are concrete examples that prove your diagram is accurate and help viewers learn. Include them in technical diagrams. **Types of evidence artifacts** (choose what's relevant to your diagram): | Artifact Type | When to Use | How to Render | |---------------|-------------|---------------| | **Code snippets** | APIs, integrations, implementation details | Dark rectangle + syntax-colored text (see color palette for evidence artifact colors) | | **Data/JSON examples** | Data formats, schemas, payloads | Dark rectangle + colored text (see color palette) | | **Event/step sequences** | Protocols, workflows, lifecycles | Timeline pattern (line + dots + labels) | | **UI mockups** | Showing actual output/results | Nested rectangles mimicking real UI | | **Real input content** | Showing what goes IN to a system | Rectangle with sample content visible | | **API/method names** | Real function calls, endpoints | Use actual names from docs, not placeholders | **Example**: For a diagram about a streaming protocol, you might show: - The actual event names from the spec (not just "Event 1", "Event 2") - A code snippet showing how to connect - What the streamed data actually looks like **Example**: For