Skip to main content
skill CX Codex

excalidraw-use — Claude Code skill: images onto an Excalidraw board

excalidraw-use lays existing images out on an Excalidraw scene in a grid, shoots Vite/React slides to separate images, and reads a .excalidraw file for broken pictures.

MIT 187 installs ★ 1,540 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add daymade/claude-code-skills --skill excalidraw-use -a claude-code
Open on GitHub

What excalidraw-use does

The skill covers the tedious half of Excalidraw: getting a pile of existing images onto a board so nobody drags them apart afterwards. scripts/build_scene.py takes the file list, column count and an optional template scene, writes a separate .excalidraw file, then prints a verified: line with the element count and a hash check. No verified: line means the output is not worth handing over.

For decks, scripts/shoot_deck.mjs reads src/slides/index.ts from a Vite/React project, captures each slide and confirms fragments actually became visible. --advance picks the paging method: pdf when the deck reads a ?pdf=1 query, keys otherwise. Do not mix them, because under ?pdf=1 extra key presses land on the next slide. puppeteer has to resolve from the directory you run the script in, or it never starts.

scripts/inspect_scene.py reports element counts by type, payload size, whether every image still resolves to matching content, and the occupied extent. Writing into a live board is what to avoid: a scene open in a browser tab does not reload from disk, and the next save overwrites your file. Hand over a separate file and paste through the clipboard; scenes past 15 MB get split with scripts/split_scene.py.

What it helps with

  • lay dozens of screenshots onto a board in an even grid
  • capture every slide of a Vite deck as its own image
  • check a .excalidraw file for images whose payload no longer matches
  • drop duplicates by comparing image content, not filenames
  • split an oversized scene before pasting it through the clipboard

Example prompts for the agent

  • Put these screenshots on an Excalidraw board in a 6-column grid and save it as tray.excalidraw.
  • Shoot every slide of the deck into shots/ and flag any fragment that never revealed.
  • Inspect board.excalidraw: what's in it and are the images still intact?

How to install excalidraw-use

1Skills CLI (Vercel)

npx skills add daymade/claude-code-skills --skill excalidraw-use -a claude-code

2Manually: put the files in place

~/.claude/skills/excalidraw-use/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/excalidraw-use/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about excalidraw-use

How do I install excalidraw-use in Claude Code?

Run npx skills add daymade/claude-code-skills --skill excalidraw-use -a claude-code. The skill lands at ~/.claude/skills/excalidraw-use/SKILL.md.

What does excalidraw-use do?

It builds a .excalidraw scene from existing images, turns deck slides into per-slide images, and inspects a scene file. Diagram generation from prose is out of scope.

What does it need to capture slides?

puppeteer resolvable from the working directory; decks that build their own PDFs usually already have it. npx puppeteer does not install a module an ESM import can find.

Source text

SKILL.md · MIT
---
name: excalidraw-use
description: >-
  Places existing images onto an Excalidraw whiteboard, turns a slide deck into clean per-slide
  images, and inspects a .excalidraw file. Use whenever someone mentions Excalidraw, a
  whiteboard/canvas, .excalidraw, 白板 or 画板 — e.g. "put these screenshots on my board" — or a
  workshop delivered by hand-drawing over screenshots on a shared canvas. Not for generating a
  diagram from a text description.
---

# Excalidraw: images onto a board

Excalidraw is a whiteboard people draw on live. This skill covers the part that
is fiddly to do by hand: getting **a lot of existing images** onto a board,
laid out so nobody has to drag them apart afterwards.

It does **not** generate diagrams from prose. If the request is "draw the
architecture" or "make a flowchart", that is a diagram-generation job — several
tools and skills do it, including a `diagram` skill in the gstack suite if the
user has it installed.

## Which job is this?

| The user says | Go to |
|---|---|
| "put these images on my board", "add the old screenshots to the canvas" | **Job 1 — build a pick tray** |
| "turn the deck into images", "screenshot every slide" | **Job 2 — deck to images**, then Job 1 |
| "what's in this file", "how big is this board", "is anything broken" | **Job 3 — inspect** |
| "draw me a flowchart from this description" | not this skill |

