coleam00/excalidraw-diagram-skill

Overview

This skill generates Excalidraw .excalidraw JSON files that make visual arguments for workflows, architectures, and concepts. It follows a design methodology that prioritizes structure, educational value, and brand-consistent styling. Use it to produce diagrams that teach and prove, not just label.

How this skill works

The skill reads a single color palette file as the source of truth for every visual style decision, then builds Excalidraw elements section-by-section to avoid oversized, brittle JSON. For comprehensive technical diagrams it mandates research, evidence artifacts (code, JSON, event names), and a render–view–fix loop to validate layout, bindings, and visual hierarchy. Outputs are ready-to-open .excalidraw JSON files with descriptive element IDs and clear multi-zoom structure.

When to use it

• Visualizing system architectures with real API/event names
• Explaining workflows or protocols where structure implies behavior
• Teaching technical formats with concrete examples (code/JSON snippets)
• Creating conceptual diagrams that must convey relationships without heavy text
• Producing large diagrams that need section-by-section composition and validation

Best practices

• Always read and use the single color-palette file for fills, strokes, and evidence backgrounds
• Start with a depth assessment (simple vs comprehensive) before designing
• For technical diagrams, research real specs and include evidence artifacts (code, JSON, event names)
• Build large diagrams one section at a time with descriptive IDs and namespaced seeds
• Apply the Isomorphism Test: remove text mentally—does the structure still communicate?

Example use cases

• Architecture diagram showing client → services → database with example request/response JSON
• Streaming protocol diagram with actual event names and a timeline evidence artifact
• Educational slide diagram that teaches a transformation pipeline using multi-zoom levels
• Conceptual mental-model diagram (simple) that uses shapes as meaning rather than boxed labels
• Operational runbook visual that includes real commands or sample API snippets as evidence