A Claude Code skill that generates VS Code-compatible tldraw (.tldr) architecture diagrams from JSON.

When you work on a project inside Claude Code for a long time, it's easy to lose track of the overall architecture and workflow. This skill lets you instantly visualize your project structure as an interactive diagram — right inside VS Code, for free, with zero setup.

Just describe your architecture as simple JSON (nodes + edges), and the skill generates a .tldr file that opens natively in VS Code via the tldraw extension. No external tools, no browser tabs, no paid services.

Example diagram rendered in VS Code tldraw:

Install the tldraw extension to view .tldr files directly in VS Code:

code --install-extension tldraw-org.tldraw-vscode

Or manually: Extensions (Ctrl+Shift+X) → search "tldraw" → Install tldraw by tldraw

Without this extension, .tldr files will open as raw JSON.

The generator script uses only built-in Node.js modules (fs, path) — zero npm dependencies.

Claude Code discovers skills from ~/.claude/skills/. Copy SKILL.md and the bootstrap dependencies:

git clone https://github.com/MOZARTINOS/claude-code-skill-tldraw-diagram.git
mkdir -p ~/.claude/skills/tldraw-json-to-tldr
cp claude-code-skill-tldraw-diagram/SKILL.md ~/.claude/skills/tldraw-json-to-tldr/
cp -r claude-code-skill-tldraw-diagram/scripts ~/.claude/skills/tldraw-json-to-tldr/
cp -r claude-code-skill-tldraw-diagram/assets ~/.claude/skills/tldraw-json-to-tldr/
cp -r claude-code-skill-tldraw-diagram/examples ~/.claude/skills/tldraw-json-to-tldr/

Copy the scripts/ directory into your project so Claude can find and run it:

cp -r claude-code-skill-tldraw-diagram/scripts your-project/scripts

Or keep the entire repo as a subdirectory:

cp -r claude-code-skill-tldraw-diagram your-project/skills/tldraw-json-to-tldr

git clone https://github.com/MOZARTINOS/claude-code-skill-tldraw-diagram.git
cd claude-code-skill-tldraw-diagram
node scripts/gen-tldr.mjs --in examples/diagram.json --out examples/diagram.tldr

Use this when opening a new or old project where diagram generation is not configured yet:

# From this skill repository:
node scripts/bootstrap-project.mjs --target /path/to/your-project

# If the skill is already inside your project:
node skills/tldraw-json-to-tldr/scripts/bootstrap-project.mjs --target .

# If the skill is installed globally:
# Bash/Zsh:
node "$HOME/.claude/skills/tldraw-json-to-tldr/scripts/bootstrap-project.mjs" --target /path/to/your-project
# PowerShell:
node "$env:USERPROFILE/.claude/skills/tldraw-json-to-tldr/scripts/bootstrap-project.mjs" --target .

Bootstrap will:

• install/update scripts/gen-tldr.mjs
• create .diagrams/ files if missing
• add VS Code tasks and extension recommendation
• generate and validate .diagrams/smoke-test.tldr and .diagrams/diagram.tldr

Use this when you still get a blank tldraw canvas in a specific project:

# PowerShell
node "$env:USERPROFILE/.claude/skills/tldraw-json-to-tldr/scripts/doctor-vscode-tldraw.mjs" --target . --reset-workspace-cache

# Bash/Zsh
node "$HOME/.claude/skills/tldraw-json-to-tldr/scripts/doctor-vscode-tldraw.mjs" --target . --reset-workspace-cache

If needed, run hard reset:

node "$env:USERPROFILE/.claude/skills/tldraw-json-to-tldr/scripts/doctor-vscode-tldraw.mjs" --target . --hard-reset-workspace

Create a JSON file with this structure:

{
  "title": "My Architecture",
  "nodes": [
    { "id": "client", "label": "Browser Client", "group": "Frontend" },
    { "id": "api", "label": "API Server", "group": "Backend" },
    { "id": "db", "label": "PostgreSQL", "group": "Data" }
  ],
  "edges": [
    { "from": "client", "to": "api", "label": "REST" },
    { "from": "api", "to": "db", "label": "SQL" }
  ]
}

node scripts/gen-tldr.mjs --in path/to/diagram.json --out path/to/output.tldr

node scripts/gen-tldr.mjs --smoke --out smoke-test.tldr

The smoke test creates a minimal .tldr with a single "SMOKE TEST" box. Use this to verify that the tldraw extension is working before debugging your diagram.

# Uses .diagrams/diagram.json -> .diagrams/diagram.tldr
node scripts/gen-tldr.mjs

node scripts/gen-tldr.mjs --help

The tldraw VS Code extension expects .tldr files to follow a strict internal schema. Files generated with incorrect schema versions, missing migration sequences, or legacy property names (like props.text instead of props.richText) result in a blank canvas with no visible error.

This skill produces .tldr files that render correctly every time by enforcing:

1. Correct schema — tldrawFileFormatVersion: 1, schemaVersion: 2, and all required com.tldraw.* migration sequences
2. Required base records — document:document, page:page, camera:page:page
3. Modern shape properties — props.richText (ProseMirror format) instead of the deprecated props.text
4. Valid prop sets — only properties that pass tldraw's schema validation for geo, arrow, and text shapes

Nodes are arranged in columns by group. Each group gets a header label. Arrows connect node centers.

See references/tldraw-compat.md for the full schema contract, including:

• Required top-level fields
• Required base records
• Shape property specifications for geo, arrow, and text types
• Common blank-canvas causes and recovery steps

claude-code claude-code-skill tldraw tldr vscode architecture-diagram diagram-generator json-to-diagram code-visualization project-workflow

MIT