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 — diamond decisions, auto Yes/No labels, dashed retry loop	Sequence — dotted lifelines, solid calls vs. dashed returns
ML / Transformer — tensor-shape labels, residual skip-connections	ERD — PK * / FK > markers, cardinality on relationships

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

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

🔄 How it works

_{This diagram was drawn by the skill itself — see assets/workflow.tldr.}

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)

🎯 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:

💬 Community

• Discord: https://discord.gg/79JF5Atuk
• WeChat: scan the QR code below

❤️ Support

If this skill helps you, consider supporting the author:

WeChat Pay

Alipay

Buy Me a Coffee

Give a Reward

👤 Author

Agents365-ai

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

📄 License

MIT