excalidraw

Files (5)

• SKILL.md
• excalidraw-api.md · reference/
• color-palette.md · references/
• element-templates.md · references/
• json-schema.md · references/

SKILL.md (first lines)

# Excalidraw Diagram Creator

Generate Excalidraw diagrams using the ExcalidrawAutomate (EA) API. Output is a
compressed-Markdown drawing file saved directly to the Obsidian vault — Obsidian
renders it natively.

> [!important] On-disk filename — read this first
> `ea.create({ filename: "foo" })` does **not** write `foo.excalidraw`. It writes
> **`foo.excalidraw.md`** (Excalidraw stores drawings as compressed Markdown).
> Throughout this skill, when you call `ea.create({ filename: "name", ... })`:
> - The actual file on disk is **`<foldername>/name.excalidraw.md`**.
> - Embeds stay **`![[name.excalidraw]]`** — Obsidian resolves the `.excalidraw`
>   basename to the real `name.excalidraw.md` file (do **not** write
>   `![[name.excalidraw.md]]`).
> - **Verify success by the on-disk path `name.excalidraw.md`, not
>   `name.excalidraw`.** A headless agent that `stat`s `name.excalidraw` will
>   never find it and will falsely report failure.

**Before writing any diagram code**, read the bundled EA API reference at:
`${CLAUDE_PLUGIN_ROOT}/skills/excalidraw/reference/excalidraw-api.md`

For the full upstream plugin source, clone https://github.com/zsviczian/obsidian-excalidraw-plugin.

This skill has **two modes** depending on the request:

- **Single Diagram Mode** — user wants ONE diagram of a specific concept. Output: one `<name>.excalidraw.md` file.
- **Codebase Walkthrough Mode** — user wants to document an entire codebase visually. Output: 4-6 `<name>.excalidraw.md` files + interlinked markdown notes.

If the request mentions "document the codebase", "walk through this system", "map out this repo", or similar, jump to the **Codebase Walkthrough Mode** section. Otherwise stay in Single Diagram Mode.

---

## Core Philosophy

**Diagrams should ARGUE, not DISPLAY.**

A diagram isn't formatted text. It's a visual argument that shows relationships,
causality, and flow that words alone can't express. The shape should BE the meaning.

**The Isomorphism Test**: If you removed all text, would the structure alone communicate
the concept? If not, redesign.

For technical diagrams, use real names from the codebase — never "Service A" or "Handler".

---

## How to Generate a Diagram

Every diagram is a JavaScript script that uses the EA API. A **headless agent
runs it via `Obsidian.com eval`** (see "Headless Execution" below) — this is the
default path for Claude. Templater or a vault EA script is only for a human
running it interactively inside Obsidian; do not assume Templater is available.

### Script Pattern

```javascript
const ea = ExcalidrawAutomate;
ea.reset(); // Always call first

// Set global styles
ea.style.roughness = 0;
ea.style.strokeWidth = 2;
ea.style.fontFamily = 1; // 1=Virgil, 2=Helvetica, 3=Cascadia

// Add elements
const rectId = ea.addRect(x, y, width, height);
const textId = ea.addText(x, y, "Label", { box: true, boxPadding: 15, width: 200 });
const ellipseId = ea.addEllipse(x, y, width, height);
const diamondId = ea.addDiamond(x, y, width, height);

// Connect elements
ea.connectObjects(idA, "right", idB, "left", {
  label: "arrow label",
  startArrowHead: null,
  endArrowHead: "arrow",
});

// Save to vault. NOTE: this writes "2. Areas/Excalidraw/diagram-name.excalidraw.md"
// (filename has NO extension here; EA appends ".excalidraw.md"). ea.create() is
// async — always `await` it, and verify the .excalidraw.md file on disk
// afterward (see "Verifying a Diagram Was Written").
await ea.create({
  filename: "diagram-name",
  foldername: "2. Areas/Excalidraw",
  onNewPane: true,
});
```

### Headless Execution (the default path for an agent)

You do **not** have Templater. Run an EA script from the command line via the
`obsidian` CLI's `eval` command. Obsidian must be running with the vault open
(the plugin exposes `window.ExcalidrawAutomate`).

**Procedure:**

1. **Write the EA script body to a temp file** (not inline — the Obsidian CLI
   arg parser silently fails on `word:` sequences and `[` / `]`, which appear
   in any non-trivial script). Use a normal file write to e.g.
   `${TMPDIR}/ea-diagram.js`. The file contains only the *body* — the code that
   uses `ea` (and optionally `utils`), starting at `ea.reset()`. Do **not**
   include `const ea = ExcalidrawAutomate;` (the wrapper injects `ea`).

2. **Run it through `Obsidian.com eval`** with an async `new Function` wrapper that
   binds `ea` to `window.ExcalidrawAutomate` and awaits the script. Reading the
   script from disk inside the eval avoids all CLI-arg-parser escaping issues:

   ```bash
   Obsidian.com eval code="(async () => {
     const fs = require('fs');
     const body = fs.readFileSync('/abs/path/to/ea-diagram.js', 'utf8');
     const ea = window.ExcalidrawAutomate;
     const utils = this.app ? { app: this.app } : {};
     const fn = new Function('ea', 'utils',
       '\"use strict\"; return (async () => { ' + body + ' })();');
     await fn(ea, utils);
     return 'ea-script-done';
   })()"
   ```

From hamchowderr/braynee, MIT.

More from hamchowderr/braynee