[{"_1":2,"_474":-5,"_475":-5},"loaderData",{"_3":4,"_8":9,"_23":24},"root",{"_5":-5,"_6":7},"user","countable",true,"routes/_main",{"_5":-5,"_10":11},"recentPosts",[12,17,20],{"_13":14,"_15":16},"slug","best-mcp-servers-for-developers","title","The Best MCP Servers for Developers in 2026",{"_13":18,"_15":19},"claude-skill-and-plugin-security-scanning","Claude's Beta Skill and Plugin Security Scanning, Explained",{"_13":21,"_15":22},"mcp-tasks-extension-explained","How MCP's Tasks Extension Works","routes/creators.$handle",{"_25":26,"_27":26,"_28":29,"_30":31,"_32":33,"_472":31,"_473":114},"handle","agents365-ai","displayName","profileUrl","https://github.com/agents365-ai","verified",false,"skills",[34],{"_35":36,"_13":37,"_38":39,"_40":41,"_42":43,"_44":45,"_46":47,"_48":49,"_50":51,"_52":53,"_54":55,"_61":62,"_63":64,"_65":66,"_81":82,"_83":-5,"_84":85,"_86":87,"_88":89,"_90":91,"_92":93,"_94":-5,"_95":96,"_97":26,"_30":31,"_98":31,"_99":87,"_100":101,"_102":87,"_103":87,"_104":105,"_106":107,"_136":137,"_172":173,"_223":224,"_444":445,"_456":457,"_468":469,"_470":471},"id","gh__agents365-ai__drawio-skill__skills-drawio-skill","draw-io-diagrams-agents365-ai","name","Draw.io Diagrams","canonicalName","drawio-skill","tagline","Generate and export detailed diagrams effortlessly.","description","Use when the user requests diagrams, flowcharts, architecture diagrams, ER diagrams, UML / sequence / class diagrams, SysML / MBSE diagrams (block definition, internal block, requirement, parametric), BPMN business process diagrams, swimlane / cross-functional flowcharts, 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.","longDescription","The Draw.io Diagrams skill enables users to create and export a wide variety of diagrams in the `.drawio` format. This skill is particularly useful for generating architecture diagrams, flowcharts, UML diagrams, and more, with a focus on precision and custom styling. Users can export their diagrams in multiple formats including PNG, SVG, PDF, and JPG, ensuring that the diagrams retain their quality and are easily shareable. The skill leverages the native draw.io desktop app CLI, allowing for seamless integration into existing workflows without the need for browser automation.\n\nDesigned for developers, designers, and anyone needing to visualize complex systems, this skill excels in scenarios where clarity and detail are paramount. It supports over 10,000 stock and branded shapes, making it suitable for professional-grade diagrams that require specific icons or styles. The ability to embed the diagram XML within exported files ensures that users can easily edit their diagrams later, enhancing the usability of the exported content.\n\nThe skill also includes a variety of bundled scripts that facilitate the generation of diagrams from existing codebases or infrastructure definitions. For example, it can visualize project structures from Python, JavaScript, Go, and Rust, as well as extract and represent infrastructure from Terraform or Kubernetes manifests. This makes it a versatile tool for teams working with complex architectures or those who need to document their systems visually. The included references and scripts provide additional support for users to tailor the skill to their specific needs, ensuring that they can create the exact diagrams required for their projects.","primaryCategory","design","subcategory","graphic-design","secondaryCategories",[],"tags",[56,57,58,59,60],"drawio","diagrams","architecture","visualization","export","skillType","tool-wrapper","complexity","intermediate","platforms",[67,68,69,70,71,72,73,74,75,76,77,78,79,80],"claude-code","claude-api","codex-cli","cursor","antigravity","github-copilot","windsurf","opencode","cline","roo-code","goose","kiro","continue","trae","delivery","source-link","skillFileUrl","pricing","free","price",0,"thumbnailType","icon","thumbnailIcon","chart-bar","thumbnailColor","blue","thumbnailImageUrl","sellerId","gh__agents365-ai","sellerName","featured","downloads","views",4,"rating","reviewCount","status","active","metrics",{"_108":87,"_109":110,"_111":112,"_113":114,"_115":110,"_116":117,"_118":119,"_120":121,"_122":123,"_124":125,"_126":127,"_128":129,"_130":131,"_132":133,"_134":135},"repoOpenIssues","freshnessScore",100,"mirrorCount",2,"skillCountInRepo",1,"qualityScore","daysSinceUpdate",5,"popularityScore",79,"trustScore",60,"repoStars",7418,"repoWatchers",20,"repoContributors",8,"overallScore",87,"repoCreatedAt","2026-03-03T16:54:59Z","repoForks",541,"repoPushedAt","2026-08-05T10:18:33Z","source",{"_138":26,"_139":140,"_141":142,"_147":41,"_148":-5,"_145":149,"_150":151,"_152":31,"_153":154,"_155":156,"_162":163,"_164":7,"_165":166,"_167":168,"_169":170,"_171":170},"owner","repoUrl","https://github.com/agents365-ai/drawio-skill","author",{"_28":29,"_143":144,"_38":26,"_25":26,"_145":146},"avatarUrl","https://github.com/agents365-ai.png","type","User","repo","commitSha","github","branch","main","isOfficial","path","skills/drawio-skill","license",{"_38":157,"_158":159,"_160":161},"MIT License","spdxId","MIT","url","https://github.com/agents365-ai/drawio-skill/blob/main/LICENSE","sourceUpdatedAt","2026-08-05T10:18:30.000Z","redistributable","permalink","https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/SKILL.md","repoFullName","agents365-ai/drawio-skill","lastSyncedAt","2026-08-11T01:22:26.542Z","firstSeenAt","seo",{"_174":175,"_186":187,"_188":189,"_207":-5,"_208":209,"_215":216,"_217":218,"_219":220,"_221":222},"useCases",[176,180,183],{"_15":177,"_178":179},"Creating Architecture Diagrams","body","Use this skill to generate detailed architecture diagrams that represent complex systems clearly and professionally.",{"_15":181,"_178":182},"Visualizing Code Structures","Leverage the skill to visualize the structure of your Python or JavaScript projects, making it easier to understand dependencies and relationships.",{"_15":184,"_178":185},"Exporting Diagrams for Documentation","Export your diagrams in various formats for inclusion in technical documentation, ensuring they are high-quality and editable.","whenNotToUse","Avoid this skill for casual sketching or when you need diagrams-as-code that integrate directly with version control, as other tools like Mermaid or Excalidraw may be more suitable.","faqs",[190,195,198,201,204],{"_191":192,"_193":194},"q","What types of diagrams can I create with this skill?","a","You can create a variety of diagrams including flowcharts, architecture diagrams, UML diagrams, ER diagrams, and more, tailored to your specific needs.",{"_191":196,"_193":197},"How does the skill handle exports?","The skill exports diagrams in PNG, SVG, PDF, and JPG formats, with options to embed the diagram XML for easy editing later.",{"_191":199,"_193":200},"Can I use this skill for casual sketching?","No, this skill is designed for polished and precise diagrams. For casual sketching, consider using tools like Excalidraw or tldraw.",{"_191":202,"_193":203},"What if I need specific shapes for my diagrams?","The skill supports over 10,000 stock and branded shapes, and includes scripts to help you find specific icons or styles.",{"_191":205,"_193":206},"Is there support for generating diagrams from code?","Yes, the skill includes scripts that can visualize project structures from various programming languages and infrastructure definitions.","ogImageUrl","keywords",[210,211,212,213,214],"draw.io diagrams","generate diagrams","export draw.io","flowcharts","UML diagrams","whenToUse","Use this skill when you need to create detailed diagrams that require custom styling or specific shapes, particularly in professional or technical contexts.","metaTitle","Draw.io Diagrams Skill for Visualizations","problemSolved","This skill addresses the need for high-quality, customizable diagram generation and export, streamlining the process of visualizing complex systems.","metaDescription","Create and export detailed diagrams with the Draw.io skill for precise visualizations. Click to learn more!","content",{"_225":121,"_226":227,"_417":418,"_427":428,"_429":31,"_430":431,"_442":443},"bundledFiles","fileTree",[228,235,238,242,245,248,251,254,257,260,263,266,269,272,275,278,281,284,288,291,294,297,300,303,306,309,312,315,318,321,324,327,330,333,336,339,342,345,348,351,354,357,360,363,366,369,372,375,378,381,384,387,390,393,396,399,402,405,408,411,414],{"_153":229,"_230":231,"_145":232,"_233":234},"SKILL.md","size",43255,"file","language","markdown",{"_153":236,"_230":237,"_145":232,"_233":234},"data/SHAPE-INDEX-NOTICE.md",880,{"_153":239,"_230":240,"_145":232,"_233":241},"data/lobe-icons.json",12919,"json",{"_153":243,"_230":244,"_145":232},"data/shape-index.json.gz",436148,{"_153":246,"_230":247,"_145":232,"_233":234},"references/autolayout.md",19318,{"_153":249,"_230":250,"_145":232,"_233":234},"references/derasterize.md",2526,{"_153":252,"_230":253,"_145":232,"_233":234},"references/diagram-types.md",16691,{"_153":255,"_230":256,"_145":232,"_233":234},"references/live-infra.md",3670,{"_153":258,"_230":259,"_145":232,"_233":234},"references/mermaid-authoring.md",4978,{"_153":261,"_230":262,"_145":232,"_233":234},"references/pr-bot.md",3522,{"_153":264,"_230":265,"_145":232,"_233":234},"references/shapes.md",7155,{"_153":267,"_230":268,"_145":232,"_233":234},"references/style-extraction.md",17575,{"_153":270,"_230":271,"_145":232,"_233":234},"references/style-presets.md",11079,{"_153":273,"_230":274,"_145":232,"_233":234},"references/toolbox.md",9102,{"_153":276,"_230":277,"_145":232,"_233":234},"references/troubleshooting.md",5280,{"_153":279,"_230":280,"_145":232,"_233":234},"references/tubemap.md",3275,{"_153":282,"_230":283,"_145":232,"_233":234},"references/xml-authoring.md",12635,{"_153":285,"_230":286,"_145":232,"_233":287},"scripts/aiicons.py",7983,"python",{"_153":289,"_230":290,"_145":232,"_233":287},"scripts/autolayout.py",18286,{"_153":292,"_230":293,"_145":232,"_233":287},"scripts/buildup.py",14380,{"_153":295,"_230":296,"_145":232,"_233":287},"scripts/c4.py",6670,{"_153":298,"_230":299,"_145":232,"_233":287},"scripts/ciimports.py",7776,{"_153":301,"_230":302,"_145":232,"_233":287},"scripts/composeimports.py",4738,{"_153":304,"_230":305,"_145":232,"_233":287},"scripts/compress.py",10582,{"_153":307,"_230":308,"_145":232,"_233":287},"scripts/dockerimports.py",6337,{"_153":310,"_230":311,"_145":232,"_233":287},"scripts/drawio2mermaid.py",5965,{"_153":313,"_230":314,"_145":232,"_233":287},"scripts/drawio2pptx.py",4519,{"_153":316,"_230":317,"_145":232,"_233":287},"scripts/drawiodiff.py",7158,{"_153":319,"_230":320,"_145":232,"_233":287},"scripts/drawiohtml.py",10486,{"_153":322,"_230":323,"_145":232,"_233":287},"scripts/edgeports.py",9285,{"_153":325,"_230":326,"_145":232,"_233":287},"scripts/encode_drawio_url.py",2250,{"_153":328,"_230":329,"_145":232,"_233":287},"scripts/explain.py",6098,{"_153":331,"_230":332,"_145":232,"_233":287},"scripts/goimports.py",5557,{"_153":334,"_230":335,"_145":232,"_233":287},"scripts/heatmap.py",9176,{"_153":337,"_230":338,"_145":232,"_233":287},"scripts/jsimports.py",6314,{"_153":340,"_230":341,"_145":232,"_233":287},"scripts/k8simports.py",9805,{"_153":343,"_230":344,"_145":232,"_233":287},"scripts/openapiimports.py",6786,{"_153":346,"_230":347,"_145":232,"_233":287},"scripts/prdiff.py",7995,{"_153":349,"_230":350,"_145":232,"_233":287},"scripts/pyclasses.py",6221,{"_153":352,"_230":353,"_145":232,"_233":287},"scripts/pyimports.py",6353,{"_153":355,"_230":356,"_145":232,"_233":287},"scripts/raster2drawio.py",7467,{"_153":358,"_230":359,"_145":232,"_233":287},"scripts/relabel.py",4247,{"_153":361,"_230":362,"_145":232,"_233":287},"scripts/repair_png.py",1097,{"_153":364,"_230":365,"_145":232,"_233":287},"scripts/restyle.py",7243,{"_153":367,"_230":368,"_145":232,"_233":287},"scripts/runbook.py",10187,{"_153":370,"_230":371,"_145":232,"_233":287},"scripts/rustimports.py",7610,{"_153":373,"_230":374,"_145":232,"_233":287},"scripts/seqlayout.py",9917,{"_153":376,"_230":377,"_145":232,"_233":287},"scripts/shapesearch.py",5967,{"_153":379,"_230":380,"_145":232,"_233":287},"scripts/sqlerd.py",6745,{"_153":382,"_230":383,"_145":232,"_233":287},"scripts/svgflow.py",3735,{"_153":385,"_230":386,"_145":232,"_233":287},"scripts/tfimports.py",11910,{"_153":388,"_230":389,"_145":232,"_233":287},"scripts/tfstate.py",5533,{"_153":391,"_230":392,"_145":232,"_233":287},"scripts/timelapse.py",11188,{"_153":394,"_230":395,"_145":232,"_233":287},"scripts/tubemap.py",6895,{"_153":397,"_230":398,"_145":232,"_233":287},"scripts/validate.py",13337,{"_153":400,"_230":401,"_145":232,"_233":241},"styles/built-in/colorblind-safe.json",1472,{"_153":403,"_230":404,"_145":232,"_233":241},"styles/built-in/corporate.json",1471,{"_153":406,"_230":407,"_145":232,"_233":241},"styles/built-in/dark.json",1546,{"_153":409,"_230":410,"_145":232,"_233":241},"styles/built-in/default.json",1454,{"_153":412,"_230":413,"_145":232,"_233":241},"styles/built-in/handdrawn.json",1474,{"_153":415,"_230":416,"_145":232,"_233":241},"styles/schema.json",5362,"codeExamples",[419,423,425],{"_233":420,"_421":422},"bash","snippet","# macOS (Homebrew — recommended; CLI binary is `drawio`, not `draw.io`)\nbrew install --cask drawio\ndrawio --version\n\n# macOS (full path if not in PATH)\n/Applications/draw.io.app/Contents/MacOS/draw.io --version\n\n# Windows\n\"C:\\Program Files\\draw.io\\draw.io.exe\" --version\n\n# Linux\ndrawio --version",{"_233":420,"_421":424},"# Preview PNG (use this in step 4, before self-check) — NO -e, width-capped to stay under vision's 2576px ceiling\ndrawio -x -f png --width 2000 -o diagram.png input.drawio\n\n# Final PNG (step 7, after user approval) — WITH -e, double extension\ndrawio -x -f png -e -s 2 -o diagram.drawio.png input.drawio\n\n# macOS — full path (if not in PATH); preview / final variants\n/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png --width 2000 -o diagram.png input.drawio\n/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -e -s 2 -o diagram.drawio.png input.drawio\n\n# Windows\n\"C:\\Program Files\\draw.io\\draw.io.exe\" -x -f png -e -s 2 -o diagram.drawio.png input.drawio\n\n# Linux (headless — requires xvfb-run; on servers add HOME and --disable-gpu)\nexport HOME=${HOME:-/tmp}\nxvfb-run -a --server-args=\"-screen 0 1280x1024x24\" \\\n drawio -x -f png -e -s 2 -o diagram.drawio.png input.drawio --disable-gpu\n# Running as root (CI / Docker)? Append --no-sandbox AT THE END (placing it earlier makes drawio treat it as the input filename)\n\n# SVG export (final — -e is safe; SVG is text)\ndrawio -x -f svg -e -o diagram.svg input.drawio\n\n# PDF export (final)\ndrawio -x -f pdf -e -o diagram.pdf input.drawio\n\n# Custom output directory (e.g. CI artifacts dir) — create if missing, then export there\nmkdir -p ./artifacts && drawio -x -f png -e -s 2 -o ./artifacts/diagram.drawio.png input.drawio",{"_233":420,"_421":426},"python3 /scripts/repair_png.py diagram.drawio.png","skillMd","# Draw.io Diagrams\n\n## Overview\n\nGenerate `.drawio` XML files and export to PNG/SVG/PDF/JPG locally using the native draw.io desktop app CLI.\n\n**Supported formats:** PNG, SVG, PDF, JPG — no browser automation needed.\n\nPNG, SVG, and PDF exports support `--embed-diagram` (`-e`) — the exported file contains the full diagram XML, so opening it in draw.io recovers the editable diagram. Use double extensions (`name.drawio.png`) to signal embedded XML.\n\n## When to use / when NOT to use\n\n**Use this skill for:** polished, precise diagrams (architecture, network, strict UML, ERD), anything needing solid opaque fills, 10,000+ stock/branded shapes, swimlanes, or custom geometry, exported as editable PNG/SVG/PDF.\n\n**Do NOT use it — route elsewhere — for:**\n\n- A casual hand-drawn / whiteboard look → **excalidraw** or **tldraw**.\n- Diagrams-as-code that live in git / render in Markdown → **mermaid** (general) or **plantuml** (UML).\n- Freeform infinite-canvas sketching or freehand strokes → **tldraw**.\n\n## Bundled resources\n\nWhen the workflow references one of these, read it on demand — none of them need to be in context up front.\n\n| File | Read it when |\n| --- | --- |\n| `references/toolbox.md` | You're **not sure which bundled script fits** a request, or want to chain several — a map of all 31 scripts grouped by use-case (author / import code / import IaC / import API spec / live infra / compare / annotate / reverse-export / utilities) with an \"I have X, I want Y → use Z\" guide |\n| `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 |\n| `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 |\n| `references/diagram-types.md` | The user names a specific diagram type (ERD, UML class, sequence, C4, architecture, ML/DL, flowchart, SysML, BPMN, network topology, swimlane) |\n| `references/shapes.md` + `scripts/shapesearch.py` | The diagram needs a **specific shape** — a cloud icon (AWS/Azure/GCP), Cisco/Kubernetes/network symbol, UML/BPMN/ER/electrical/P&ID element — or any time you'd otherwise guess a `style=` string. `shapesearch.py \"\"` returns the exact official style for 10k+ shapes |\n| `scripts/aiicons.py` | The diagram involves an **AI/LLM brand** (OpenAI, Claude, Gemini, Mistral, Llama, HuggingFace, Ollama, LangChain, …) — `aiicons.py \"\"` returns a draw.io `image` style for the brand logo (lobe-icons via CDN; `--embed` to inline). draw.io has no built-in AI logos. See `references/shapes.md` → \"AI / LLM brand logos\" |\n| `references/style-presets.md` | The user asks to learn / save / list / set-default / delete a style preset, or you've resolved an active preset and need the application rules |\n| `references/style-extraction.md` | You're inside the Learn flow and need the extraction procedure (called from `style-presets.md`) |\n| `references/troubleshooting.md` | An export fails, vision rejects a PNG, or a rendering looks wrong |\n| `scripts/repair_png.py` | After every `-e` PNG export — fixes draw.io's truncated IEND chunk (issue #8) |\n| `scripts/encode_drawio_url.py` | The CLI is unavailable and you need a browser-fallback diagrams.net URL (`--edit` for an editable editor URL) |\n| `references/autolayout.md` | The diagram is large or layout-heavy (dependency/call graph, code structure, >~15 nodes) and you want Graphviz to place nodes + route edges instead of hand-placing coordinates |\n| `scripts/pyimports.py` · `jsimports.py` · `goimports.py` · `rustimports.py` | The user wants to visualize a **Python, JS/TS, Go, or Rust project** structure — extracts the import graph (transitive-reduced, optional `--group` containers, nested by sub-package) for autolayout |\n| `scripts/pyclasses.py` | The user wants a **Python class hierarchy / class diagram** — extracts classes + inheritance edges (boxed by module with `--group`) for autolayout |\n| `scripts/tfimports.py` · `k8simports.py` · `composeimports.py` | The user wants to visualize **declared** infrastructure (**Terraform** `.tf`, **Kubernetes** manifests, or **docker-compose**) — extracts the resource/service reference graph (official AWS/Azure/GCP/K8s icons for tf/k8s; service boxes + volume cylinders for compose) for autolayout |\n| `scripts/tfstate.py` · `dockerimports.py` (+ `k8simports.py`) | The user wants to draw **what is ACTUALLY running / deployed** — pipe `terraform show -json` (deployed state), `docker inspect $(docker ps -q)` (live containers), or `kubectl get all,ing,cm,secret,pvc -o json` (live cluster, via k8simports) and get the real topology with the same official icons. See `references/live-infra.md` |\n| `scripts/drawiodiff.py` | The user wants to **compare / diff two diagrams or two snapshots** (\"what changed\", infra drift) — `drawiodiff.py old.drawio new.drawio -o diff.json` emits a colour-coded graph (added=green, removed=red, changed=orange, same=grey) for autolayout. Matches by cell id (importer/live-snapshot output) or `--by-label` (hand-drawn) |\n| `scripts/timelapse.py` | The user wants an **architecture time-lapse / to see how a codebase's structure evolved over git history** — `timelapse.py --importer pyimports` re-runs an importer at each sampled commit and assembles a self-contained HTML player (embedded frames, play/step controls). Best on a package with real import edges (point `` at the module root) |\n| `scripts/explain.py` | The user wants to **describe / document / summarize an existing `.drawio` in words** (reverse of generating one) — `explain.py diagram.drawio` emits structured Markdown: components grouped by container/tier, relations (`A —label→ B`), per-page sections for multi-page/C4. Good for a README/PR summary or a text-only read-out |\n| `scripts/drawio2pptx.py` | The user wants a **PowerPoint deck / slides from a diagram** — `drawio2pptx.py diagram.drawio -o deck.pptx` puts each page on its own 16:9 slide (page name as title), so a multi-page **C4 model** becomes a ready-to-present deck. Needs `python-pptx` (`pip install python-pptx`) + the draw.io CLI |\n| `scripts/drawiohtml.py` | The user wants a **shareable interactive viewer** for a diagram (pan / zoom / search, no draw.io needed) — `drawiohtml.py diagram.drawio -o viewer.html` inlines every page's SVG into ONE self-contained HTML with page tabs, drag-pan, wheel-zoom, node search (Enter cycles + centres matches) and **working drill-down links** (a C4 model's `data:page/id` links switch tabs). No server, no external requests — send the file to anyone |\n| `scripts/svgflow.py` | The user wants an **animated / \"flowing\" diagram** (data-flow, moving edges) — `svgflow.py diagram.drawio -o flow.svg` exports to SVG and makes every edge a marching-ants animation (dashes travel along the arrows). Self-contained looping `.svg` that renders on GitHub / any browser; `--speed` / `--dash` / `--reverse` |\n| `scripts/drawio2mermaid.py` | The user wants to **convert a `.drawio` into Mermaid text** (diagrams-as-code for a Markdown file that GitHub renders) — `drawio2mermaid.py diagram.drawio` emits a `flowchart` (containers → `subgraph`s, edge labels kept, cylinder/rhombus shapes mapped); `--fenced` wraps in ```mermaid, multi-page → one graph per page. Structural only (styling/icons don't survive) |\n| `scripts/sqlerd.py` | The user wants an **ER diagram from SQL DDL** — parses `CREATE TABLE` statements into per-table nodes (columns with PK/FK markers) and crow's-foot FK edges for autolayout |\n| `scripts/ciimports.py` | The user wants a **CI pipeline diagram** (GitHub Actions workflows or GitLab CI) — `ciimports.py ` reads `.github/workflows/*.yml` + `.gitlab-ci.yml` and emits jobs (runner, matrix size, reusable-workflow calls), `needs:` dependency edges, per-workflow trigger nodes, and stage/workflow containers for autolayout. Needs PyYAML |\n| `scripts/openapiimports.py` | The user wants an **API diagram from an OpenAPI / Swagger spec** — `openapiimports.py spec.yaml` maps each operation to a node **coloured by HTTP method** (GET blue, POST green, PUT/PATCH orange, DELETE red) plus one node per component schema, with edges from operations to the schemas they use and between nested schemas. `--group` boxes by tag, `--no-schemas` shows just the endpoint surface; feeds autolayout |\n| `scripts/heatmap.py` | The user wants to **colour an existing `.drawio` by data** (a cost / latency / traffic / error-rate heat map) — `heatmap.py diagram.drawio -m metrics.csv` matches each metric (CSV `key,value` or JSON `{key:value}`) to a node by id or label and recolours it along a gradient (`--palette heat\\|cool\\|warm`, `--reverse`), optionally scaling node size (`--size`) and adding a legend. Post-processes any diagram; export as usual |\n| `scripts/seqlayout.py` | The user wants a **sequence diagram** — describe participants + messages as JSON and the script computes all lifeline/activation/arrow geometry deterministically (no hand-placed coordinates, no Graphviz needed) |\n| `scripts/c4.py` | The user wants a **C4 model** (System Context / Container / Component) — levels JSON in, one multi-page `.drawio` out with official C4 shapes/colors and **click-to-drill-down** links between levels |\n| `scripts/relabel.py` | The user wants a **language variant or bulk text swap of an existing `.drawio`** (e.g. an EN diagram re-labelled in Chinese for a bilingual README) — `relabel.py diagram.drawio --extract -o labels.json` dumps every label as an identity JSON map; translate the values (keep the keys), then `relabel.py diagram.drawio --map labels.json -o diagram_cn.drawio` swaps them with layout/styles/ids untouched |\n| `scripts/restyle.py` | The user wants to **re-theme an EXISTING `.drawio`** (\"make this dark\", \"apply my corporate style to this diagram\") — `restyle.py diagram.drawio --preset ` remaps every vertex fill/stroke to the preset palette by hue, applies font/extras (dark fontColor, edge color, background), and leaves layout, shapes, and edge routing untouched. Presets resolve like Step 0 (user dir, then built-ins) |\n| `scripts/edgeports.py` | Edges **stack on top of each other where they meet a shape** — the usual swimlane/cross-functional complaint, and anywhere a node has several connections leaving the same side. `edgeports.py diagram.drawio` pins `exitX/exitY`+`entryX/entryY`: it picks the side of each node facing the other endpoint, then spreads that side's edges over evenly-spaced slots **ordered by the far endpoint's position**, so they keep their relative order instead of crossing. Resolves absolute coordinates through swimlane parents, skips ends you already pinned, and is idempotent. It is a **port assigner, not a router** — it separates lines at the shape boundary, it will not stop an edge crossing an unrelated shape mid-run (add waypoints for that) |\n| `scripts/validate.py` | You generated a `.drawio` (especially via autolayout or for a large hand-placed diagram) and want a fast deterministic structural lint (dangling edges, dup/reserved ids, broken parents, overlaps) before the vision self-check. `--score` prints a readability score for comparing layout variants |\n| `scripts/raster2drawio.py` | The user has an **image of a diagram** (whiteboard photo, legacy PNG, Visio screenshot) and wants an **editable `.drawio`** — read the image with your own vision, extract nodes/edges as JSON (schema + full workflow in `references/derasterize.md`), then `raster2drawio.py graph.json -o out.drawio` honours those coordinates/labels/shapes; nodes missing `x`/`y` fall back to `autolayout.py` placement |\n| `scripts/buildup.py` | The user wants a diagram to **build itself node-by-node** as a video/GIF (a construction time-lapse of ONE static diagram — distinct from `timelapse.py`'s git-history animation) — `buildup.py diagram.drawio` reveals cells in topological (dependency) order into a self-contained HTML player (play/pause/step/scrub); `--gif` also exports an animated GIF (needs Pillow). Needs the draw.io CLI |\n| `scripts/compress.py` | The user wants an **executive / boardroom summary of a big diagram** — collapses clusters (pure-Python label propagation, no networkx) into one labeled node each with aggregated inter-cluster edges, emitting a 2-page `.drawio` (exec view + click-to-drill-down into the full original). Claude can rename clusters semantically afterward. Needs Graphviz `dot` |\n| `scripts/runbook.py` | The user wants a flowchart/decision-tree `.drawio` turned into a **click-through triage app** (on-call runbook) — `runbook.py flow.drawio` reads the XML (no draw.io CLI needed) and emits a self-contained HTML runbook: current-step text, per-edge choice buttons, breadcrumb trail, Back/Restart, end-state on terminal nodes |\n| `scripts/prdiff.py` | You're setting up **automated PR diagram review** in CI — for every `.drawio` changed between two git refs it renders base/head/diff PNGs and emits a Markdown report; ships with a composite GitHub Action (`.github/actions/drawio-diff/`) that posts a sticky PR comment. See `references/pr-bot.md` |\n| `scripts/tubemap.py` | The user wants a **metro / subway / tube map** — a system, pipeline, or journey drawn as coloured transit lines with octilinear (H/V/45°) routing, white interchange circles, and station stops. Compose a metro JSON (lines = ordered stations on an integer grid, shared stations = interchanges), then `tubemap.py metro.json -o metro.drawio`. Stdlib-only; schema + the one grid rule in `references/tubemap.md` |\n\n## Prerequisites\n\nThe draw.io desktop app must be installed and the CLI accessible:\n\n**macOS sandbox / sandbox isolation note (e.g., codex.app):** In some sandboxed macOS environments, invoking the draw.io desktop CLI (even `drawio --version`) can crash the draw.io process or produce no output. If that happens, treat the CLI as **unavailable in this sandbox isolation** — do not keep retrying inside the sandbox. Prefer a **non-sandboxed host environment** (outside sandbox isolation) for any CLI export work, or use the browser fallback / XML-only outputs.\n\n```bash\n# macOS (Homebrew — recommended; CLI binary is `drawio`, not `draw.io`)\nbrew install --cask drawio\ndrawio --version\n\n# macOS (full path if not in PATH)\n/Applications/draw.io.app/Contents/MacOS/draw.io --version\n\n# Windows\n\"C:\\Program Files\\draw.io\\draw.io.exe\" --version\n\n# Linux\ndrawio --version\n```\n\nInstall draw.io desktop if missing:\n\n- macOS: `brew install --cask drawio` or download from \n- Windows: download installer from \n- Linux: download `.deb`/`.rpm` from — **do not use snap** (AppArmor sandbox denies secrets/keyring on servers, causes crash)\n\n## Workflow\n\nBefore starting the workflow, assess whether the user's request is specific enough. If key details are missing, ask 1-3 focused questions:\n\n- **Diagram type** — which preset? (ERD, UML, Sequence, Architecture, ML/DL, Flowchart, SysML, BPMN, Network, Swimlane, or general)\n- **Output format** — PNG (default), SVG, PDF, or JPG?\n- **Output location** — default is the user's working dir; honor any explicit path the user gives (e.g. \"put it in `./artifacts/`\"). Don't ask if they didn't mention one.\n- **Scope/fidelity** — how many components? Any specific technologies or labels?\n\nSkip clarification if the request already specifies these details or is clearly simple (e.g., \"draw a flowchart of X\").\n\n**Step 0 — Resolve active preset.** Determine which (if any) user-defined style preset applies to this generation.\n\n- Scan the user's message for a phrase that clearly names a style preset: \"use my `` style\", \"with my `` style\", \"in `` mode\", \"in the style of ``\". A bare `with ` does **not** count — \"draw a diagram with redis\" names a component, not a style. If a clear match is found → active preset = ``.\n- Else, check `~/.drawio-skill/styles/` for any file with `\"default\": true`. If found → active preset = that one.\n- Else → no preset active; fall through to the built-in color/shape/edge conventions for the rest of the workflow.\n\nLoad the preset JSON from `~/.drawio-skill/styles/.json`, falling back to `/styles/built-in/.json`. If the named preset exists in neither location, tell the user the name is unknown, list the available presets (user dir + built-in), and stop — do **not** silently fall back to defaults.\n\nWhen a preset loads successfully, mention it in the first line of the reply: *\"Using preset `` (confidence: ``).\"* See `references/style-presets.md` → \"Applying a preset\" for how the preset changes color/shape/edge/font decisions.\n\n1. **Check deps** — **resolve which name the binary has on this system** and use that name verbatim in every subsequent command in this workflow. Try in order: (a) `drawio --version` (the canonical name for Homebrew cask, jgraph `.deb`/`.rpm`, Arch AUR), (b) `draw.io --version` (older builds, some custom symlinks, some distro packages), (c) macOS `.app` direct: `/Applications/draw.io.app/Contents/MacOS/draw.io --version`, (d) Windows: `\"C:\\Program Files\\draw.io\\draw.io.exe\" --version`. The first one that prints a version is your binary; remember the exact path/name and substitute it for `drawio` in every export command below. **Do not copy the example commands verbatim if your binary is named differently** — the examples use `drawio` only because it's the most common. On macOS-Homebrew, `drawio` is just a thin wrapper script that execs `/Applications/draw.io.app/Contents/MacOS/draw.io` — they run the same engine, so candidate (c) is only needed when the `drawio` wrapper is absent (e.g. the app was installed by drag-and-drop without the cask). **Also note the major version** the command printed: **≥ 30** unlocks Mermaid→`.drawio` conversion and the ELK `--layout` pass (see `references/mermaid-authoring.md`); on **≤ 29** both are unavailable — `.mmd` input fails and `--layout` corrupts argument parsing — so never emit those flags there.\n2. **Plan** — identify shapes, relationships, layout (LR or TB), group by tier/layer\n3. **Generate** — produce the `.drawio` file, choosing the authoring mode: **(a) Mermaid → CLI convert** when the diagram is a standard type with no custom styling/icon needs **and** the CLI is ≥ v30 — write a `.mmd` and run `drawio -x -f xml -o .drawio .mmd`, see `references/mermaid-authoring.md` (structure only; layout comes free; never `--layout` afterwards). **(b) Hand-written XML** for custom styling, vendor icons, swimlanes, precise geometry — **read `references/xml-authoring.md` first** (skeleton, cell forms, palette, spacing rules). **(c) A bundled generator** for the data-driven cases below. **For large or layout-heavy diagrams (dependency/call graphs, code structure, >~15 nodes), don't hand-place** — describe the graph as JSON and run `python3 /scripts/autolayout.py graph.json -o .drawio` to compute node positions + orthogonal edge routing via Graphviz (see `references/autolayout.md`; add `--tune` to auto-pick the more readable direction). For a **Python / JS-TS / Go / Rust project**, the matching importer (`scripts/pyimports.py`, `jsimports.py`, `goimports.py`, or `rustimports.py`) extracts the import graph (transitive-reduced; add `--group` to box modules by sub-package, nested for deep trees) ready for autolayout; for a **Python class hierarchy**, `scripts/pyclasses.py` extracts classes + inheritance instead; for **Terraform / Kubernetes / docker-compose** (`scripts/tfimports.py`, `k8simports.py`, `composeimports.py`), the importer extracts the resource/service reference graph — tf/k8s nodes resolve to their official cloud icons automatically; to draw **what is actually running** rather than the declared config, pipe `terraform show -json` into `scripts/tfstate.py` or `docker inspect $(docker ps -q)` into `scripts/dockerimports.py` (`k8simports.py` already accepts live `kubectl get ... -o json`) — see `references/live-infra.md`; for an **ER diagram from SQL DDL**, `scripts/sqlerd.py` parses `CREATE TABLE` into table nodes + crow's-foot FK edges; for an **API diagram from an OpenAPI / Swagger spec**, `scripts/openapiimports.py` maps operations (coloured by HTTP method) + component schemas into a graph for autolayout; for a **CI pipeline diagram** (GitHub Actions / GitLab CI), `scripts/ciimports.py` extracts jobs, `needs:` edges, triggers, and stage/workflow containers. To turn any generated `.drawio` into a **metric heat map** — recolour nodes by a CSV/JSON of cost/latency/traffic/errors — run `python3 /scripts/heatmap.py .drawio -m metrics.csv` (matches on cell id or label; `--palette`, `--size`, legend). For a **sequence diagram**, skip autolayout entirely — describe participants + messages as JSON and run `python3 /scripts/seqlayout.py seq.json -o .drawio` (deterministic lifeline/activation/arrow geometry; see the script docstring for the JSON schema). For a **C4 model**, `python3 /scripts/c4.py c4.json -o .drawio` emits the full multi-page Context→Container→Component set with drill-down links (schema in the script docstring). For complex architecture diagrams with many visible edge labels, give labels `labelBackgroundColor=#ffffff;fontSize=11` and use edge geometry `x`/`y` offsets plus `` to move long labels into nearby whitespace instead of relying on draw.io's default midpoint placement. For hand-placed diagrams where edges cross shapes (architecture, network topology, deployment, UML), fix the routing in the XML — run `python3 /scripts/edgeports.py .drawio` to distribute stacked edges over each shape's perimeter automatically, then add `` waypoints or widen node spacing for any edge still crossing a shape mid-run (see `references/xml-authoring.md`). **No CLI flag reroutes edges without moving nodes**: every `--layout` preset is an ELK *node* layout that re-places vertices, and an unrecognised value opens a modal error dialog that hangs headless runs. draw.io's obstacle-avoiding router is editor-side only. After generating any `.drawio`, run `python3 /scripts/validate.py .drawio` for a fast structural lint (dangling edges, dup ids, overlaps) before exporting. Default output dir is the user's working dir; if the user specified an output path or directory (e.g. `./artifacts/`, `docs/images/`), use that instead — `mkdir -p` the target dir first. Apply the same dir choice to PNG/SVG/PDF exports in steps 4 and 7.\n4. **Export draft** — run CLI to produce a preview PNG. **Do NOT pass `-e`** at this step — the embedded `zTXt mxGraphModel` chunk it adds causes vision APIs (Claude included) to return 400 \"Could not process image\" in step 5. **Cap the preview width with `--width 2000` (not `-s 2`)** — Claude's vision API rejects images larger than 2576×2576px with \"Unable to resize image — dimensions exceed the 2576x2576px limit\", and `-s 2` on a medium-or-larger diagram easily overshoots that ceiling. Save the clean preview as `.png` (single extension). Embedding and full-resolution scale are for the final export only (step 7).\n5. **Self-check** — use the agent's built-in vision capability to read the exported PNG, catch obvious issues, auto-fix before showing user (requires a vision-enabled model such as Claude Sonnet/Opus). If reading the PNG returns a 400 / \"Could not process image\" error, you almost certainly exported with `-e` by mistake — re-export without `-e` and retry once. If it still fails, skip self-check and continue to step 6.\n6. **Review loop** — show image to user, collect feedback, apply targeted XML edits, re-export, repeat until approved\n7. **Final export** — re-export the approved version to all requested formats. Use `-e` here (PNG/SVG/PDF) so the deliverable stays editable in draw.io; save as `.drawio.png` to signal embedded XML. **For PNG with `-e`, run `python3 /scripts/repair_png.py .drawio.png` immediately after** — draw.io's CLI truncates the IEND chunk in `-e` PNG output (8 bytes missing), producing a corrupt file that vision APIs and strict PNG decoders reject (issue #8). Report file paths.\n\n**If `drawio --version` crashes or prints nothing (common in restricted macOS sandbox isolation like codex.app):**\n\n- Do not keep retrying CLI invocations inside the sandbox.\n- Skip steps 4, 5, 6, and 7 (CLI export + PNG-based review) and use **Browser fallback** (`scripts/encode_drawio_url.py`) or deliver the `.drawio` XML only.\n- If the user needs PNG/SVG/PDF outputs, ask them to run the export commands in a **non-sandboxed host environment** (outside sandbox isolation) and share the resulting files.\n\nEscalation rule:\n\n- If the binary exists on PATH (or known app path exists) but execution fails with abnormal exit, empty output, Electron startup failure, display/session error, or likely sandbox restriction, prefer one escalated retry before falling back.\n- If the binary is missing entirely, do not escalate just to search more aggressively; go to install guidance or fallback.\n\n### Step 5: Self-Check\n\nAfter exporting the draft PNG, use the agent's vision capability (e.g., Claude's image input) to read the image and check for these issues before showing the user. If the agent does not support vision, skip self-check and show the PNG directly.\n\n**Important:** the draft PNG read here must have been exported **without** `-e`. Draw.io's `-e` flag emits a PNG with a truncated IEND chunk (8 bytes of type+CRC missing) that the Anthropic vision API rejects with 400 \"Could not process image\" (issue #8). The simplest fix for the preview step is to skip `-e` entirely; the final export in step 7 keeps `-e` and runs the repair snippet. If you see the 400 error here, re-export without `-e` and retry once; if it still fails (any other reason), skip self-check and proceed to step 6.\n\n| Check | What to look for | Auto-fix action |\n| ------- | ----------------- | ----------------- |\n| Overlapping shapes | Two or more shapes stacked on top of each other | Shift shapes apart by ≥200px |\n| Clipped labels | Text cut off at shape boundaries | Increase shape width/height to fit label |\n| Missing connections | Arrows that don't visually connect to shapes | Verify `source`/`target` ids match existing cells |\n| Off-canvas shapes | Shapes at negative coordinates or far from the main group | Move to positive coordinates near the cluster |\n| Edge-shape overlap | An edge/arrow visually crosses through an unrelated shape | Add waypoints (``) to route around the shape, or increase spacing between shapes |\n| Stacked edges | Multiple edges overlap each other on the same path | Distribute entry/exit points across the shape perimeter (use different exitX/entryX values) |\n| Edge-label overlap | Edge text overlaps another label, line, or node in the exported PNG | Keep the label on the edge, add a white label background, and move it locally with edge geometry `x`/`y` offsets into adjacent whitespace |\n\n- Max **2 self-check rounds** — if issues remain after 2 fixes, show the user anyway\n- Re-export after each fix and re-read the new PNG\n\n### Step 6: Review Loop\n\nAfter self-check, show the exported image and ask the user for feedback.\n\n**Targeted edit rules** — for each type of feedback, apply the minimal XML change:\n\n| User request | XML edit action |\n| ------------- | ---------------- |\n| Change color of X | Find `mxCell` by `value` matching X, update `fillColor`/`strokeColor` in `style` |\n| Add a new node | Append a new `mxCell` vertex with next available `id`, position near related nodes |\n| Remove a node | Delete the `mxCell` vertex and any edges with matching `source`/`target` |\n| Move shape X | Update `x`/`y` in the `mxGeometry` of the matching `mxCell` |\n| Resize shape X | Update `width`/`height` in the `mxGeometry` of the matching `mxCell` |\n| Add arrow from A to B | Append a new `mxCell` edge with `source`/`target` matching A and B ids |\n| Change label text | Update the `value` attribute of the matching `mxCell` |\n| Change layout direction | **Full regeneration** — rebuild XML with new orientation |\n\n**Rules:**\n\n- For single-element changes: edit existing XML in place — preserves layout tuning from prior iterations\n- For layout-wide changes (e.g., swap LR↔TB, \"start over\"): regenerate full XML\n- Overwrite the same `{name}.png` (no `-e`) each iteration — do not create `v1`, `v2`, `v3` files. `-e` is reserved for the final export in step 7.\n- After applying edits, re-export and show the updated image\n- Loop continues until user says approved / done / LGTM\n- **Safety valve:** after 5 iteration rounds, suggest the user open the `.drawio` file in draw.io desktop for fine-grained adjustments\n\n### Step 7: Final Export\n\nOnce the user approves:\n\n- Export to all requested formats (PNG, SVG, PDF, JPG) — default to PNG if not specified\n- Report file paths for both the `.drawio` source file and exported image(s)\n- **Auto-launch:** offer to open the `.drawio` file in draw.io desktop for fine-tuning — `open diagram.drawio` (macOS), `xdg-open` (Linux), `start` (Windows)\n- Confirm files are saved and ready to use\n\n## Style Presets\n\nA **style preset** is a named JSON file capturing a user's visual preferences (palette, shapes, font, edges). When active, it fully replaces the built-in color/shape conventions in this skill.\n\n**Lookup order** when SKILL.md's Step 0 resolves a preset name:\n\n1. `~/.drawio-skill/styles/.json` — user presets (survive `git pull`)\n2. `/styles/built-in/.json` — shipped built-ins (`default`, `corporate`, `handdrawn`, `colorblind-safe`, `dark`)\n\nAlways lowercase the user-provided name before any file operation — the schema enforces lowercase.\n\n**For everything else — Learn flow (extracting a preset from a file), management ops (list/default/delete/rename), application rules (color lookup, shape keywords, edges, fonts, extras, interaction with diagram-type presets), and validation — read `references/style-presets.md`.** It's only needed when the user invokes those flows or when an active preset must be applied to the current generation.\n\n## Authoring .drawio XML\n\n**Before hand-writing any `.drawio` XML (step 3), read `references/xml-authoring.md`** — file skeleton, shape/edge cell forms, containers, connection-point distribution, color palette, and spacing/grid rules all live there. Skip it only when a bundled generator writes the XML for you (`autolayout.py` + importers, `seqlayout.py`).\n\nTwo rules worth stating even here: never reuse ids `0`/`1` (reserved root cells), and every edge `mxCell` needs a `` child — self-closing edge cells do not render.\n\n## Export\n\n### Commands\n\nThere are **two** export modes:\n\n- **Preview / self-check** (step 4 of the workflow) — no `-e`. Output `diagram.png`. Required for vision self-check; using `-e` here triggers a 400 \"Could not process image\" error from the vision API (issue #8).\n- **Final / deliverable** (step 7) — pass `-e`. Output `diagram.drawio.png`. The embedded XML keeps the file editable in draw.io.\n\n> All commands below write `drawio` as a placeholder for the binary you resolved in Step 1. If your binary is on PATH as `draw.io` (with dot — some older or distro-packaged installs), substitute `draw.io` throughout. If only the macOS `.app` or Windows `.exe` is available, use the full path variant shown a few lines down.\n\n```bash\n# Preview PNG (use this in step 4, before self-check) — NO -e, width-capped to stay under vision's 2576px ceiling\ndrawio -x -f png --width 2000 -o diagram.png input.drawio\n\n# Final PNG (step 7, after user approval) — WITH -e, double extension\ndrawio -x -f png -e -s 2 -o diagram.drawio.png input.drawio\n\n# macOS — full path (if not in PATH); preview / final variants\n/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png --width 2000 -o diagram.png input.drawio\n/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -e -s 2 -o diagram.drawio.png input.drawio\n\n# Windows\n\"C:\\Program Files\\draw.io\\draw.io.exe\" -x -f png -e -s 2 -o diagram.drawio.png input.drawio\n\n# Linux (headless — requires xvfb-run; on servers add HOME and --disable-gpu)\nexport HOME=${HOME:-/tmp}\nxvfb-run -a --server-args=\"-screen 0 1280x1024x24\" \\\n drawio -x -f png -e -s 2 -o diagram.drawio.png input.drawio --disable-gpu\n# Running as root (CI / Docker)? Append --no-sandbox AT THE END (placing it earlier makes drawio treat it as the input filename)\n\n# SVG export (final — -e is safe; SVG is text)\ndrawio -x -f svg -e -o diagram.svg input.drawio\n\n# PDF export (final)\ndrawio -x -f pdf -e -o diagram.pdf input.drawio\n\n# Custom output directory (e.g. CI artifacts dir) — create if missing, then export there\nmkdir -p ./artifacts && drawio -x -f png -e -s 2 -o ./artifacts/diagram.drawio.png input.drawio\n```\n\n### Post-export PNG repair (required after `-e` PNG export)\n\ndraw.io CLI truncates the IEND chunk when emitting `-e` PNGs — the file ends with the 4-byte IEND length field but the `IEND` type + CRC (8 bytes) are missing. Result: vision APIs return 400 \"Could not process image\" and strict PNG decoders error out. SVG/PDF are unaffected.\n\nRun this immediately after every `-e` PNG export:\n\n```bash\npython3 /scripts/repair_png.py diagram.drawio.png\n```\n\nThe script's `endswith(IEND)` guard makes it a no-op once draw.io fixes the bug upstream — safe to run unconditionally.\n\n**Key flags:**\n\n- `-x` — export mode (required)\n- `-f` — format: `png`, `svg`, `pdf`, `jpg`\n- `-e` — embed diagram XML in output (PNG, SVG, PDF) — exported file remains editable in draw.io. **Skip for the preview PNG used in step 5 self-check** — `-e` PNGs have a truncated IEND chunk that vision APIs reject (issue #8). For final PNG export, keep `-e` and run `scripts/repair_png.py` (see Post-export PNG repair). SVG/PDF unaffected.\n- `-s` — scale: `1`, `2`, `3` (2 recommended for final PNG; do NOT use for the step-4 preview — see `--width`)\n- `--width ` — target width in pixels (no short form; `-w` does **not** exist and silently breaks the input-file parser). Use `--width 2000` for the step-4 preview to keep the PNG under Claude's 2576×2576 vision ceiling. There's also a `--height ` flag for tall-narrow diagrams. Don't combine `--width` with `-s`.\n- `-o` — output file path; accepts any directory (e.g. `./artifacts/diagram.drawio.png`) — `mkdir -p` the target dir first. Use `.drawio.png` double extension when embedding.\n- `--layout ` — **CLI ≥ v30 only** — Post-generate layout pass on XML input. Accepts **only** the ELK presets `verticalFlow`, `horizontalFlow`, `verticalTree`, `horizontalTree`, `radialTree`, `organic`, or a JSON layout array — all of them re-place nodes as well as routing edges; alternative to `autolayout.py` when Graphviz is missing. **Any other value opens a modal `Unknown layout:` dialog that hangs a headless run** — there is no edge-routing-only mode on the CLI. Never combine with Mermaid-converted files (already laid out). On ≤ 29 this flag breaks argument parsing — don't emit it. See `references/mermaid-authoring.md`\n- `-b` — border width around diagram (default: 0, recommend 10)\n- `-t` — transparent background (PNG only)\n- `--page-index ` — export one page of a multi-page file. **1-based** in current drawio-desktop (verified on 29.7.8: `--page-index 2` exports the second page; older docs claimed 0-based). Default: first page. `--page-range 2..3` also works\n\n### Browser fallback (no CLI needed)\n\nWhen the draw.io desktop CLI is unavailable, generate a client-side URL:\n\n```bash\npython3 /scripts/encode_drawio_url.py input.drawio # read-only viewer\npython3 /scripts/encode_drawio_url.py --edit input.drawio # opens in the editor\n```\n\nDefault prints a `https://viewer.diagrams.net/...#R…` viewer URL; `--edit` prints a `https://app.diagrams.net/...#create=…` URL that opens straight into the editable editor. Either way the diagram XML is `encodeURIComponent`-encoded, deflate-compressed, and base64'd into the URL fragment — the fragment (after `#`) is never sent to the server, so nothing is uploaded. The `encodeURIComponent` step is mandatory: without it, any diagram containing a literal `%` or non-ASCII (e.g. CJK) label makes the browser throw \"URI malformed\" and the diagram never opens.\n\nOpen the URL with `open \"$URL\"` (macOS) / `xdg-open \"$URL\"` (Linux). On **WSL2 / Windows**, `cmd.exe` drops the `#fragment` — write a `.url` shortcut file and open that instead (see `references/troubleshooting.md` → \"WSL2 / Windows specifics\").\n\n### Fallback chain\n\nWhen tools are unavailable, degrade gracefully:\n\n| Scenario | Behavior |\n| ---------- | ---------- |\n| draw.io CLI missing, Python available | Use browser fallback (diagrams.net URL) |\n| draw.io CLI missing, Python missing | Generate `.drawio` XML only; instruct user to open in draw.io desktop or diagrams.net manually |\n| draw.io CLI crashes / no output in macOS sandbox isolation | Treat CLI as unavailable in-sandbox; use browser fallback / XML-only; ask user to run CLI exports in a non-sandboxed host environment |\n| Vision unavailable for self-check | Skip self-check (step 5); proceed directly to showing user the exported PNG |\n| Export fails (Chromium/display issues) | On Linux, retry with `xvfb-run -a`; if still failing, deliver `.drawio` XML and suggest manual export |\n| Export fails on Linux server (headless) | Try in order: (1) `xvfb-run -a`, (2) append `--no-sandbox` at the very end if root, (3) add `--disable-gpu`, (4) `export HOME=/tmp`, (5) install apt deps (`libgtk-3-0 libnotify4 libnss3 libgbm1 libasound2t64` etc.), (6) fall back to [tomkludy/drawio-renderer](https://hub.docker.com/r/tomkludy/drawio-renderer) Docker (REST API for headless export) |\n\n### Checking if drawio is in PATH\n\n```bash\n# Prefer the Homebrew / Linux-package binary name (no dot)\nif command -v drawio &>/dev/null; then\n DRAWIO=\"drawio\"\n# Fall back to the dot-named binary (older installs, manual symlinks)\nelif command -v draw.io &>/dev/null; then\n DRAWIO=\"draw.io\"\n# macOS .app bundle (binary inside the bundle keeps the dot)\nelif [ -f \"/Applications/draw.io.app/Contents/MacOS/draw.io\" ]; then\n DRAWIO=\"/Applications/draw.io.app/Contents/MacOS/draw.io\"\n# WSL2: the CLI is the Windows desktop exe, reached via /mnt/c (note the space)\nelif grep -qi microsoft /proc/version 2>/dev/null && [ -f \"/mnt/c/Program Files/draw.io/draw.io.exe\" ]; then\n DRAWIO=\"/mnt/c/Program Files/draw.io/draw.io.exe\"\nelse\n echo \"drawio not found — install from https://github.com/jgraph/drawio-desktop/releases (Homebrew: brew install --cask drawio)\"\nfi\n```\n\nOn **WSL2 / native Windows**, opening exported files and browser-fallback URLs needs path conversion + a `.url`-file workaround (`cmd.exe` drops URL `#fragment`s) — see the \"WSL2 / Windows specifics\" section in `references/troubleshooting.md`.\n\n## Common Mistakes\n\nWhen something looks wrong (export fails, vision rejects a PNG, layout broken, edges misroute), see `references/troubleshooting.md` for a row-by-row mistake → fix table.\n\n## Diagram Type Presets\n\nWhen the user requests a specific diagram type, read `references/diagram-types.md` for the matching preset (shapes, edges, layout direction). Pick by user phrasing:\n\n| User says | Section in `references/diagram-types.md` |\n| --- | --- |\n| \"ER diagram\", \"schema diagram\", \"data model\" | ERD |\n| \"UML class diagram\", \"class diagram\" | UML Class |\n| \"sequence diagram\", \"interaction diagram\", \"lifeline\" | Sequence |\n| \"architecture\", \"system diagram\", \"service diagram\" | Architecture |\n| \"neural network\", \"model architecture\", \"ML diagram\", \"deep learning\" | ML / Deep Learning Model |\n| \"flowchart\", \"decision tree\", \"process flow\" | Flowchart |\n| \"C4\", \"system context diagram\", \"container diagram\", \"component diagram\" | C4 Model |\n| \"SysML\", \"MBSE\", \"block definition diagram\", \"internal block diagram\", \"requirement diagram\", \"parametric diagram\" | SysML |\n| \"BPMN\", \"business process\", \"process model\", \"pool and lanes\", \"workflow diagram\" | BPMN |\n| \"network topology\", \"network diagram\", \"LAN/WAN\", \"subnet\", \"firewall diagram\" | Network Topology |\n| \"swimlane diagram\", \"cross-functional flowchart\", \"who does what\", \"handoff diagram\" | Cross-Functional Flowchart |\n\nThe diagram-type preset sets **structural** style keywords. If a user style preset is also active (see `## Style Presets`), keep the structural keywords and layer color/font/edge/extras on top — read `references/style-presets.md` → \"Interaction with diagram-type presets\" for the merge rules.","skillMdTruncated","frontmatter",{"_155":159,"_38":41,"_44":45,"_432":433,"_434":435,"_436":437,"_65":438},"compatibility","Requires draw.io desktop app CLI on PATH (macOS/Linux/Windows). Self-check step requires a vision-enabled model (e.g., Claude Sonnet/Opus); gracefully skipped if unavailable. Optional auto-layout (scripts/autolayout.py) needs Graphviz (dot).","version","2.1.0","homepage","https://github.com/Agents365-ai/drawio-skill",[439,440,441],"macos","linux","windows","totalSizeBytes",916585,"runtime",{"_446":7,"_447":31,"_448":-5,"_449":31,"_450":31,"_451":7,"_452":453,"_454":455},"requiresBash","requiresMcp","model","requiresNode","requiresNetwork","requiresPython","allowedTools",[],"dependencies",[],"install",{"_458":459,"_460":461,"_462":463,"_464":465,"_466":467},"cli","npx skills add agents365-ai/drawio-skill/drawio-skill","coordinate","agents365-ai/drawio-skill/drawio-skill","browseUrl","https://github.com/agents365-ai/drawio-skill/tree/main/skills/drawio-skill","downloadUrl","https://github.com/agents365-ai/drawio-skill/archive/refs/heads/main.zip","gitUrl","https://github.com/agents365-ai/drawio-skill.git","createdAt","2026-08-11T01:22:32.966Z","updatedAt","2026-08-20T17:45:46.794Z","hasNext","page","actionData","errors"]