skills/tldraw-file/SKILL.md

name, description, argument-hint, user-invocable

name	description	argument-hint	user-invocable
tldraw-file	Create, repair, validate, or generate valid `.tldr` files that tldraw can open. Use when the user asks for a tldraw diagram, `.tldr` file, corrupted tldraw repair, or a diagram they can open in tldraw.	[diagram request, file path, or validation target]	true

tldraw File

Use when creating, repairing, validating, or generating a .tldr file.

Core Rule

Do not hand-wave validity. A .tldr file must validate through tldraw's own schema/importer, not just JSON.parse. Valid JSON can still be corrupted to tldraw.

Temporary Setup

If the current project does not already depend on tldraw, install it in /tmp/opencode, not in the user's repo:

bun init -y
bun add tldraw

Run validation scripts from the directory where tldraw is installed.

File Shape

A .tldr file has top-level tldrawFileFormatVersion, schema, and records. Records must be an array of valid tldraw records. Include at least a document record and a page record, then shapes parented to that page.

Use geo rectangles for most boxes, text shapes for headings, and simple arrows for flow. Avoid note shapes unless you know the current schema.

See record templates for base records and shape JSON.

Validation Workflow

1. Create or update .tldr with apply_patch.
2. Validate JSON syntax.
3. Validate records with createTLStore({ snapshot }).
4. Validate importer compatibility with parseTldrawJsonFile.
5. If tldraw says corrupted, trust tldraw and fix the specific schema path.

bun -e "const f='/path/to/file.tldr'; const data=await Bun.file(f).text(); JSON.parse(data); console.log('valid json')"

bun -e "import { createTLStore } from 'tldraw'; const file=JSON.parse(await Bun.file('/path/to/file.tldr').text()); const snapshot={store:Object.fromEntries(file.records.map(r=>[r.id,r])), schema:file.schema}; try { const store=createTLStore({snapshot}); console.log('ok records', store.allRecords().length); } catch(e){ console.error(e); process.exit(1)} process.exit(0)"

bun -e "import { createTLStore } from 'tldraw'; import { parseTldrawJsonFile } from './node_modules/tldraw/dist-esm/lib/utils/tldr/file.mjs'; const json=await Bun.file('/path/to/file.tldr').text(); const schema=createTLStore().schema; const result=parseTldrawJsonFile({json, schema}); console.log(result.ok ? 'parse ok' : result.error); process.exit(result.ok ? 0 : 1)"

Common Corruption Causes

• File is valid JSON but does not match tldraw schema.
• Missing labelColor on arrow shapes.
• Missing required shape props, especially on note shapes.
• Old schema sequence numbers copied from another tldraw version.
• Invalid color names.
• Shape parentId points to a missing page.
• Duplicate record IDs.
• Records object used instead of records array.
• richText missing where current schemas expect it.

See schema notes for current sequence shape and valid colors.

Practical Diagram Advice

• Keep diagrams editable rather than pixel-perfect.
• Use stable readable IDs, for example shape:admin-review.
• Use indexed records like a1, a2, a3.
• Keep labels in both richText and legacy text props for compatibility.
• Prefer simple layout and reliable schemas over fancy shapes.