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:
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.- 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.
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.
1---2name: excalidraw-diagrams3description: 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.4---56# Excalidraw78This 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.910## Job 1: Never read Excalidraw files directly — delegate to a subagent1112Excalidraw 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.1314**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.1516For the exact subagent task templates (read/modify/create/compare), the full reasoning, and token measurements, see `references/delegation-details.md`. The short version:17- **Understand a diagram** → subagent reads it, returns a component list + relationships, not JSON.18- **Modify a diagram** → subagent reads it, adds elements using the style guide below, writes the file, returns a confirmation + new element ids.19- **Create a diagram** → subagent designs and writes it using the style guide below, returns a summary + file location.20- **Compare diagrams** → subagent reads both, returns the differences, not two dumps of JSON.2122## Job 2: Match the house style when creating or adding to a diagram2324Three 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:25261. **`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.272. Then the file matching what you're building:28 - **`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.29 - **`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.30 - **`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.313. **`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.3233If 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.3435## Red flags — stop and delegate instead3637Catch yourself about to:38- Use the Read tool on a `.excalidraw` file "just to check something quick"39- Parse or write Excalidraw JSON directly in the main conversation40- Load multiple diagrams to compare them side by side in-context41- Place a colored box without having decided what that color means elsewhere in the same diagram4243All of these mean: dispatch a subagent, and point it at the relevant reference file(s) above.
mk-joshuajallen