## Job 1 — build a pick tray of images

```bash
python3 scripts/build_scene.py \
  --out tray.excalidraw \
  --cols 6 \
  --template-from ~/path/to/their-board.excalidraw \
  --exclude already-placed.png \
  images/*.png
```

Expected output — if you do not see the `verified:` line, the file is not usable:

```
verified: 30 image element(s), hashes match, no overlap
placed 30 image(s), 6 x 5 grid, min gap 600
wrote tray.excalidraw (3.5 MB)
```

**Hand the user the file plus how to get it onto their board.** That second half
is where this goes wrong: at excalidraw.com, both *Open* and drag-and-drop
**replace the entire current scene**. Telling someone to "open this file" when
they have a live board is telling them to lose it. The additive route is the
clipboard — full instructions and the reasoning in
[references/paste_workflow.md](references/paste_workflow.md). Read it before you
write the hand-off message.

Three decisions worth making deliberately:

- **`--template-from` whenever they have an existing board.** Excalidraw's
  published JSON schema documents the top-level shape and the `files` map, but
  not the image element's own fields (`fileId`, `status`, `scale`, `crop`), so
  copying a live element from *their* board is the only way to be sure the field
  set matches the build they actually run. Without it a reasonable default is
  used, which has worked but is one observed field set, not a spec.
  [references/scene_file_format.md](references/scene_file_format.md) has the
  field-by-field breakdown, keeping what the official docs state separate from
  what was read off a real file — open it when you need to hand-build or repair
  a scene rather than let the script write one.
- **`--exclude` anything already on their board.** The check is by image content,
  not filename, so a renamed copy is still caught. Skipping this is how someone
  ends up with the same picture twice and has to delete one by hand.
- **Spacing.** `--cell` is the longest side each image is scaled to; `--pitch` is
  the distance between cell centres. The gap is `pitch - cell`, and the defaults
  (800 / 1400 → 600) are deliberately generous. If a user has ever said "don't
  make me fix the spacing again", raise `--pitch`, don't lower it.

If the scene is more than ~15 MB, split it — the clipboard is where a large
scene stalls:

```bash
python3 scripts/split_scene.py --scene tray.excalidraw --out-dir parts/ --chunks 4
```

## Job 2 — turn a slide deck into clean images

For Vite/React decks whose slides are registered in a `src/slides/index.ts` with
entries shaped `{ id: 'intro', component: S01, fragmentCount: 3 }`.

```bash
# 1. Build the deck FROM SOURCE and serve that build (not a dev server).
cd <deck>; npx vite build --outDir /tmp/deck-dist --emptyOutDir
cd /tmp/deck-dist && python3 -m http.server 8080 &

# 2. Shoot it.
node scripts/shoot_deck.mjs \
  --index <deck>/src/slides/index.ts \
  --url http://127.0.0.1:8080/index.html \
  --out shots/ \
  --advance pdf     # or: keys
```

Expected output:

```
30 slides (7 with fragments), advance=pdf
30/30 captured, 32 inline chrome element(s) hidden -> shots/
all .fragment elements rendered visible (opacity check)
```

That last line is the one that matters. If instead you see
`WARNING: N slide(s) have fragments that never revealed`, those screenshots are
missing content — **do not** feed them into Job 1. Read
[references/deck_screenshot_pitfalls.md](references/deck_screenshot_pitfalls.md);
the usual cause is that the build being served is older than the source.

**`puppeteer` must be resolvable from wherever you run the script.** Decks that
generate their own PDFs usually already have it — run the script from that
project, or symlink its `node_modules` next to the script. `npx puppeteer` does
not install a resolvable module for an ESM import.

**Picking `--advance`:** grep the deck's `Deck` component for `pdf`. If it reads
a `?pdf=1` query, use `pdf`; otherwise `keys`. Never both — under `?pdf=1` the
fragment index is already at maximum, so extra key presses move to the *next*
slide and you silently capture the wrong content.

