Skip to content

Agent skill that turns natural language, code, Terraform/K8s, SQL, OpenAPI, AsyncAPI, Protobuf and GraphQL sources into editable, tested draw.io architecture diagrams: incremental sync, multi-view projection, drift diff, CI architecture tests, whiteboard derasterize, interactive HTML/PPTX/Mermaid exports.

docs: toolbox.md — map all 25 scripts by use-case (v1.26.1) (#75)

Agents365.ai46d5eb10c714
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7f4403b..8e6c8ab 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,14 @@ All notable changes to **drawio-skill** are documented here. The format is based
on [Keep a Changelog](https://keepachangelog.com/), and the project follows
semantic-ish versioning (the `version:` field in `skills/drawio-skill/SKILL.md`).
+## [1.26.1] — 2026-07-04
+### Added
+- **`references/toolbox.md`** — a use-case map of all 25 bundled scripts
+ (author / import code / import IaC / live infra / compare / reverse-export /
+ utilities) with an "I have X, I want Y → use Z" decision guide and the shared
+ extractor → autolayout → validate → export pipeline. Docs only; SKILL.md
+ resource table points to it as the "not sure which script fits" entry.
+
## [1.26.0] — 2026-07-04
### Added
- **Diagram → Mermaid** (`scripts/drawio2mermaid.py`) — convert a `.drawio` into
diff --git a/skills/drawio-skill/SKILL.md b/skills/drawio-skill/SKILL.md
index c657780..f82084a 100644
--- a/skills/drawio-skill/SKILL.md
+++ b/skills/drawio-skill/SKILL.md
@@ -1,6 +1,6 @@
---
name: drawio-skill
-version: 1.26.0
+version: 1.26.1
description: Use when the user requests diagrams, flowcharts, architecture diagrams, ER diagrams, UML / sequence / class diagrams, network topology, cloud architecture from Terraform or Kubernetes manifests, ML/DL model figures (Transformer/CNN/LSTM), mind maps, or any visualization. Also use proactively when explaining systems with 3+ components, complex data flows, or relationships that benefit from visual representation. Best suited when the diagram needs custom styling, rich shape vocabulary, swimlanes, or exportable images (PNG/SVG/PDF/JPG). Generates .drawio XML and exports locally via the native draw.io desktop CLI.
license: MIT
homepage: https://github.com/Agents365-ai/drawio-skill
@@ -34,6 +34,7 @@ When the workflow references one of these, read it on demand — none of them ne
| File | Read it when |
|---|---|
+| `references/toolbox.md` | You're **not sure which bundled script fits** a request, or want to chain several — a map of all 25 scripts grouped by use-case (author / import code / import IaC / live infra / compare / reverse-export / utilities) with an "I have X, I want Y → use Z" guide |
| `references/xml-authoring.md` | You're about to **hand-write `.drawio` XML** (workflow step 3) — file skeleton, shape/edge cells, containers, connection distribution, palette, spacing/grid rules. Not needed when a bundled generator writes the XML |
| `references/mermaid-authoring.md` | The diagram is a **standard type with no custom styling/icon needs** (flowchart, state, gantt, mindmap, timeline, journey, pie, …) and the CLI is **≥ v30** — author it as Mermaid text and let the CLI convert to native `.drawio` (structure only, layout free). Also documents the CLI's ELK `--layout` pass for XML |
| `references/diagram-types.md` | The user names a specific diagram type (ERD, UML class, sequence, C4, architecture, ML/DL, flowchart) |
diff --git a/skills/drawio-skill/references/toolbox.md b/skills/drawio-skill/references/toolbox.md
new file mode 100644
index 0000000..853af35
--- /dev/null
+++ b/skills/drawio-skill/references/toolbox.md
@@ -0,0 +1,83 @@
+# Toolbox — every bundled script, by use-case
+
+A map of the 25 bundled scripts grouped by what you're trying to do. The
+per-task routing table in `SKILL.md` says *when* to reach for each; this says
+*how they fit together*. Read it when you're not sure which script a request
+maps to, or you want to chain several.
+
+The recurring backbone is one pipeline — an **extractor** emits graph JSON, then
+`autolayout.py` places it, then `validate.py` lints it, then the draw.io CLI
+exports it:
+
+```
+<extractor> → graph.json → autolayout.py → diagram.drawio → validate.py → (export PNG/SVG/PDF)
+```
+
+## Quick decision guide
+
+| I have… | I want… | Use |
+|---|---|---|
+| a description in words | a styled diagram | hand-write XML (`references/xml-authoring.md`) or `autolayout.py` |
+| a big/complex graph | it laid out for me | `autolayout.py` (`--tune` picks direction) |
+| a Python/JS/Go/Rust project | its module/class structure | `pyimports` · `jsimports` · `goimports` · `rustimports` · `pyclasses` |
+| Terraform/K8s/compose files | the **declared** architecture | `tfimports` · `k8simports` · `composeimports` |
+| a running cluster/stack/cloud | what's **actually deployed** | `tfstate` · `dockerimports` · `k8simports -` |
+| a SQL schema | an ER diagram | `sqlerd` |
+| a sequence of interactions | a UML sequence diagram | `seqlayout` |
+| a system at 3 zoom levels | a C4 model with drill-down | `c4` |
+| two diagrams / two snapshots | what changed (drift) | `drawiodiff` |
+| a repo's git history | how its architecture grew | `timelapse` |
+| a `.drawio` | a written description | `explain` (→ Markdown) |
+| a `.drawio` | a slide deck | `drawio2pptx` (→ PPTX) |
+| a `.drawio` | an animated data-flow | `svgflow` (→ SVG) |
+| a `.drawio` | diagrams-as-code | `drawio2mermaid` (→ Mermaid) |
+| a shape/icon need | the exact style string | `shapesearch` · `aiicons` (AI/LLM logos) |
+
+## 1. Author & place
+
+- **`autolayout.py`** — graph JSON → placed `.drawio` (Graphviz `dot`; orthogonal routing, `--group` containers, `--tune` best direction). The hub every extractor feeds. See `references/autolayout.md`.
+- **`seqlayout.py`** — participants + messages JSON → sequence diagram with computed lifelines/activation bars (no Graphviz).
+- **`c4.py`** — levels JSON → one multi-page `.drawio` (Context→Container→Component) with click-to-drill-down links.
+- **`shapesearch.py`** — search 10k+ official shapes for their exact `style=` string. **`aiicons.py`** — draw.io `image` styles for AI/LLM brand logos.
+
+## 2. Code → diagram
+
+- **`pyimports` · `jsimports` · `goimports` · `rustimports`** — a project's intra-module import graph (transitive-reduced; `--group` boxes by sub-package).
+- **`pyclasses.py`** — a Python class-inheritance graph.
+
+All emit graph JSON → `autolayout.py`.
+
+## 3. Infrastructure → diagram (declared config)
+
+- **`tfimports.py`** — Terraform `.tf` → resources as official AWS/Azure/GCP icons.
+- **`k8simports.py`** — K8s manifests → objects as official kind icons (edges: Ingress→Service→workload→ConfigMap/Secret/PVC).
+- **`composeimports.py`** — docker-compose → service boxes + volume cylinders.
+- **`sqlerd.py`** — SQL DDL (`CREATE TABLE`) → ERD with crow's-foot FK edges.
+
+## 4. Live infrastructure → diagram (actually running)
+
+The **actual** counterpart to §3 — see `references/live-infra.md`.
+
+- **`tfstate.py`** — `terraform show -json | tfstate.py -` → deployed resources (provider-agnostic; expands `count`/`for_each`).
+- **`dockerimports.py`** — `docker inspect $(docker ps -q) | dockerimports.py -` → running containers + networks + volumes.
+- **`k8simports.py -`** — `kubectl get all,ing,cm,secret,pvc -o json | k8simports.py -` → live cluster.
+
+## 5. Compare & evolve
+
+- **`drawiodiff.py`** — diff two `.drawio` (or two live snapshots) → colour-coded graph (added=green, removed=red, changed=orange). Pairs with §4 for drift.
+- **`timelapse.py`** — re-run an extractor across git history → a self-contained HTML player of how the architecture grew.
+
+## 6. Diagram → other formats (reverse / interop)
+
+The skill runs both directions — these turn a `.drawio` back into something else:
+
+- **`explain.py`** — → structured **Markdown** (components by tier, relations, per-page C4).
+- **`drawio2pptx.py`** — → a 16:9 **PowerPoint** deck, one page per slide (needs `python-pptx`).
+- **`svgflow.py`** — → an **animated SVG** (edges flow as marching ants); renders on GitHub.
+- **`drawio2mermaid.py`** — → **Mermaid** `flowchart` text (diagrams-as-code GitHub renders).
+
+## 7. Utilities & quality
+
+- **`validate.py`** — deterministic structural lint (dangling edges, dup/reserved ids, overlaps; `--score` for layout readability). Run before exporting.
+- **`repair_png.py`** — fix draw.io's truncated IEND chunk after every `-e` PNG export (issue #8).
+- **`encode_drawio_url.py`** — encode a `.drawio` into a diagrams.net browser URL when the CLI is unavailable (`--edit` for an editable editor URL).