Diagram

/diagram — Full-power draw.io diagrams (drawio-skill integration)

Origin & license

This skill packages most of the capability of drawio-skill (MIT License © Agents365-ai) — 28 Python scripts, shape search across 10,000+ icons, style-preset system, vision self-check workflow. The kit-root scripts/, references/, styles/, and data/ trees are near-verbatim copies of upstream — do NOT modify script internals; invoke them via Bash only. Original license is preserved in LICENSE-drawio-skill.

Differences from upstream behavior (to match TechSphereX AI house conventions):

• Communication language: English (match project / user language if they write in another language).
• Approval: use this kit’s approval-gate.md (L1/L2/L3) instead of upstream’s free-form review loop — essentially equivalent (L3 ≈ upstream self-check + review loop, L1 ≈ “Plan” before writing files, L2 ≈ diff when editing an existing .drawio).
• Default style: TechSphereX AI palette (drawio-conventions.md) — NOT the upstream default preset — unless the user names another preset or has set a personal default.
• Output path: docs/diagrams/{feature}/{diagram-type}-{slug}.drawio (per drawio-conventions.md section 7), not the current working directory.
• No automatic image export — default is write .drawio only (per “do NOT export static images unless the user explicitly asks” in drawio-conventions.md). Export a temporary PNG draft only when vision self-check is needed for a complex diagram, and always tell the user it is temporary.

When to use /diagram instead of /architecture / /flowchart

Prerequisites (confirm on this machine)

• draw.io desktop CLI: installed, v30.2.6 at C:\Program Files\draw.io\draw.io.exe — supports Mermaid→.drawio conversion and --layout ELK (both require v30+).
• Graphviz (dot): may be missing — scripts/autolayout.py needs Graphviz for layout. If missing, use CLI --layout ELK instead (see references/autolayout.md), or tell the user to install graphviz if they want autolayout.py specifically.
• Always resolve the real binary path before export commands — on this machine use "C:\Program Files\draw.io\draw.io.exe" (NOT bare drawio, which may not be on PATH).

Input examples

/diagram microservices architecture: API Gateway, Auth/Order/Payment service, Kafka, Postgres, Redis
/diagram --type erd @schema.sql
/diagram --type sequence OAuth login flow: Client, Auth Server, Resource Server
/diagram --type c4 TOPO system (Context → Container → Component)
/diagram --from-code ./src --lang python --group          # import graph diagram
/diagram --from-iac ./infra --lang terraform               # architecture from Terraform, real cloud icons
/diagram redraw existing container architecture with style "corporate"
/diagram learn style from @docs/diagrams/container/architecture-overview.drawio name it "TechSphereX AI-brand"
/diagram export docs/diagrams/topo/architecture-overview.drawio to PNG

Workflow

Step 0 — Resolve style preset

Per references/style-presets.md:

1. Scan the user request for an explicit preset name (“use style X”, “in the X look”). The phrase with X does not count if X is a component name, not a style.
2. If none → check whether the user has set any preset "default": true (stored under ~/.drawio-skill/styles/ per upstream design, or an equivalent project directory if there is no shared home).
3. If none → default to the TechSphereX AI palette (drawio-conventions.md sections 2–6). Do NOT use drawio-skill’s built-in default.json unless the user explicitly passes --style default.
4. Valid preset → load from styles/built-in/<name>.json (built-ins: default, corporate, handdrawn, colorblind-safe, dark) or a user-saved file. Unknown preset name → report error, list available presets, do NOT silently fall back.

Step 1 — Determine diagram type & clarify requirements

If important information is missing, ask at most 1–3 questions:

• Diagram type — see references/diagram-types.md to map the user’s wording (ERD/UML/Sequence/Architecture/ML/Flowchart/C4).
• Data source — free-form description, or existing code/SQL/IaC/OpenAPI?
• Image export needed? — default NO (.drawio only); ask if the user did not specify.

Skip questions when the request is already clear enough.

Choose how to produce XML (condensed from references/toolbox.md):

Step 2 — L3 Preview (per approval-gate.md)

