drawio-skill — From Text to Professional Diagrams

English · 中文 · 📖 Online Docs

A skill that turns natural-language descriptions into .drawio XML and exports them to PNG / SVG / PDF / JPG via the native draw.io desktop CLI. It can also turn an existing codebase (Python / JS-TS / Go / Rust) into an auto-laid-out structure diagram. Works with Claude Code, Cursor, Copilot, OpenClaw, Codex, Hermes, and any agent compatible with the Agent Skills format.

✨ Highlights

• 6 diagram type presets — ERD, UML Class, Sequence, Architecture, ML/Deep Learning, Flowchart
• Visualize a codebase — extract and auto-lay-out the structure of a Python / JS-TS / Go / Rust project (import graphs) or a Python class hierarchy — Graphviz placement, transitive reduction, nested module containers
• Search 10,000+ official shapes — resolve the exact AWS / Azure / GCP / Cisco / Kubernetes / UML / BPMN icon style instead of guessing (no more blank-box shape=mxgraph.* typos)
• AI / LLM brand logos — 321 logos (OpenAI, Claude, Gemini, Mistral, Llama, Ollama, LangChain…) that draw.io has none of, for LLM-app architecture diagrams
• Self-check + auto-fix — reads its own PNG output and auto-fixes overlaps, clipped labels, stacked edges, and more (up to 2 rounds)
• Iterative feedback loop — up to 5 rounds of targeted refinement
• Style presets — capture your visual style from a .drawio file or image, reuse on demand
• Clean layout — grid-aligned, spacing scales with diagram size, connectors routed clear of nodes
• Multi-agent, zero-config — runs from a single SKILL.md; no MCP server, no background daemon (the optional npx installer needs Node, the skill itself does not)

🖼️ 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 (auth + rate limiting + routing), Auth/User/Order/Product/Payment
services, Kafka message queue, Notification service, and User DB / Order DB /
Product DB / Redis Cache / Stripe API

The skill is designed to route edges cleanly across different topologies, avoiding lines that cross through shapes:

Star · 7 nodes Central message broker with 6 microservices radiating outward, no edge crossings on this example.

Layered · 10 nodes / 4 tiers E-commerce stack with horizontal and diagonal cross-connections routed via corridors.

Ring · 8 nodes CI/CD pipeline with a closed loop and 2 spur branches flowing along the perimeter.

Full walkthrough in docs/USAGE.md.

🚀 Installation

1. Install the draw.io desktop CLI

Verify with drawio --version. On WSL2 the CLI is the Windows desktop exe reached via /mnt/c — the skill detects this automatically (see troubleshooting). Full recipes in docs/INSTALL_CLI.md.

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 drawio

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

Also indexed on SkillsMP and ClawHub.

Updating: /plugin update drawio (Claude Code), skills update drawio-skill (SkillsMP), clawhub update drawio-pro-skill (OpenClaw), or git pull for manual installs — see docs/INSTALL_SKILL.md#updates. Release history in CHANGELOG.md.

⚡ Quick Start

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

Draw a Transformer encoder-decoder for machine translation: 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 .drawio XML, exports to your chosen format, self-checks the result, and lets you iterate.

🗺️ Visualize a Codebase

Beyond hand-authored diagrams, the skill turns existing code into structure diagrams — no manual coordinates. Just ask:

"Visualize the module structure of this Python project" · "Draw the class hierarchy of mypackage"

