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), Terraform / Kubernetes / docker-compose infrastructure, or a SQL schema into an auto-laid-out diagram. Works with Claude Code, Cursor, Copilot, OpenClaw, Codex, Autohand Code, Hermes, and any agent compatible with the Agent Skills format.

✨ Highlights

• 7 diagram type presets — ERD, UML Class, Sequence, C4, 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
• IaC → architecture diagram — turn Terraform configs, Kubernetes manifests, or docker-compose files into an architecture diagram where every resource renders as its official AWS / Azure / GCP / K8s icon, edges derived from actual references (role ARNs, selectors, volume mounts)
• SQL DDL → ER diagram — parse CREATE TABLE statements into per-table nodes with PK/FK markers and crow's-foot foreign-key edges
• Deterministic sequence diagrams — describe participants + messages as JSON; lifelines, auto-tracked activation bars, and arrows are computed, never hand-placed
• C4 model with drill-down — one command generates the multi-page System Context → Container → Component set with official C4 shapes; parent elements click through to their child page
• 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, plus 18 data-store brands (Redis, Postgres, Qdrant, Milvus…) for LLM/RAG 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

Platform	Command
macOS	brew install --cask drawio
Windows	Download installer
Linux	.deb/.rpm from releases; sudo apt install xvfb for headless

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

# Autohand Code global install
git clone https://github.com/Agents365-ai/drawio-skill.git \
  ~/.autohand/skills/drawio-skill

# Autohand Code project-level install
git clone https://github.com/Agents365-ai/drawio-skill.git \
  .autohand/skills/drawio-skill

Autohand Code also supports autohand --skill-install for cataloged skills, with --project for workspace-level installs. Until this skill is listed there, use the direct clone path above.

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 Code & Infrastructure

Beyond hand-authored diagrams, the skill turns existing code, infrastructure, and schemas into 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

# Infrastructure as Code — official cloud icons resolved automatically
python3 scripts/tfimports.py   ./infra      -o graph.json   # Terraform → AWS/Azure/GCP icons
python3 scripts/k8simports.py  ./manifests  -o graph.json   # K8s YAML/JSON → kind icons
python3 scripts/composeimports.py compose.yml -o graph.json # services + named volumes

# Data & interactions
python3 scripts/sqlerd.py      schema.sql   -o graph.json   # SQL DDL → ER diagram
python3 scripts/seqlayout.py   seq.json  -o sequence.drawio # sequence diagram, direct to .drawio
python3 scripts/c4.py          c4.json   -o c4.drawio       # C4 model, multi-page + drill-down

C4 Level 1 · System Context Clicking the blue system box in draw.io drills down to…

C4 Level 2 · Containers …the Containers page — one JSON, one multi-page .drawio.

_{↑ A serverless stack straight from main.tf — API Gateway, Lambdas, DynamoDB, SQS, S3, CloudFront and IAM all resolved to their official AWS icons, edges from real resource references. K8s manifests work the same way →}

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

Piece	What it does
9 extractors	import graphs for Python · JS/TS · Go · Rust, Python class inheritance, Terraform / Kubernetes / docker-compose resource graphs (official cloud icons), and SQL DDL → ERD
Sequence engine	seqlayout.py computes lifeline / activation-bar / arrow geometry from a message list — no Graphviz, no hand placement
Auto-layout	Graphviz places nodes and routes orthogonal edges around them — removes the manual-coordinate ceiling for large graphs. --tune tries both directions and keeps the more readable one
Transitive reduction	drops edges implied by a longer path, turning a dense hairball into a traceable graph (asyncio: 149 → 46 edges)
Nested containers	--group boxes modules by sub-package, nested for deep package trees
Deterministic validator	validate.py lints the .drawio (dangling edges, duplicate ids, overlaps) before the visual self-check

Layout needs Graphviz (brew install graphviz / apt install graphviz) — optional; everything else works without it. Full format + flag reference in references/autolayout.md. Regenerate, validate (--strict gate) and render headlessly in CI: docs/CI.md.

🧩 Supported Diagram Types

Category	Examples	Notable features
Architecture	microservices, cloud (AWS/GCP/Azure), network topology, deployment	Tier-based swimlanes, hub-center strategy
C4 model	system context, containers, components	Multi-page .drawio, click-to-drill-down links
ML / Deep Learning	Transformer, CNN, LSTM, GRU	Tensor shape annotations, layer-type color coding
Flowcharts	business processes, workflows, decision trees, state machines	Semantic shapes (parallelogram I/O, diamond decisions)
UML	class diagrams, sequence diagrams	Inheritance / composition / aggregation arrows; lifelines + activation boxes
Data	ER diagrams, data flow diagrams (DFD)	Table containers, PK/FK notation
Other	org charts, mind maps, wireframes	—

🔍 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}