Whiteboard tldraw diagrams (.tldr) from natural language with 6 presets and vision-based self-check. PNG/SVG export, multi-agent.

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.

Microservices Architecture — generated from a single natural-language prompt

✨ 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 10-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.

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

Check deps — verifies tldraw --version; offers npm install -g @kitschpatrol/tldraw-cli if missing.
Plan layout — picks geo shapes, assigns node positions on a 10px grid, spaces according to node count.
Generate .tldr JSON — writes shape + arrow records with bound anchors and distributed normalizedAnchor points.
Export draft PNG — tldraw export diagram.tldr -f png --scale 2 -o ./.
Self-check — vision-enabled model reads the PNG, auto-fixes overlaps / clipped labels / arrow crossings (max 2 rounds). Skipped if vision isn’t available.
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.
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	✅ 10-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

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