tldraw-skill — From Text to Whiteboard Diagrams

English · 中文 · 📖 Online Docs

A skill that turns natural-language descriptions into hand-drawn-style .tldr whiteboard diagrams and exports them to PNG / SVG via @kitschpatrol/tldraw-cli. Works with Claude Code, Cursor, Copilot, OpenClaw, Codex, Hermes, and any agent compatible with the Agent Skills format.

✨ Highlights

• 6 diagram type presets — Architecture, Flowchart, Sequence, ML/Deep Learning, ERD, UML
• Vision-based self-check + auto-fix — reads its own PNG output and auto-fixes overlaps, clipped labels, missing arrows, off-canvas shapes, and stacked edges (up to 2 rounds; requires a vision-enabled model)
• Iterative review loop — targeted JSON edits, up to 5 rounds, then suggests opening in tldraw.com for fine-tuning
• Complexity-scaled layout — spacing (200 / 280 / 350px) grows with node count; routing corridors and hub placement built in
• Semantic 13-color palette — blue services, green databases, violet auth, orange queues, yellow decisions, etc. — consistent across runs
• Zero browser automation — tldraw-cli runs anywhere Node runs; identical setup on macOS, Linux, Windows (no Chromium, no Playwright)

🖼️ Examples

[!TIP] The hero image above was generated from this single prompt:

Create a microservices e-commerce architecture with Mobile/Web/Admin clients,
API Gateway, User/Order/Product/Payment services, Kafka event bus, Notification
service, and User DB / Order DB / Product DB / Redis Cache / Stripe API

The skill plans shape positions on a 10px grid, distributes arrow endpoints around each node's perimeter, and re-checks the exported PNG to catch overlaps before showing you the result.

More diagram styles

Each of these was generated from a single natural-language prompt and exported through the same self-check pipeline:

• Flowchart: Draw a login flowchart: Start → Enter Credentials → decision "Valid?"; Yes → Load Dashboard → Success; No → Show Error, then loop back to Enter Credentials.
• Sequence: Sequence diagram for a login API: Client → API → Auth → DB, with POST /login, validate, query user, and dashed return messages (user row, 200 OK, session).
• ML / Transformer: Sketch a Transformer encoder block: input embedding [B,512,768], positional encoding, multi-head attention, add & norm, feed forward [768→3072→768], add & norm, encoder output — with residual skip-connections.
• ERD: E-commerce ERD with User, Order, Product, OrderItem entities; mark PK with * and FK with >; show 1:N relationships places / contains / in.

It's a whiteboard — it can sketch, too

tldraw isn't only boxes and arrows. Because it's a hand-drawn whiteboard with a freehand draw shape, the skill can also draw figuratively — geo primitives (ellipse / triangle / heart) plus freehand strokes, or pure freehand curves generated from parametric equations:

Cat / dog — geo primitives + freehand whiskers and tails. Spiral / flower / butterfly / tree — pure freehand draw strokes generated from parametric curves (the butterfly is a single 1,400-point stroke). Not what the skill is for — it's a diagram tool — but a fun demonstration of the freehand draw shape and the hand-drawn aesthetic. Sources under assets/ (example-cat/dog/spiral/flower/butterfly/tree.tldr).

Full feature breakdown in docs/features.md. Known limitations (strict UML notation, PDF export, vision requirement) in docs/limitations.md.

🚀 Installation

1. Install @kitschpatrol/tldraw-cli

Platform	Command
macOS / Linux / Windows	npm install -g @kitschpatrol/tldraw-cli

Verify with tldraw --version. Requires Node.js (npm). No browser automation, no Playwright — tldraw-cli runs identically everywhere Node runs.

2. Install the skill

# Any agent (Claude Code, Cursor, Copilot, ...)
npx skills add Agents365-ai/365-skills -g

# Claude Code plugin marketplace
> /plugin marketplace add Agents365-ai/365-skills
> /plugin install tldraw

# Manual install
git clone https://github.com/Agents365-ai/tldraw-skill.git \
  ~/.claude/skills/tldraw-skill

Also indexed on SkillsMP and ClawHub.

Updating: /plugin update tldraw (Claude Code), skills update tldraw-skill (SkillsMP), clawhub update tldraw-pro-skill (OpenClaw), or git pull for manual installs.

⚡ Quick Start

After installation, just describe what you want. For example, an ML model sketch:

