drawio-skill — From Text to Professional Diagrams
English · 中文 · 📖 Online Docs
A skill that turns natural language and real system sources into maintainable .drawio architecture models. Beyond generation and export, it incrementally synchronizes without discarding manual layout, projects multiple views from one model, enforces architecture contracts, queries dependencies, simulates failure propagation, and publishes dependency-free interactive walkthroughs. Works with Claude Code, Cursor, Copilot, OpenClaw, Codex, Autohand Code, Hermes, and any agent compatible with the Agent Skills format.
✨ Highlights
- Architecture digital twin / Diagram IR — separate meaning, provenance, and geometry; project executive, system, deployment, data-flow, and security views from one model
- Incremental sync without losing manual layout —
diagramctl sync updates changed nodes/relations while preserving tuned coordinates, styles, and annotations; removals stay reviewable by default
- Diagram-as-Test — YAML/JSON rules for direct Internet-to-database access, cycles, orphans, ownership, production observability, external timeouts, trust-boundary protocols, and color contrast
- Architecture query and review — query components/owners/boundaries/paths, identify articulation points and high coupling, and emit Markdown/JSON review reports
- What-if + Story Mode — simulate failure propagation with an annotated diagram; publish an offline, keyboard-accessible HTML walkthrough with text alternative, provenance, and language switching
- MCP server built in —
scripts/diagramctl_mcp.py exposes nine tools (build/sync/views/architecture_test/review/query/whatif/story/doctor) to Claude Desktop, Cursor, VS Code, Codex, and any MCP host; stdlib-only and offline, no mcp package
- One CLI —
doctor/build/sync/views/query/test/review/whatif/story/publish/transform connects the toolbox; core semantic workflows need only Python and are offline by default
- 11 diagram type presets — ERD, UML Class, Sequence, C4, Architecture, ML/Deep Learning, Flowchart, SysML (BDD / IBD / Requirement / Parametric), BPMN, Network Topology, Cross-Functional Swimlane
- Mermaid → native .drawio (draw.io ≥ 30) — author 28 standard types as Mermaid text (mindmap, gantt, timeline, journey, pie, sankey, kanban…) and the CLI converts them into a laid-out, editable
.drawio — structure in, layout free
- 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
- CI-ready — official
drawio-architecture-test GitHub Action enforces architecture contracts on every PR with no draw.io/Xvfb/Graphviz install; visual PR diff action for rendered .drawio
- Multi-agent, no daemon — portable Agent Skills package plus an optional MCP server for host integrations (core semantic workflows need only Python; native export remains optional)
🗺️ Feature Map
A bird's-eye view of everything the skill does — diagram types, import sources, layout engines, styling, export formats, and repurposing — in one map. Fittingly, this map was itself drawn with drawio-skill.
🖼️ Examples
The maintained Architecture Studio showcase
covers code → IR → .drawio, conflict-aware synchronization that preserves a
manually tuned layout, and architecture → policy/views/what-if/accessible Story.
Every artifact is regenerated by one script and verified in the test suite.
[!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.
|
It also speaks Mermaid — standard types (flowchart, mindmap, kanban, gitGraph, timeline…) convert straight to native, editable .drawio. Here's a Kanban board (this project's own roadmap) generated from a few lines of Mermaid:
Tube-Map Mode restyles a pipeline or journey as a London-Underground-style metro map — coloured lines, octilinear (H/V/45°) routing, and white interchange circles. Here's the skill's own flow (this map is assets/tubemap.json, ~20 lines):
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. Version ≥ 30 recommended — it unlocks Mermaid → .drawio conversion and the ELK --layout pass (both unavailable on ≤ 29). 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.
Updating: /plugin update drawio (Claude Code), skills update drawio-skill (SkillsMP), 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
# Live infrastructure — draw what's ACTUALLY running / deployed
terraform show -json | python3 scripts/tfstate.py - -o graph.json # deployed cloud
docker inspect $(docker ps -q)| python3 scripts/dockerimports.py - -o graph.json # running containers
kubectl get all,ing,cm,secret,pvc -o json | python3 scripts/k8simports.py - -o graph.json # live cluster
# Data & interactions
python3 scripts/sqlerd.py schema.sql -o graph.json # SQL DDL → ER diagram
python3 scripts/ciimports.py . -o graph.json # GitHub Actions + GitLab CI -> pipeline DAG
python3 scripts/openapiimports.py openapi.yaml -o graph.json # OpenAPI/Swagger → API diagram (by method)
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
# Diff two diagrams / snapshots → colour-coded "what changed"
python3 scripts/drawiodiff.py old.drawio new.drawio -o graph.json # +added -removed ~changed
# Architecture time-lapse → self-contained HTML player of how a codebase grew
python3 scripts/timelapse.py src --importer pyimports # → architecture-evolution.html
# Reverse: describe an existing .drawio as structured Markdown (README / PR summary)
python3 scripts/explain.py architecture.drawio -o architecture.md
# Diagram → PowerPoint deck (one page per slide; C4 model → presentation)
python3 scripts/drawio2pptx.py c4.drawio -o c4.pptx # needs: pip install python-pptx
# Interactive HTML viewer — pan/zoom/search/tabs + working drill-down links, one file
python3 scripts/drawiohtml.py c4.drawio -o c4.html
# Animated data-flow SVG — edges "flow" (marching ants); renders on GitHub
python3 scripts/svgflow.py architecture.drawio -o flow.svg
# Reverse: .drawio → Mermaid flowchart (diagrams-as-code GitHub renders)
python3 scripts/drawio2mermaid.py architecture.drawio --fenced -o arch.md
# Language variant: extract labels → translate values → apply (layout untouched)
python3 scripts/relabel.py architecture.drawio --extract -o labels.json
python3 scripts/relabel.py architecture.drawio --map labels.json -o architecture_cn.drawio
# Re-theme an existing .drawio with a style preset (e.g. dark mode)
python3 scripts/restyle.py architecture.drawio --preset dark
# Colour an existing .drawio by data → cost / latency / traffic heat map
python3 scripts/heatmap.py architecture.drawio -m latency.csv --size -o hot.drawio
# any extractor → auto-layout → editable .drawio
python3 scripts/autolayout.py graph.json -o diagram.drawio
# Image → editable .drawio — your vision extracts the graph JSON, this rebuilds it
python3 scripts/raster2drawio.py whiteboard-graph.json -o out.drawio
# Watch a diagram build itself, node by node → HTML player (+ optional GIF)
python3 scripts/buildup.py architecture.drawio --gif build.gif # → buildup.html
# Big diagram → boardroom exec summary (clustered) + click-to-drill-down to full
python3 scripts/compress.py big.drawio -o exec.drawio
# Decision-tree flowchart → click-through HTML triage runbook (no draw.io CLI needed)
python3 scripts/runbook.py triage.drawio -o triage.html
# CI: render base/head/diff PNGs + Markdown report for every .drawio a PR changed
python3 scripts/prdiff.py --base origin/main --head HEAD -o drawio-pr/report.md
# Tube-Map Mode — restyle a pipeline / journey as a metro / subway map
python3 scripts/tubemap.py metro.json -o metro.drawio
| Piece |
What it does |
| 13 extractors |
import graphs for Python · JS/TS · Go · Rust, Python class inheritance, Terraform / Kubernetes / docker-compose resource graphs (official cloud icons), SQL DDL → ERD, OpenAPI / Swagger → API diagram (operations coloured by HTTP method + schemas), CI pipelines → DAG (GitHub Actions needs: graphs + GitLab stages, with triggers, matrix sizes, reusable-workflow calls), and live infra from terraform show -json / docker inspect / kubectl get -o json (draw what's actually deployed) |
| Diagram diff |
drawiodiff.py compares two .drawio (or two live snapshots) into one colour-coded graph — added=green, removed=red, changed=orange — so you can see architecture / infra drift at a glance |
| Language variants |
relabel.py swaps every label via a JSON map with layout/styles/ids untouched — --extract dumps all labels, translate the values, --map applies them. One diagram → EN + CN twins for bilingual docs |
| Re-theme |
restyle.py applies a style preset (built-in dark/corporate/… or your own) to an existing .drawio — palette remapped by hue so same-colored nodes stay grouped; layout and edge routing untouched |
| Metric heat map |
heatmap.py recolours an existing .drawio from a CSV/JSON of per-node values — cost / latency / traffic / error-rate shaded low→high on a gradient (optional size-by-value + legend), matched by cell id or label |
| Architecture time-lapse |
timelapse.py re-runs an importer across a repo's git history and assembles a self-contained HTML player — watch modules & edges appear over time (▶ play / ‹ › step) |
| Diagram → Markdown |
explain.py reverses a .drawio into a structured description — components by tier, relations, per-page for C4 — for dropping an architecture summary into a README or PR |
| Interactive viewer |
drawiohtml.py publishes a .drawio as one self-contained HTML — page tabs, drag-pan, wheel-zoom, node search, and a C4 model's drill-down links keep working. Share the file; no draw.io, no server |
| Diagram → PowerPoint |
drawio2pptx.py turns a multi-page diagram into a 16:9 deck (one page per slide, page name as title) — a C4 model becomes a ready-to-present slideshow |
| Animated data-flow |
svgflow.py makes a diagram's edges flow (marching-ants animation along each arrow) — a self-contained looping SVG that renders on GitHub, in docs, or as a slide background |
| Diagram → Mermaid |
drawio2mermaid.py converts a .drawio into a Mermaid flowchart (containers → subgraphs, edge labels kept) — paste it into Markdown as diagrams-as-code that GitHub renders natively |
| 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 |
An agent skill that turns plain-language descriptions and real system sources — code, Terraform, Kubernetes, SQL, OpenAPI — into editable .drawio architecture diagrams, then keeps them synced, tested and exportable.