• Hand-authored / small diagrams: list nodes/edges as a table (like /architecture, /flowchart) so the user reviews layout before full XML.
• Script-generated diagrams (autolayout/importer/sqlerd/seqlayout/c4):
  1. Run the script to produce .drawio.
  2. Run scripts/validate.py <file>.drawio — structural lint (dangling edges, duplicate ids, cell overlap) before any image export.
  3. If a preview is needed: export a PNG draft (without -e, --width 2000 so it stays under the vision API’s 2576px limit) — tell the user this is a temporary review image, not the final deliverable.
  4. If the model has vision: read the PNG and check against common defects (overlapping shapes, clipped labels, unconnected arrows, nodes outside the page, crossing edges) — at most 2 self-fix rounds.
  5. Show the image to the user; ask Approve / Edit: … / Cancel. Localized edits (color, add/remove node, rename label) → edit XML in place, keep layout. Full direction/layout changes → regenerate from scratch.
  6. At most 5 review loops — then suggest the user open the file in draw.io desktop for manual polish.

Step 3 — L1 Approval → Write

Write .drawio to docs/diagrams/{feature}/{diagram-type}-{slug}.drawio. If the file already exists → L2 diff before overwrite.

Step 4 — Export (only when the user asks or passes --export)

Use the confirmed binary ("C:\Program Files\draw.io\draw.io.exe" on this machine):

# Preview / self-check (Step 2) — NO -e
"C:\Program Files\draw.io\draw.io.exe" -x -f png --width 2000 -o preview.png input.drawio

# Final export — WITH -e so the .drawio.png stays re-editable in draw.io
"C:\Program Files\draw.io\draw.io.exe" -x -f png -e -s 2 -o output.drawio.png input.drawio
python scripts/repair_png.py output.drawio.png   # REQUIRED after every -e PNG export (CLI may omit IEND chunk)

# SVG / PDF (no IEND issue; -e is safe)
"C:\Program Files\draw.io\draw.io.exe" -x -f svg -e -o output.svg input.drawio
"C:\Program Files\draw.io\draw.io.exe" -x -f pdf -e -o output.pdf input.drawio

Report paths for both the source .drawio and any exported images.

Extended features (invoke when the user needs them)

Mandatory rules

• Default: no image export — write .drawio only, unless the user asks or vision self-check truly needs a temporary image (and say so).
• Default style = TechSphereX AI palette (drawio-conventions.md), not upstream preset, unless another preset is specified.
• Prefer core shapes; vendor icons via shapesearch.py — MUST note that the matching shape library must be enabled in draw.io when using non-core stencils.
• Do NOT modify logic inside scripts/, references/, or data/ — third-party MIT source; invoke via Bash only. For different behavior, wrap/override at this SKILL.md layer; do not patch upstream scripts.
• After every -e PNG export, immediately run scripts/repair_png.py.
• After every autolayout.py/importer run, MUST run scripts/validate.py before image export or completion report.

Output

• docs/diagrams/{feature}/{diagram-type}-{slug}.drawio — primary source file.
• Exported images (if requested): same directory, double extension .drawio.png / .svg / .pdf (embedded XML so they remain editable in draw.io).

References

• @.claude/rules/approval-gate.md
• @.claude/rules/drawio-conventions.md
• @.claude/rules/naming-conventions.md
• Brain: DRAWIO-BRAIN.md
• @references/toolbox.md — full map of 28 scripts; read when unsure which to use
• @references/diagram-types.md — shape/edge/layout presets by diagram type
• @references/xml-authoring.md — before hand-authoring XML
• @references/mermaid-authoring.md — when using Mermaid → CLI convert
• @references/style-presets.md — manage/apply style presets, Learn flow
• @references/style-extraction.md — style extraction for Learn
• @references/shapes.md — shape style cheatsheet + how to use shapesearch.py
• @references/autolayout.md — graph.json format for autolayout.py
• @references/live-infra.md — diagram live running infra (Terraform state/Docker/K8s live)
• @references/troubleshooting.md — export failures, vision rejecting images, bad layout
• @LICENSE-drawio-skill — original MIT license for the integrated code