Skip to content

softaworks/agent-toolkit / skills/excalidraw

excalidraw

Unverified

Use when working with *.excalidraw or *.excalidraw.json files, user mentions diagrams/flowcharts, or requests architecture visualization - delegates all Excalidraw operations to subagents to prevent context exhaustion from verbose JSON (single files: 4k-22k tokens, can exceed read limits)

Excalidraw Subagent Delegation

Overview

Core principle: Main agents NEVER read Excalidraw files directly. Always delegate to subagents to isolate context consumption.

Excalidraw files are JSON with high token cost but low information density. Single files range from 4k-22k tokens (largest can exceed read tool limits). Reading multiple diagrams quickly exhausts context budget (7 files = 67k tokens = 33% of budget).

The Problem

Excalidraw JSON structure:

  • Each shape has 20+ properties (x, y, width, height, strokeColor, seed, version, etc.)
  • Most properties are visual metadata (positioning, styling, roughness)
  • Actual content: text labels and element relationships (<10% of file)
  • Signal-to-noise ratio is extremely low

Example: 14-element diagram = 596 lines, 16K, ~4k tokens. 79-element diagram = 2,916 lines, 88K, ~22k tokens (exceeds read limit).

When to Use

Trigger on ANY of these:

  • File path contains .excalidraw or .excalidraw.json
  • User requests: "explain/update/create diagram", "show architecture", "visualize flow"
  • User mentions: "flowchart", "architecture diagram", "Excalidraw file"
  • Architecture/design documentation tasks involving visual artifacts

