drawio-skill Turns Prompts, Code, and Terraform into Editable Diagrams

Ask a generic agent for an architecture diagram and you usually get a pretty picture you have to redraw by hand. drawio-skill, a 10k-star project, targets the maintainable artifact instead: it turns natural language and real system sources into editable .drawio models, then keeps them true as the system changes — incremental sync without discarding manual layout, multiple views from one model, and architecture rules enforced in CI.

Why This Skill Matters

Three capabilities make it more than a diagram generator. First, it draws from real sources: 16 extractors turn Python, JavaScript/TypeScript, Go, and Rust import graphs, Terraform / Kubernetes / docker-compose configs, SQL DDL, OpenAPI, AsyncAPI, Protobuf, GraphQL SDL, and CI pipelines into diagrams — including live infrastructure snapshots from terraform show -json, docker inspect, or kubectl get -o json. Second, it self-checks: the workflow plans the layout, writes the .drawio XML, exports a draft PNG, reads it back, and auto-fixes overlaps and clipped labels for up to 2 rounds before showing you the result, with up to 5 rounds of feedback after that. Third, it ships real icon coverage: shape search resolves exact styles from 10,000+ official draw.io shapes, and aiicons.py resolves 321 AI/LLM brand logos plus 18 data-store brands.

It works with Claude Code, Cursor, Copilot, OpenClaw, Codex, Autohand Code, Hermes, and any agent compatible with the Agent Skills format — the README's own list.

Installation

Two steps. First the draw.io desktop CLI, since exports render through it:

brew install --cask drawio
drawio --version

Version 30 or later is recommended — it unlocks Mermaid-to-.drawio conversion and the ELK layout pass, both unavailable on earlier versions. Then install the skill:

npx skills add Agents365-ai/drawio-skill -g

Graphviz is optional and only needed for auto-layout (brew install graphviz); everything else works without it.

Real Workflow: Describe a Diagram, Iterate to Approval

1. Describe the system in plain language, the way the README's ML example does:

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.

2. The skill plans the layout, generates the .drawio XML, exports, and self-checks its own PNG before you see anything.
3. Ask for changes in up to 5 feedback rounds, then take the final export — PNG, SVG, or PDF.

Eleven diagram type presets cover the common shapes of this: ERD, UML Class, Sequence, C4, Architecture, ML/Deep Learning, Flowchart, SysML, BPMN, Network Topology, and Cross-Functional Swimlane.

Real Workflow: Sync a Diagram When the Code Changes

The diagramctl sync flow updates changed nodes and relations while preserving your tuned coordinates, styles, and annotations; removals stay reviewable by default. For teams that want diagrams as a gate, architecture rules written as YAML/JSON run through an official GitHub Action on every PR, with visual diffs rendered alongside. One model can also project all five views — executive, system, deployment, data-flow, and security — instead of five hand-drawn forks.

Tips

• diagramctl subcommands cover the lifecycle: doctor, build, sync, views, query, test, review, whatif, story, publish, transform.
• Prefer authoring in text? 28 Mermaid standard types — mindmap, gantt, timeline, kanban and more — convert straight into native, editable .drawio on draw.io 30+.
• Style presets (default, corporate, handdrawn, colorblind-safe, dark) are built in, and the skill can learn your own style from an existing .drawio file after you approve the preview.
• The comparison table in the README is the project's own positioning — including against the official jgraph/drawio-mcp, which it describes as complementary.

When Not to Use This

The README routes alternatives honestly. For a casual hand-drawn or whiteboard look, it points to excalidraw-skill or tldraw-skill; for diagrams-as-code that live in git and render in Markdown, mermaid-skill or plantuml-skill; for freeform canvas sketching, tldraw-skill again. And if your target is a quick throwaway sketch, a two-step install plus draw.io desktop is more setup than the job deserves.

See the leaderboard for more skills.