Installation

Install the Excalidraw Diagram Skill and set up the render pipeline for visual validation.

Installing the Excalidraw Diagram Skill is a two-step process: first, add the skill to your project, then set up the render pipeline for visual validation.

Prerequisites

• A coding agent that supports skills (Claude Code, OpenCode, or compatible)
• Python 3.8+ (for the render pipeline)
• uv package manager (recommended)

Step 1: Install the Skill

Clone or download the repository and copy it into your project’s .claude/skills/ directory:

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

The skill files must be in .claude/skills/excalidraw-diagram/ for agents to discover them.

Step 2: Set Up the Render Pipeline

The skill includes a render pipeline that lets the agent visually validate its diagrams. This is a mandatory part of the workflow — diagrams are rendered to PNG, inspected by the agent, and fixed in a loop until they look right.

There are two ways to set it up:

Option A: Ask Your Agent (Easiest)

The simplest approach is to let your coding agent set everything up for you.

Just tell your agent:

Set up the Excalidraw diagram skill renderer by following the instructions in SKILL.md.

The agent will:

1. Navigate to the correct directory
2. Run uv sync to install Python dependencies
3. Run uv run playwright install chromium to install the browser

This is the recommended approach — your agent knows how to read the setup instructions and execute them correctly.

Option B: Manual Setup

If you prefer to set it up yourself, run these commands:

cd .claude/skills/excalidraw-diagram/references
uv sync
uv run playwright install chromium

What Each Command Does

• uv sync — Installs Python dependencies from pyproject.toml (Playwright)
• uv run playwright install chromium — Downloads the Chromium browser for rendering

Troubleshooting

If you don’t have uv installed:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or use pip
pip install uv

If you encounter permission errors, you may need to run with elevated privileges or adjust your Python environment.

Verify Installation

To verify the render pipeline is working:

cd .claude/skills/excalidraw-diagram/references
uv run python render_excalidraw.py --help

You should see usage information for the render script.

File Structure

After installation, your skill directory should look like this:

.claude/skills/excalidraw-diagram/
  SKILL.md                          # Design methodology + workflow
  references/
    color-palette.md                # Brand colors (edit this to customize)
    element-templates.md            # JSON templates for each element type
    json-schema.md                  # Excalidraw JSON format reference
    render_excalidraw.py            # Render .excalidraw to PNG
    render_template.html            # Browser template for rendering
    pyproject.toml                  # Python dependencies (playwright)

Next Steps

Quickstart

Create your first diagram in under 2 minutes

Customize Colors

Match diagrams to your brand palette

The render pipeline is a core part of the workflow, not an optional feature. Every diagram gets rendered, viewed, and fixed in a loop before delivery.