Use delegation even for:

  • "Small" files (smallest is 4k tokens - still significant)
  • "Quick checks" (checking component names still loads full JSON)
  • Single file operations (isolation prevents context pollution)
  • Modifications (don't need full format understanding in main context)

Delegation Pattern

Main Agent Responsibilities

NEVER:

  • ❌ Use Read tool on *.excalidraw files
  • ❌ Parse Excalidraw JSON in main context
  • ❌ Load multiple diagrams for comparison
  • ❌ Inspect file to "understand the format"

ALWAYS:

  • ✅ Delegate ALL Excalidraw operations to subagents
  • ✅ Provide clear task description to subagent
  • ✅ Request text-only summaries (not raw JSON)
  • ✅ Keep diagram analysis isolated from main work

Subagent Task Templates

Read/Understand Operation

Task: Extract and explain the components in [file.excalidraw.json]

Approach:
1. Read the Excalidraw JSON
2. Extract only text elements (ignore positioning/styling)
3. Identify relationships between components
4. Summarize architecture/flow

Return:
- List of components/services with descriptions
- Connection/dependency relationships
- Key insights about the architecture
- DO NOT return raw JSON or verbose element details

Modify Operation

Task: Add [component] to [file.excalidraw.json], connected to [existing-component]

Approach:
1. Read file to identify existing elements
2. Find [existing-component] and its position
3. Create new element JSON for [component]
4. Add arrow elements for connections
5. Write updated file

Return:
- Confirmation of changes made
- Position of new element
- IDs of created elements

Create Operation

Task: Create new Excalidraw diagram showing [description]

Approach:
1. Design layout for [number] components
2. Create rectangle elements with text labels
3. Add arrows showing relationships
4. Use consistent styling (colors, fonts)
5. Write to [file.excalidraw.json]

Return:
- Confirmation of file created
- Summary of components included
- File location

Compare Operation

Task: Compare architecture approaches in [file1] vs [file2]

Approach:
1. Read both files
2. Extract text labels from each
3. Identify structural differences
4. Compare component relationships

Return:
- Key differences in architecture
- Components unique to each approach
- Relationship/flow differences
- DO NOT return full element details from both files

Common Rationalizations (STOP and Delegate Instead)

ExcuseRealityWhat to Do
"Direct reading is most efficient"Consumes 4k-22k tokens unnecessarilyDelegate to subagent
"It's token-efficient to read directly"Baseline tests showed 9-45% budget usedAlways delegate
"This is optimal for one-time analysis""One-time" still pollutes main contextSubagent isolation
"The JSON is straightforward"Simplicity ≠ token efficiencyDelegate anyway
"I need to understand the format"Format understanding not needed in main agentSubagent handles format
"Within reasonable bounds" (18k tokens)"Reasonable" is subjective rationalizationHard rule: delegate
"Just a quick check of components""Quick check" still loads full JSONExtract text via subagent
"File is small (16K)"4k tokens is NOT smallSize threshold doesn't matter

Red Flags - STOP and Delegate

Catch yourself about to:

  • Use Read tool on .excalidraw file
  • "Quickly check" what components exist
  • "Understand the structure" before modifying
  • Load file to "see what's there"
  • Compare multiple diagrams side-by-side
  • Parse JSON to "extract just the text"

All of these mean: Use Task tool with subagent instead.

Quick Reference

OperationMain Agent ActionSubagent Returns
Understand diagramDelegate with "Extract and explain" templateComponent list + relationships
Modify diagramDelegate with "Add [X] connected to [Y]" templateConfirmation + changes made
Create diagramDelegate with "Create showing [description]" templateFile location + summary
Compare diagramsDelegate with "Compare [A] vs [B]" templateKey differences (not raw JSON)

Token Analysis (Why This Matters)

Real data from baseline testing:

ScenarioWithout DelegationWith DelegationSavings
Single large file22k tokens (45% budget)~500 tokens (subagent summary)98%
Two-file comparison18k tokens (9% budget)~800 tokens (diff summary)96%
Modification task14k tokens (7% budget)~300 tokens (confirmation)98%

Context pollution impact:

  • Reading all 7 project diagrams: 67k tokens (33% of 200k budget)
  • With delegation: ~2k tokens (isolated in subagents)
  • Savings: 97% context budget preserved

Implementation Example

❌ BAD (Direct Read):

User: "What architecture is shown in detailed-architecture.excalidraw.json?"
Agent: Let me read that file... [reads 22k tokens into main context]

✅ GOOD (Subagent Delegation):

User: "What architecture is shown in detailed-architecture.excalidraw.json?"
Agent: I'll use a subagent to extract the architecture details.

[Dispatches Task tool with general-purpose subagent]
Task: Extract and explain components in .ryanquinn3/ticketing/detailed-architecture.excalidraw.json

[Receives ~500 token summary with component list and relationships]
[Responds to user with architecture explanation, main context preserved]

Why "Straightforward JSON" Doesn't Matter

Agents often rationalize: "The format is simple, I can just read it."

The problem isn't complexity - it's verbosity:

  • Simple structure with 20+ properties per element
  • Repetitive metadata (seed, version, nonce, roughness)
  • Positioning data (x, y, width, height) not semantically useful
  • Visual styling (strokeColor, opacity, fillStyle) irrelevant to content

Token cost comes from volume, not complexity.

Even "straightforward" JSON consumes 4k-22k tokens because:

  • 79 elements × ~280 tokens/element = 22k tokens
  • Most tokens are metadata noise
  • Only text labels and relationships matter (~10% of content)

The Iron Law

Main agents NEVER read Excalidraw files. No exceptions.

Not for:

  • "Quick checks"
  • "Small files"
  • "Understanding format"
  • "One-time analysis"
  • "Optimal efficiency"

Always delegate. Isolation is free via subagents.

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 463kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 463kUpdated Claude CodeCodexVerifiedInstall
discernment-nudgeanthropics/skillsAfter you give a substantive answer or draft that the user may act on — advice or recommendations, drafted artifacts such as goals, plans, pitches, proposals, or emails, estimates or projections, analysis or interpretation of data, factual claims they may rely on, or a multi-step argument — invoke this skill BEFORE finalizing your reply and then, if it applies, append 2-3 short follow-up questions, each tied to something specific in what you just produced, that help the user check key facts, probe the reasoning or assumptions, and notice missing context. Do this at most once per conversation. Skip it when the user asked a trivial how-to or simple lookup, wants a purely educational explanation, asked you only to format, convert, or assemble a file from content they provided, is writing code they will run, is doing creative writing or casual chat, or already asked you to double-check, cite, or review — the skill file explains these boundaries and the exact output format.Stars: 195kUpdated Claude CodeCodexVerifiedInstall
internal-commsanthropics/skillsA set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).Stars: 195kUpdated Claude CodeCodexVerifiedInstall