Tldraw
Deterministic read/write for tldraw canvases. The .tldr format is plain JSON ({tldrawFileFormatVersion: 1, schema, records}); Tools/Tldr.ts writes records that pass tldraw's own validator, so generated files open cleanly in the tldraw web editor, the VS Code tldraw extension, or the desktop app. Two directions: model → canvas (sketch diagrams) and canvas → model (read and structure a human's rough thinking).
Customization
Before executing, check for user customizations at:
~/.claude/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/Tldraw/
If this directory exists, load and apply any PREFERENCES.md found there (default canvas directory, preferred colors/register, default open surface). If not, proceed with defaults.
Voice Notification
When executing a workflow, do BOTH:
Send voice notification:
curl -s -X POST http://localhost:31337/notify \
-H "Content-Type: application/json" \
-d '{"message": "Running WORKFLOWNAME in Tldraw"}' \
> /dev/null 2>&1 &
Output text notification:
Running **WorkflowName** in **Tldraw**...
Workflow Routing
| Workflow |
Trigger |
File |
| SketchDiagram |
"sketch a diagram", "draw this on a canvas", "tldraw diagram" |
Workflows/SketchDiagram.md |
| StructureCanvas |
"structure my canvas", "organize my whiteboard", "read my canvas" |
Workflows/StructureCanvas.md |
Quick Reference
- Tool:
bun ~/.claude/skills/Tldraw/Tools/Tldr.ts <create|inspect|add|remove|move|settext|validate> <file.tldr> [flags]
- Record shapes, spec format, coordinate conventions:
References/TldrFormat.md
- Vendored schema (tldraw 5.2.5):
References/SchemaSnapshot.json
Examples
Example 1: Diagram for a post
User: "Sketch the three-stage pipeline as a hand-drawn diagram"
→ Invokes SketchDiagram workflow
→ Writes spec JSON, runs Tldr.ts create + add, validates
→ Returns the .tldr path and how to open it; user nudges shapes and exports
Example 2: Organize an ideation canvas
User: "I dumped ideas on my canvas — structure them"
→ Invokes StructureCanvas workflow
→ Tldr.ts inspect --json reads every shape's text and position
→ Clusters related items, adds frames + arrows, moves shapes into groups
→ User reopens the same file and sees the organized version
Gotchas
- zsh
echo mangles spec JSON — it expands \n inside strings into real newlines, breaking JSON. Write the spec to a file (or use printf '%s') and pass --spec <file>; the tool also accepts --spec - on stdin, but only feed it from something that doesn't reinterpret escapes.
- Text is
richText, never a plain string — labels on geo/text/note/arrow shapes are ProseMirror doc JSON ({"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"..."}]}]}). A bare string prop is rejected by tldraw's validator. Tldr.ts builds this for you; never hand-write a text prop.
- Arrow bindings require
terminal: "start"|"end" — tldraw's own ArrowBindingUtil.getDefaultProps() omits it, but the schema validator rejects a binding without it (verified against tldraw 5.2.5). The tool sets it; if you hand-edit bindings, keep it.
- Raw records need every prop — records written to the file bypass editor defaulting, so a missing prop (e.g.
growY on geo) fails validation on load. Always go through Tldr.ts add; don't append hand-rolled records.
- Fractional index strings order shapes —
index values (a1, a2, …) are base62 lexicographic and must never end in 0. The tool generates them; duplicates cause z-order glitches in the editor.
- The desktop-app
.tldraw format is a different thing — the tldraw desktop app's native save is a zip (sqlite + assets + scripts), not this JSON. This skill targets portable .tldr JSON, which the web editor, the VS Code extension, and the desktop app can all open/import.
- Editors hold files in memory — if the user has the canvas open while you edit it on disk, their surface may not reload (or may overwrite your change on save). Edit while closed, or tell the user to reopen after your write.
Opening a canvas
- VS Code / Cursor: the official tldraw extension opens
.tldr files in-editor — fully local, right choice for private content.
- tldraw.com: File → Open. Content goes to a third-party web app — only for content already public-destined.
- Export to image: from any tldraw surface, select all → Export as SVG/PNG. (No headless export path ships with this skill.)
Execution Log
After completing any workflow, append a single JSONL entry:
echo '{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","skill":"Tldraw","workflow":"WORKFLOW_USED","input":"8_WORD_SUMMARY","status":"ok|error","duration_s":SECONDS}' >> ~/.claude/LIFEOS/MEMORY/SKILLS/execution.jsonl
1---2name: tldraw3description: Read, create, and edit tldraw .tldr canvas files deterministically — sketch hand-drawn-register diagrams (boxes, arrows, sticky notes, frames, text) directly into a canvas file the user opens in any tldraw surface, and read a rough canvas back as structured data to organize it. USE WHEN tldraw, .tldr file, whiteboard, canvas, sketch a diagram, hand-drawn diagram, draw this on a canvas, put this on the whiteboard, structure my canvas, organize my whiteboard, read my canvas, cluster my sticky notes. NOT FOR polished static images, infographics, or mermaid diagrams (use Art), web UI design (use Webdesign), programmatic video (use Remotion).4---5
6# Tldraw
7
8Deterministic read/write for tldraw canvases. The `.tldr` format is plain JSON (`{tldrawFileFormatVersion: 1, schema, records}`); `Tools/Tldr.ts` writes records that pass tldraw's own validator, so generated files open cleanly in the tldraw web editor, the VS Code tldraw extension, or the desktop app. Two directions: model → canvas (sketch diagrams) and canvas → model (read and structure a human's rough thinking).
9
10## Customization
11
12**Before executing, check for user customizations at:**
13`~/.claude/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/Tldraw/`
14
15If this directory exists, load and apply any PREFERENCES.md found there (default canvas directory, preferred colors/register, default open surface). If not, proceed with defaults.
16
17## Voice Notification
18
19**When executing a workflow, do BOTH:**
20
211. **Send voice notification**:
22 ```bash
23 curl -s -X POST http://localhost:31337/notify \
24 -H "Content-Type: application/json" \
25 -d '{"message": "Running WORKFLOWNAME in Tldraw"}' \
26 > /dev/null 2>&1 &
27 ```
28
292. **Output text notification**:
30 ```
31 Running **WorkflowName** in **Tldraw**...
32 ```
33
34## Workflow Routing
35
36| Workflow | Trigger | File |
37|----------|---------|------|
38| **SketchDiagram** | "sketch a diagram", "draw this on a canvas", "tldraw diagram" | `Workflows/SketchDiagram.md` |
39| **StructureCanvas** | "structure my canvas", "organize my whiteboard", "read my canvas" | `Workflows/StructureCanvas.md` |
40
41## Quick Reference
42
43- Tool: `bun ~/.claude/skills/Tldraw/Tools/Tldr.ts <create|inspect|add|remove|move|settext|validate> <file.tldr> [flags]`
44- Record shapes, spec format, coordinate conventions: `References/TldrFormat.md`
45- Vendored schema (tldraw 5.2.5): `References/SchemaSnapshot.json`
46
47## Examples
48
49**Example 1: Diagram for a post**
50```
51User: "Sketch the three-stage pipeline as a hand-drawn diagram"
52→ Invokes SketchDiagram workflow
53→ Writes spec JSON, runs Tldr.ts create + add, validates
54→ Returns the .tldr path and how to open it; user nudges shapes and exports
55```
56
57**Example 2: Organize an ideation canvas**
58```
59User: "I dumped ideas on my canvas — structure them"
60→ Invokes StructureCanvas workflow
61→ Tldr.ts inspect --json reads every shape's text and position
62→ Clusters related items, adds frames + arrows, moves shapes into groups
63→ User reopens the same file and sees the organized version
64```
65
66## Gotchas
67
68- **zsh `echo` mangles spec JSON** — it expands `\n` inside strings into real newlines, breaking JSON. Write the spec to a file (or use `printf '%s'`) and pass `--spec <file>`; the tool also accepts `--spec -` on stdin, but only feed it from something that doesn't reinterpret escapes.
69- **Text is `richText`, never a plain string** — labels on geo/text/note/arrow shapes are ProseMirror doc JSON (`{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"..."}]}]}`). A bare string prop is rejected by tldraw's validator. `Tldr.ts` builds this for you; never hand-write a `text` prop.
70- **Arrow bindings require `terminal: "start"|"end"`** — tldraw's own `ArrowBindingUtil.getDefaultProps()` omits it, but the schema validator rejects a binding without it (verified against tldraw 5.2.5). The tool sets it; if you hand-edit bindings, keep it.
71- **Raw records need every prop** — records written to the file bypass editor defaulting, so a missing prop (e.g. `growY` on geo) fails validation on load. Always go through `Tldr.ts add`; don't append hand-rolled records.
72- **Fractional index strings order shapes** — `index` values (`a1`, `a2`, …) are base62 lexicographic and must never end in `0`. The tool generates them; duplicates cause z-order glitches in the editor.
73- **The desktop-app `.tldraw` format is a different thing** — the tldraw desktop app's native save is a zip (sqlite + assets + scripts), not this JSON. This skill targets portable `.tldr` JSON, which the web editor, the VS Code extension, and the desktop app can all open/import.
74- **Editors hold files in memory** — if the user has the canvas open while you edit it on disk, their surface may not reload (or may overwrite your change on save). Edit while closed, or tell the user to reopen after your write.
75
76## Opening a canvas
77
78- **VS Code / Cursor**: the official tldraw extension opens `.tldr` files in-editor — fully local, right choice for private content.
79- **tldraw.com**: File → Open. Content goes to a third-party web app — only for content already public-destined.
80- **Export to image**: from any tldraw surface, select all → Export as SVG/PNG. (No headless export path ships with this skill.)
81
82## Execution Log
83
84After completing any workflow, append a single JSONL entry:
85
86```bash
87echo '{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","skill":"Tldraw","workflow":"WORKFLOW_USED","input":"8_WORD_SUMMARY","status":"ok|error","duration_s":SECONDS}' >> ~/.claude/LIFEOS/MEMORY/SKILLS/execution.jsonl
88```
danielmiessler