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.
Python agent-skillsarchitecturearchitecture-diagramasyncapibpmnc4-modelclaude-codediagramdiagrams-as-codedrawioflowchartgithub-actionsgraphqlimage-to-diagramkubernetesmcp-serverprotobufsysmlterraformuml
docs: toolbox.md — map all 25 scripts by use-case (v1.26.1) (#75)
Agents365.ai46d5eb10c714
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 basedon [Keep a Changelog](https://keepachangelog.com/), and the project followssemantic-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` intodiff --git a/skills/drawio-skill/SKILL.md b/skills/drawio-skill/SKILL.mdindex 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.1description: 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: MIThomepage: 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.mdnew file mode 100644index 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).