Add `--strict` to make unrevealed fragments a non-zero exit when this runs
inside a pipeline. It stays a warning by default so a deck that legitimately
keeps a `.fragment` hidden does not fail the whole run.

## Job 3 — inspect a scene

```bash
python3 scripts/inspect_scene.py board.excalidraw --images
```

Reports element counts by type, embedded payload size, whether every image
element resolves to a file whose content still matches its key, and the occupied
extent. Read-only.

The **extent** is the practically useful number: pasted content lands wherever
the viewport is, so knowing where existing work sits is how you tell the user
where to scroll before pasting.

## Never write into their live board file

Build a separate scene file and let the user paste from it. Two independent
reasons, both observed:

- A board that is open in a browser tab does not reload when the file on disk
  changes, and the next in-app save overwrites whatever you wrote.
- The file on disk is usually **older than the browser's state** — someone
  exported it days ago and has been working in the tab since. Merging into that
  export silently drops everything they have done since.

If a merged file is genuinely wanted, write it to a **new path** and let the user
choose which to open. Never overwrite the original.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| Scene opens but a picture is blank | `files` entry missing or its key does not match the payload | `inspect_scene.py` reports both; rebuild |
| Images touch or overlap on the board | `--pitch` not greater than `--cell` | the script refuses this combination; raise `--pitch` |
| Paste does nothing / takes forever | scene too large for the clipboard | `split_scene.py`, then paste each part |
| Pasting replaced the whole board | *Open* / drag-and-drop was used instead of copy-paste | see references/paste_workflow.md; recover with in-app undo |
| Slides captured missing their later content | fragments never revealed | rebuild the deck from source, re-serve, re-shoot |
| Key-press badges appear in slide screenshots | the wait for them to fade was cut short | the script already waits ~2.9 s after the last press; if a deck lingers longer, raise it |
| `Cannot find package 'puppeteer'` | not resolvable from the script's location | run from a project that has it |
| Image drawn at the wrong shape | element aspect ratio does not match the source | `build_scene.py` fails on this rather than writing it |

## Next step

After a tray is built, the natural follow-up is the paste itself, which only the
user can do. Give them the file path, the scroll-to-empty-space warning, and the
three-key sequence — then stop. Do not open excalidraw.com to "verify" the file:
loading a scene there replaces whatever is in that browser's current session,
which may be the board you were trying to protect.

© daymade · MIT · daymade/claude-code-skills

Similar skills

All skills for Design →

From the same set102

The whole set →
continue-claude-code-work continue-claude-code-work restores interrupted Claude Code work from session history, identifies unfinished requests, and selects the next verified action. CX Codex +1 216installs interaction-design-board The interaction-design-board skill builds several clickable HTML prototypes of one interface into a Design Board where you pick a variant or request a remix before the agent touches production code. CX Codex +1 213installs codex-1m-context-window-setup codex-1m-context-window-setup inspects Codex context settings, adjusts auto-compaction, and applies a model-aware expansion toward 500K or 1M when supported. CX Codex +1 211installs lark-cli-router lark-cli-router routes Feishu, Lark, and Doubao tasks to version-matched guides in lark-cli. Helps agents manage docs, calendar entries, and chat tasks safely. CX Codex +1 210installs meme-creator The meme-creator skill tracks moving objects in a clip and places logos, avatars, or stickers over them, then exports MP4 and GIF files. Use it to make a reaction meme from footage. CX Codex +1 174installs agent-web-search-setup agent-web-search-setup — a skill for Claude Code and other platforms diagnoses and fixes web search when proxies return empty responses. CX Codex +1 162installs macos-permissions macos-permissions is a Claude Code skill that diagnoses TCC denials, Local Network alerts, and stuck Keychain prompts. Fixes broken grants in background LaunchAgents. CX Codex +1 152installs tech-selection tech-selection — a skill for Claude Code helps choose or reassess a library, framework, storage option, or architecture. It runs before a technical choice is finalized. CX Codex +1 151installs

Project sponsors

Companies that keep this analytics open