Sketch a Transformer encoder-decoder on a whiteboard: 6-layer encoder with
self-attention, 6-layer decoder with cross-attention, input embeddings
(batch × 512 × 768), positional encoding, and a final output projection.
Annotate tensor shapes between layers and color-code by layer type.

The skill plans the layout, generates the .tldr JSON, exports to PNG/SVG, self-checks the result, and lets you iterate.

🧩 Supported Diagram Types

Category	Examples	Notable features
Architecture	microservices, cloud, network topology, deployment	Hub-center pattern for event buses; tier rows; cloud/hexagon/triangle shape vocabulary
Flowcharts	business processes, workflows, decision trees	ellipse start/end, diamond decisions; auto-labels Yes/No branches
Sequence diagrams	API call flows, request/response, async messages	Lifeline approximation (thin grey rectangles); dashed arrows for async / return
ML / Deep Learning	Transformer, CNN, LSTM, GRU	Tensor shape annotations in node labels; layer-type color coding; skip-connection bends
ERD	entity relationships, schemas	Multi-line entity labels (PK * / FK >); cardinality on arrow labels
UML Class	high-level class diagrams	Multi-line class labels (attributes + methods); inheritance / association arrows (see limitations for strict UML notation)

🔄 How it works

1. Check deps — verifies tldraw --version; offers npm install -g @kitschpatrol/tldraw-cli if missing.
2. Plan layout — picks geo shapes, assigns node positions on a 10px grid, spaces according to node count.
3. Generate .tldr JSON — writes shape + arrow records with bound anchors and distributed normalizedAnchor points.
4. Export draft PNG — tldraw export diagram.tldr -f png --scale 2 -o ./.
5. Self-check — vision-enabled model reads the PNG, auto-fixes overlaps / clipped labels / arrow crossings (max 2 rounds). Skipped if vision isn't available.
6. Review loop — shows the image, applies your targeted edits (color, label, add/remove node, move shape), re-exports — up to 5 rounds before suggesting tldraw.com for hand-tuning.
7. Final export — re-exports the approved version to all requested formats and reports file paths.

🆚 Comparison

vs Native Agent (no skill)

Feature	Native agent	tldraw-skill
Self-check after export	❌	✅ vision-based, 2-round auto-fix
Iterative review loop	❌ manual re-prompt	✅ targeted JSON edits, 5-round safety valve
Diagram type presets	❌	✅ 6 presets (Arch, Flow, Seq, ML, ERD, UML)
Complexity-scaled spacing	❌	✅ 200 / 280 / 350px tiers by node count
Color palette	random / inconsistent	✅ 13-color semantic system
Arrow distribution on shape	random anchors → stacked	✅ even spacing around perimeter
Grid alignment	❌	✅ 10px snap matches tldraw default
Multi-line tensor / column labels	ad-hoc	✅ embedded \n formatting baked in

🎯 When to use (and when not to)

Good fit:

• Whiteboard / hand-drawn-style diagrams — architecture, flowcharts, sequence, ERD, UML sketches, mind maps
• A casual, sketchy aesthetic; freehand strokes and figurative doodles (the draw shape)
• Quick visual explainers where a polished, pixel-precise look isn't the goal

Reach for a sibling skill instead when you need:

• Logos, solid-color graphics, or filled icons — tldraw has no opaque fill (solid renders as a light tint, so white-on-dark artwork can't be reproduced) → drawio-skill or your original vector source
• Precise angular geometry / strict vector shapes → drawio-skill
• Strict, publication-grade UML (hollow inheritance arrows, etc.) → plantuml-skill or drawio-skill
• Automatic layout of many nodes (tldraw needs manual coordinates) → mermaid-skill
• Pixel-faithful reproduction of an existing image — not what any diagram skill is for

🔗 Related Skills

Part of the Agents365-ai diagram-skill family — pick the right tool for the job:

Skill	Style	Best for
drawio-skill	Polished business diagrams	Stakeholder decks, strict UML, ML papers, network topologies
excalidraw-skill	Hand-drawn / sketchy	Whiteboard mockups, informal diagrams
mermaid-skill	Text-based, auto-layout	README-embeddable, version-control friendly
plantuml-skill	UML-focused	Class / sequence diagrams in CI pipelines

❤️ Support

If this skill helps you, consider supporting the author:

👤 Author

Agents365-ai

• GitHub: https://github.com/Agents365-ai
• Bilibili: https://space.bilibili.com/441831884

📄 License

MIT