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
From a prompt
Describe it, get an editable .drawio — the skill plans the layout, writes the XML, exports, then self-checks its own PNG and auto-fixes overlaps, clipped labels, and stacked edges (up to 2 rounds), with up to 5 rounds of your feedback
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
Whiteboard photo / screenshot → editable diagram — snap a legacy PNG or a physical whiteboard, let vision extract the graph, and raster2drawio.py rebuilds it as a real, editable .drawio honouring the original layout
Visualize a codebase — import graphs for Python / JS-TS / Go / Rust and Python class hierarchies, with Graphviz placement, transitive reduction, and nested module containers
IaC and live infrastructure — Terraform, Kubernetes, and docker-compose configs become diagrams with official AWS / Azure / GCP / K8s icons; snapshot what's actually deployed from terraform show -json, docker inspect, or kubectl get -o json
Schemas and pipelines — SQL DDL → ER diagram, OpenAPI/Swagger → API diagram coloured by HTTP method, AsyncAPI → event-driven architecture diagram, Protocol Buffers → message/service diagram, GraphQL SDL → entity type diagram, GitHub Actions / GitLab CI → pipeline DAG
Deterministic engines — sequence diagrams with computed lifelines and activation bars; multi-page C4 models with click-to-drill-down
Keep it true over time
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, in CI — YAML/JSON architecture rules (Internet-to-database access, cycles, orphans, trust boundaries, contrast…) plus an official GitHub Action that enforces them on every PR, and a PR action that renders visual diffs
Query, review, what-if — query components/owners/paths, spot articulation points and high coupling, simulate failure propagation, publish an accessible Story walkthrough
Drift and history — colour-coded diffs between two diagrams or two live snapshots; a time-lapse player of how a codebase's architecture grew
Share and restyle
Repurpose with one command — interactive HTML viewer (pan/zoom/search), PowerPoint deck, animated data-flow SVG, Mermaid or Markdown export, click-through runbook, exec-summary compression
Restyle and enrich — style presets (yours or built-in dark/corporate/…), bilingual label variants with layout untouched, data-driven heat maps, white-to-metro tubemap mode
10,000+ official shapes + 321 AI/LLM logos — resolve exact AWS / Cisco / K8s / UML icon styles instead of guessing, plus brand logos draw.io itself lacks
One CLI, optional MCP server — diagramctl doctor/build/sync/views/query/test/review/whatif/story/publish/transform, core workflows stdlib-only and offline; the MCP server exposes them to Claude Desktop, Cursor, VS Code, Codex, and any MCP host. Portable to any Agent Skills-compatible agent, no daemon
🗺️ 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.
.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.
Manual install: clone once to a persistent path, then link the skill subdirectory (Claude Code shown). Use cp -R instead of ln -s on hosts that do not follow symlinks. The destination must not exist yet, so move an existing drawio-skill entry aside first.
mkdir -p ~/src
git clone https://github.com/Agents365-ai/drawio-skill.git ~/src/drawio-skill
mkdir -p ~/.claude/skills
ln -s ~/src/drawio-skill/skills/drawio-skill ~/.claude/skills/drawio-skill
# Copy alternative, for hosts that do not follow symlinks
# mkdir -p ~/.claude/skills
# cp -R ~/src/drawio-skill/skills/drawio-skill ~/.claude/skills/drawio-skill
The skill is the skills/drawio-skill/ subdirectory, so SKILL.md must sit directly under the host entry: /drawio-skill/SKILL.md. Do not clone the repository root into a skills directory. Other host roots (Opencode, OpenClaw, Codex, Autohand Code global and project): docs/INSTALL_SKILL.md.
Autohand Code also supports autohand --skill-install for cataloged skills, with --project for workspace-level installs. Until this skill is listed there, use the manual recipe above with the Autohand Code skills root: ~/.autohand/skills/ (global) or /.autohand/skills/ (project).
Updating:npx skills update drawio-skill -g (skills CLI) for installer installs; link installs update with git -C ~/src/drawio-skill pull, and copy installs need a manual refresh. 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.
🖼️ Examples
[!TIP]
The diagram 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 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.
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.
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):
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:
# source -> graph JSON -> placed, editable .drawio
python3 scripts/tfimports.py ./infra -o graph.json # Terraform -> official AWS icons
python3 scripts/autolayout.py graph.json -o architecture.drawio
# drift between two states, then share as one interactive file
python3 scripts/drawiodiff.py v1.drawio v2.drawio -o drift.json
python3 scripts/drawiohtml.py architecture.drawio -o architecture.html
The full toolbox, grouped by stage:
Stage
Tools
Import
16 extractors: Python · JS/TS · Go · Rust import graphs, Python class inheritance, Terraform / Kubernetes / docker-compose with official cloud icons, live infra from terraform show -json / docker inspect / kubectl get -o json, SQL DDL → ERD, OpenAPI → API diagram (coloured by HTTP method), AsyncAPI → event-driven architecture diagram, Protobuf → message/service diagram, GraphQL SDL → entity type diagram, GitHub Actions + GitLab CI → DAG
Compare & evolve
drawiodiff.py colour-codes drift between two diagrams or two live snapshots (added=green, removed=red, changed=orange); timelapse.py replays git history as an HTML player; prdiff.py renders PR diffs in CI
restyle.py applies presets by hue remap, relabel.py produces translated twins with layout untouched, heatmap.py shades nodes from a metrics CSV/JSON, edgeports.py un-stacks edges at shape boundaries
Layout & lint
autolayout.py (Graphviz placement, orthogonal routing, --tune direction picking, --group containers, transitive reduction: asyncio 149 → 46 edges), seqlayout.py, c4.py, and the deterministic validate.py linter (--score / --strict)
Layout needs Graphviz (brew install graphviz / apt install graphviz) — optional; everything else works without it. Full format + flag reference in references/autolayout.md, every tool in references/toolbox.md. Regenerate, validate (--strict gate) and render headlessly in CI: docs/CI.md.
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"
↑ 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), plus 18 data-store brands (Redis, Postgres, MongoDB, Qdrant, Milvus, Supabase…) via simple-icons (CC0) for RAG stacks.
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. Five presets are built in — default, corporate, handdrawn, colorblind-safe (Okabe-Ito palette), dark — 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.
Using the official jgraph plugin?jgraph/drawio-mcp now ships an official Claude Code plugin (/plugin install drawio@drawio) that also generates .drawio and exports via the desktop CLI. drawio-skill is complementary — reach for it when you want the code / IaC / SQL / OpenAPI / AsyncAPI / Protobuf importers, AI-brand logos, deterministic sequence & C4 generators, self-check + review loop, and the interactive HTML viewer, all from a single SKILL.md with no MCP server.
Full comparison + key-advantages summary in docs/COMPARISON.md (with audit timestamp).
