Excalidraw Diagram Skill

Install

git clone https://github.com/coleam00/excalidraw-diagram-skill.git
cp -r excalidraw-diagram-skill .claude/skills/excalidraw-diagram

This is third-party code. Review the repository files before installing.

What it does

The skill generates Excalidraw JSON files where shapes mirror meaning: fan-outs for one-to-many, timelines for sequences. Technical diagrams include real code snippets and JSON payloads. A built-in Playwright renderer lets the agent see its output, catch overlaps and misalignment and fix them before delivering. Brand colors and styles live in one file, references/color-palette.md.

Who it is for. Developers and technical content authors who need clear process and architecture diagrams.

Example request

Create an Excalidraw diagram showing how the AG-UI protocol streams events from an agent to a frontend

Limitations

Visual validation needs the renderer set up: uv sync and Chromium via Playwright. Installation is manual only, by copying into .claude/skills.

How to disable. Delete the .claude/skills/excalidraw-diagram folder.

Security check

• The renderer runs a Python script and Chromium

README in short

A short README for an Excalidraw diagram skill compatible with agents reading .claude/skills, such as Claude Code and OpenCode. It covers copy-based installation, two renderer setup options and an example prompt. The file structure with element templates and JSON schema references is listed.

SKILL.md

---
name: excalidraw-diagram
description: Create Excalidraw diagram JSON files that make visual arguments. Use when the user wants to visualize workflows, architectures, or concepts.
---

# 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

Related