_{↑ Python's logging package as a class hierarchy — one command, modules auto-boxed, every inheritance edge resolved.}

Under the hood it runs a bundled extractor → auto-layout → validate pipeline:

# Import graph — Python / JS-TS / Go / Rust
python3 scripts/pyimports.py   myproject --group -o graph.json
python3 scripts/jsimports.py   ./src     --group -o graph.json
python3 scripts/goimports.py   ./module  --group -o graph.json
python3 scripts/rustimports.py ./crate   --group -o graph.json

# Python class-inheritance hierarchy
python3 scripts/pyclasses.py   mypackage --group -o graph.json

# any extractor → auto-layout → editable .drawio
python3 scripts/autolayout.py  graph.json -o diagram.drawio

Layout needs Graphviz (brew install graphviz / apt install graphviz) — optional; everything else works without it. Full format + flag reference in references/autolayout.md.

🧩 Supported Diagram Types

🔍 Shape Search

Need a real AWS / Azure / GCP / Cisco / Kubernetes / UML / BPMN icon? The skill searches 10,000+ official draw.io shapes for the exact style string — so vendor icons render correctly instead of falling back to a blank box from a guessed shape=mxgraph.* name.

"Add an AWS Lambda wired to an S3 bucket" · "Use the real Kubernetes pod icon"

python3 scripts/shapesearch.py "aws lambda" --limit 5
# → Lambda (77x93)
#   outlineConnect=0;...;shape=mxgraph.aws3.lambda;fillColor=#F58534;...

_{↑ A serverless AWS architecture — every icon is the real official draw.io shape resolved by shapesearch.py, not a hand-guessed shape= string.}

Covers AWS / Azure / GCP / Cisco / Kubernetes / UML / BPMN / ER / electrical / P&ID and the general shape sets. Hand-writable style cheatsheet + search usage in references/shapes.md.

🤖 AI / LLM Brand Logos

draw.io ships no modern AI/LLM logos, so an LLM-app diagram renders as generic boxes. aiicons.py resolves a brand name to a draw.io image style for any of 321 logos (OpenAI, Claude, Gemini, Mistral, Llama, Cohere, DeepSeek, Qwen, Ollama, LangChain, HuggingFace…) from lobe-icons (MIT).

python3 scripts/aiicons.py "claude" --json      # CDN-referenced (default)
python3 scripts/aiicons.py "openai" --embed     # self-contained data URI

_{↑ A multi-provider LLM app — every brand logo resolved by aiicons.py. Icons are referenced from the unpkg CDN by default (network needed at render time); --embed inlines them for offline use. Logos are trademarks of their owners, used for identification only.}

🎨 Style Presets

Capture a visual style once, reuse it everywhere. Three presets are built in — default, corporate, handdrawn — and you can teach the skill your own style from a .drawio file or a flat image:

Draw a microservices architecture using my "corporate" style

Learn my style from ~/diagrams/brand.drawio as "mybrand"

The skill extracts colors, shapes, fonts, and edge style, renders a preview, and only saves the preset after you approve. Full preset-management commands in docs/STYLE_PRESETS.md.

🔄 How it works

Behind the scenes: check dependencies → plan layout → generate .drawio XML → export draft PNG → self-check + auto-fix (up to 2 rounds) → show to user → 5-round feedback loop until approved → final export.

🆚 Comparison

vs Native Agent (no skill)

vs Other draw.io Skills & Tools

Feature	drawio-skill	jgraph/drawio-mcp (official)	bahayonghang/drawio-skills	GBSOSS/ai-drawio
Approach	Pure SKILL.md	SKILL.md / MCP / Project	YAML DSL + CLI (MCP optional)	Claude Code plugin
Dependencies	draw.io desktop only	draw.io desktop	draw.io desktop (MCP optional)	draw.io plugin + browser
Multi-agent	✅ 6 platforms	❌ Claude apps only	✅ Claude / Gemini / Codex	❌ Claude Code only
Self-check + auto-fix	✅ 2-round (reads PNG)	❌	✅ validation + strict mode	❌ screenshot only
Iterative review	✅ 5-round loop	❌ generate once	✅ 3 workflows	❌
Diagram presets	✅ 6 types	❌	✅ paper-mode classifier	❌
ML/DL diagrams	✅ tensor shapes, layer colors	❌	❌	❌
Color system	✅ 7-color semantic	❌	✅ 6 themes	❌
Official shape search	✅ 10k+ shapes (local)	✅ 10k+ shapes (MCP)	❌	❌
AI/LLM brand logos	✅ 321 (lobe-icons)	❌	❌	❌
Browser fallback	✅ diagrams.net URL (viewer + editable)	❌ inline preview only	✅ via optional MCP	✅ diagrams.net viewer (primary)
Zero-config	✅ copy skills/drawio-skill/	✅	✅ desktop-only mode	❌ needs plugin install

Full comparison + key-advantages summary in docs/COMPARISON.md (with audit timestamp).

🎯 When to use (and when not to)

Good fit:

• Polished, precise diagrams — stakeholder decks, architecture, network topology, strict UML, ER diagrams
• Solid opaque fills, 10,000+ official shapes, branded icons (AWS / Azure / GCP / Cisco / Kubernetes + AI/LLM logos), swimlanes, and custom geometry
• Anything you'll export to PNG / SVG / PDF and keep editable

Reach for a sibling skill instead when you need:

• A casual, hand-drawn / whiteboard look → excalidraw-skill or tldraw-skill
• Diagrams-as-code that live in git and render in Markdown → mermaid-skill (general) or plantuml-skill (UML)
• Freeform infinite-canvas sketching / freehand strokes → tldraw-skill

🔗 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