# Excalidraw Diagrams

> Use whenever working with *.excalidraw or *.excalidraw.json files, or when the user asks to create/update/explain/review an architecture diagram, presentation/discovery deck, gantt chart, roadmap, sprint plan, flowchart, or any other visual diagram — even if they don't say the word 'Excalidraw'. Covers two things: (1) delegating all reads/writes of Excalidraw JSON to subagents so the verbose format never floods the main context, and (2) a house style guide — colors, typography, layout, arrow conventions, per-diagram-type templates — reverse-engineered from real diagrams the user has confirmed look good, so newly created diagrams match that bar instead of looking like generic default Excalidraw output.

- Skill: `mk-joshuajallen/excalidraw-diagrams` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add mk-joshuajallen/excalidraw-diagrams`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mk-joshuajallen/excalidraw-diagrams/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: mk-joshuajallen (https://skillmd.com/u/mk-joshuajallen)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/mk-joshuajallen/excalidraw-diagrams

---


# Excalidraw

This skill has two jobs: keep verbose Excalidraw JSON out of the main context, and make sure any diagram you create actually looks good — matching a house style reverse-engineered from real examples rather than generic Excalidraw defaults.

## Job 1: Never read Excalidraw files directly — delegate to a subagent

Excalidraw JSON has a terrible signal-to-noise ratio: 20+ properties per element, most of them positioning/styling noise, with actual content (text + relationships) under 10% of the file. A single file runs 4k–22k tokens; reading a handful of them can burn a third of a context budget on data that's 90% metadata.

**The rule: main agents never read `.excalidraw`/`.excalidraw.json` files with the Read tool, and never write raw element JSON directly into the main conversation.** Always dispatch a subagent (Task tool) instead, give it a clear goal, and have it return a condensed text summary or a confirmation — not raw JSON. This applies even to "small" files, "quick" checks, and single-file edits — the isolation is what matters, not the file size.

For the exact subagent task templates (read/modify/create/compare), the full reasoning, and token measurements, see `references/delegation-details.md`. The short version:
- **Understand a diagram** → subagent reads it, returns a component list + relationships, not JSON.
- **Modify a diagram** → subagent reads it, adds elements using the style guide below, writes the file, returns a confirmation + new element ids.
- **Create a diagram** → subagent designs and writes it using the style guide below, returns a summary + file location.
- **Compare diagrams** → subagent reads both, returns the differences, not two dumps of JSON.

## Job 2: Match the house style when creating or adding to a diagram

Three files in this workspace were pointed out as canonical "what good looks like" examples, and were reverse-engineered element-by-element to produce a concrete style guide — not vague adjectives like "clean" or "professional," but actual hex colors, font sizes, roundness values, and layout patterns. Before creating new elements, read:

1. **`references/style-guide.md`** — the rules that hold across every diagram type: a small semantic color palette (never decorative), one near-black stroke color almost everywhere, rounded corners as the default, no `groupIds` (group by proximity/enclosing containers instead), arrows bound to shapes and left unlabeled, a strict font-size hierarchy, and a cleanup pass before calling anything done. Read this first, always.
2. Then the file matching what you're building:
   - **`references/architecture-diagrams.md`** — system/service diagrams: role-based color-coding (Command/Event/Service/Stage), swimlanes by system, phase bands, legend construction, labeled-node-instead-of-labeled-arrow convention.
   - **`references/presentation-slides.md`** — white/minimal decks: why this house style does NOT use frame elements for slides, whitespace-driven layout, the title→sub-header→caption→card pattern, the hand-drawn-title/plain-sans-body font mix.
   - **`references/gantt-roadmaps.md`** — sprint plans/roadmaps: stacked timeline header bands instead of gridlines, status-color coding, hachure-vs-solid fill tiers, milestone styling (dotted red rectangles, not diamonds), the "today" zone convention.
3. **`references/element-templates.md`** — copy-paste-ready element JSON (rectangle+bound-text, legend swatch, bound arrow, phase container, milestone, "today" zone, slide title) with every style value already filled in, so you're filling in `x`/`y`/`text` rather than re-deriving colors and font settings from scratch each time.

If the request doesn't fit any of the three named types, `style-guide.md`'s cross-cutting rules (palette discipline, stroke consistency, roundness, typography hierarchy) still apply — they're what makes any diagram in this style look intentional rather than default.

## Red flags — stop and delegate instead

Catch yourself about to:
- Use the Read tool on a `.excalidraw` file "just to check something quick"
- Parse or write Excalidraw JSON directly in the main conversation
- Load multiple diagrams to compare them side by side in-context
- Place a colored box without having decided what that color means elsewhere in the same diagram

All of these mean: dispatch a subagent, and point it at the relevant reference file(s) above.