excalidraw

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

CLAUDE.md

Audit 0.4.1 · source sha 28aecfe29fbf · 31 Oct 2026Report an issue or request a re-scan

• Publishersoftaworks GitHub organizationOwner of the repository this skill is read from
• Source foldersoftaworks/agent-toolkit/skills/excalidrawThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict28aecfe29fbfA new audit runs when the source changes
• Repository statusNot archivedLast push 239 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: 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…

---
name: excalidraw
description: "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)

| Excuse | Reality | What to Do |
|--------|---------|------------|
| "Direct reading is most efficient" | Consumes 4k-22k tokens unnecessarily | Delegate to subagent |
| "It's token-efficient to read directly" | Baseline tests showed 9-45% budget used | Always delegate |
| "This is optimal for one-time analysis" | "One-time" still pollutes main context | Subagent isolation |
| "The JSON is straightforward" | Simplicity ≠ token efficiency | Delegate anyway |
| "I need to understand the format" | Format understanding not needed in main agent | Subagent handles format |
| "Within reasonable bounds" (18k tokens) | "Reasonable" is subjective rationalization | Hard rule: delegate |
| "Just a quick check of components" | "Quick check" still loads full JSON | Extract text via subagent |
| "File is small (16K)" | 4k tokens is NOT small | Size 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

| Operation | Main Agent Action | Subagent Returns |
|-----------|-------------------|------------------|
| **Understand diagram** | Delegate with "Extract and explain" template | Component list + relationships |
| **Modify diagram** | Delegate with "Add [X] connected to [Y]" template | Confirmation + changes made |
| **Create diagram** | Delegate with "Create showing [description]" template | File location + summary |
| **Compare diagrams** | Delegate with "Compare [A] vs [B]" template | Key differences (not raw JSON) |

## Token Analysis (Why This Matters)

Real data from baseline testing:

| Scenario | Without Delegation | With Delegation | Savings |
|----------|-------------------|-----------------|---------|
| S

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-31
   ✓SAFE B 89 / 100

   first audit · source 28aecfe29fbf

Questions about excalidraw

• github.com/softaworks/agent-toolkit/tree/main/skills/excalidraw — the audited source at commit 28aecfe29fbf and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology