# Draw Io > Create, edit, export, and review draw.io diagrams. Use for native .drawio XML generation, PNG/SVG/PDF export, SVG overlap, border-overlap, label-intrusion, label-rect, short-terminal, text-contrast, text-emphasis, and text-overflow linting, layout adjustment, and AWS icon usage. - **Type:** Skill - **Install:** `agentstack add skill-sunwood-ai-labs-draw-io-skill-draw-io-skill` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Sunwood-ai-labs](https://agentstack.voostack.com/s/sunwood-ai-labs) - **Installs:** 0 - **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Sunwood-ai-labs](https://github.com/Sunwood-ai-labs) - **Source:** https://github.com/Sunwood-ai-labs/draw-io-skill - **Website:** https://sunwood-ai-labs.github.io/draw-io-skill/ ## Install ```sh agentstack add skill-sunwood-ai-labs-draw-io-skill-draw-io-skill ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # draw.io Diagram Skill ## 1. Purpose Use this skill when an agent needs to: - create a new draw.io diagram as native `.drawio` XML - edit or refactor an existing `.drawio` file - export diagrams to `png`, `svg`, `pdf`, or `jpg` - check routed edges, box- or frame-border overlap, supported non-rect shape border overlap, box penetration, short arrowhead tails, label collisions, weak text contrast, flat dark-card text treatment, or text overflow - build architecture diagrams with AWS icons This skill intentionally combines: - the native draw.io assistant workflow used by Claude Code style tools - practical XML editing and layout rules from repository use - repository-ready SVG linting that catches issues draw.io does not flag ### 1.1 Repository structure The repository layout and bundled workflow pieces are summarized in the diagram below. The repository also ships: - an English structure source and exports under `assets/draw-io-skill-structure.drawio*` - an icon block showcase under `assets/draw-io-skill-structure-icons.drawio*` plus a Japanese-localized companion under `assets/draw-io-skill-structure-icons.ja.drawio*` - a shape-focused lint review sample under `assets/draw-io-skill-structure-shapes.drawio` with exports at `assets/draw-io-skill-structure-shapes.drawio.png` and `assets/draw-io-skill-structure-shapes.drawio.svg` - a Japanese-localized companion source and exports under `assets/draw-io-skill-structure.ja.drawio*` - default visual templates and style tokens under `references/aesthetic-templates.md` - an editable polished visual template sample under `assets/aesthetic-template-sample.drawio` - three professional-grade sample templates under `assets/aesthetic-sample-executive-dashboard.drawio`, `assets/aesthetic-sample-ai-pipeline.drawio`, and `assets/aesthetic-sample-security-incident.drawio` - three purpose-driven templates with distinct existence reasons under `assets/purpose-board-brief-template.drawio`, `assets/purpose-dependency-orbit-template.drawio`, and `assets/purpose-incident-timeline-template.drawio` - three additional purpose-driven templates under `assets/purpose-hypothesis-helix-template.drawio`, `assets/purpose-feature-value-matrix-template.drawio`, and `assets/purpose-value-conversion-sheet-template.drawio` - public showcase pages under `docs/guide/showcase.md` and `docs/ja/guide/showcase.md` - fixture-based lint coverage under `fixtures/basic`, `fixtures/border-overlap`, `fixtures/large-frame-border-overlap`, `fixtures/shape-border-overlap`, `fixtures/label-rect-overlap`, `fixtures/text-cell-overflow`, `fixtures/text-contrast`, `fixtures/text-emphasis`, and `fixtures/shape-text-overflow` ### 1.2 Repository-local commands When working inside this repository, these are the main maintenance commands: ```sh npm install npm run check npm run verify npm ci npm run docs:build npm run docs:dev uv run python -m py_compile scripts/find_aws_icon.py ``` Use them this way: - `npm run check`: script syntax plus fixture-based lint verification - `npm run verify`: full repository signoff, including docs build - `npm run docs:build`: one-shot docs build - `npm run docs:dev`: interactive docs preview If you need to attach the repo as a skill in a local assistant environment, the repository docs use these conventions: - Codex on Windows: junction `C:\Users\YOUR_NAME\.codex\skills\draw-io -> D:\Prj\draw-io-skill` - Claude Code: clone under `~/.claude/skills/drawio` ### 1.3 Repository QA model The repository uses three QA layers: 1. syntax checks for the JavaScript tools 2. fixture-based lint verification 3. documentation build validation for the public-facing docs That keeps the technical tooling and the user-facing docs aligned in CI. ## 2. Default Workflow Follow this order unless the user asks for something narrower: 1. Create or update the native `.drawio` file first. 2. When creating a diagram from scratch and the user did not specify a visual style, start from `references/aesthetic-templates.md`; default to the polished technical light template instead of draw.io's plain box defaults. 3. Keep `.drawio` as the editable source of truth for repository work. 4. If the user asked for an exported artifact, export to `.drawio.png`, `.drawio.svg`, `.drawio.pdf`, or `.drawio.jpg`. 5. Before showing, attaching, or claiming a diagram is ready, export an SVG and run the lint script. 6. If the draw.io CLI is unavailable, do not silently skip linting. Create or locate the expected companion `*.drawio.svg` if possible, run the lint script, and explicitly report any reduced coverage such as `parsed 0 edges`; then run a manual or scripted geometry sanity check for arrows, labels, and box intrusions before surfacing the image. 7. Open or surface the final artifact requested by the user only after linting and visual verification. 8. Even when lint passes, visually verify the result. 9. If the lint output reports reduced coverage such as `parsed 0 edges`, inspect the exported PNG/SVG image itself before finalizing. Do not claim the diagram is clean while visible rendered text, line labels, arrows, or routes overlap; fix the rendered artifact and rerun the lint plus visual inspection. If the user only asks for a diagram and does not request a format, stop at the `.drawio` file. ## 3. Basic Rules - Edit only `.drawio` files directly. - Do not manually edit generated `.drawio.png`, `.drawio.svg`, or `.drawio.pdf` files. - Prefer native mxGraphModel XML over Mermaid or CSV conversions. - Keep source diagrams unless the user explicitly wants embedded-only cleanup after export. - Use descriptive lowercase filenames with hyphens. Examples: - `login-flow.drawio` - `login-flow.drawio.png` - `er-diagram.drawio.svg` - `architecture-overview.drawio.pdf` ## 4. Output Formats | Format | Embedded XML | Recommended use | |--------|--------------|-----------------| | `.drawio` | n/a | Editable source diagram | | `png` | Yes | Docs, slides, chat attachments | | `svg` | Yes | Docs, scalable output, lint input | | `pdf` | Yes | Review and print | | `jpg` | No | Last-resort lossy export | For repository workflows, prefer: - `.drawio` while editing - `.drawio.svg` when running lint - `.drawio.png` or `.drawio.svg` for documentation embeds ## 5. Export Commands ### 5.1 Preferred export helper Use the bundled helper first: ```sh node scripts/export-drawio.mjs architecture.drawio --format png --open node scripts/export-drawio.mjs architecture.drawio --format svg node scripts/export-drawio.mjs architecture.drawio --output architecture.drawio.pdf ``` What it does: - locates the draw.io CLI on Windows, macOS, or Linux - uses embedded XML for `png`, `svg`, and `pdf` - defaults to transparent 2x PNG export - supports explicit `--drawio ` when automatic CLI discovery fails - supports optional `--delete-source` when the user explicitly wants only the embedded export If draw.io CLI discovery fails, rerun with an explicit executable path: ```sh node scripts/export-drawio.mjs architecture.drawio --drawio "C:\\Program Files\\draw.io\\draw.io.exe" --format svg ``` On macOS or Linux, point `--drawio` at the installed executable for that environment. ### 5.2 Manual draw.io CLI export If needed, call draw.io directly: ```sh drawio -x -f png -e -s 2 -t -b 10 -o architecture.drawio.png architecture.drawio drawio -x -f svg -e -b 10 -o architecture.drawio.svg architecture.drawio drawio -x -f pdf -e -b 10 -o architecture.drawio.pdf architecture.drawio drawio -x -f jpg -b 10 -o architecture.drawio.jpg architecture.drawio ``` Key flags: - `-x`: export mode - `-f`: output format - `-e`: embed diagram XML in png/svg/pdf - `-o`: output file path - `-b`: border width - `-t`: transparent background for PNG - `-s`: scale factor - `-a`: all pages for PDF - `-p`: page index (1-based) ### 5.3 Legacy PNG helper For existing shell workflows, the original helper remains available: ```sh bash scripts/convert-drawio-to-png.sh architecture.drawio ``` ## 6. SVG Linting Linting is a required preflight before presenting a diagram to the user or embedding it in docs/articles. Do not wait for the user to ask whether lint was run. After exporting SVG, run the bundled lint: ```sh node scripts/check-drawio-svg-overlaps.mjs architecture.drawio.svg node scripts/check-drawio-svg-overlaps.mjs fixtures/border-overlap/border-overlap.drawio.svg node scripts/check-drawio-svg-overlaps.mjs fixtures/large-frame-border-overlap/large-frame-border-overlap.drawio.svg node scripts/check-drawio-svg-overlaps.mjs fixtures/shape-border-overlap/shape-border-overlap.drawio.svg node scripts/check-drawio-svg-overlaps.mjs fixtures/label-rect-overlap/label-rect-overlap.drawio node scripts/check-drawio-svg-overlaps.mjs fixtures/text-cell-overflow/text-cell-overflow.drawio node scripts/check-drawio-svg-overlaps.mjs fixtures/text-contrast/text-contrast.drawio node scripts/check-drawio-svg-overlaps.mjs fixtures/text-emphasis/text-emphasis.drawio ``` The lint script currently checks: - `edge-edge`: edge crossings and collinear overlaps - `edge-rect-border`: lines that run along or visibly overlap a box or large frame border - `edge-shape-border`: lines that run along supported non-rect shape borders such as `document`, `hexagon`, `parallelogram`, and `trapezoid` - `edge-rect`: lines penetrating boxes - `edge-terminal`: final arrow runs that are too short after the last bend - `edge-label`: routed lines crossing label text boxes - `label-rect`: label text boxes colliding with another box or card - `rect-shape-border`: box or frame borders that run along those supported non-rect shape borders - `text-contrast`: text whose font color is too close to its fill color for the current font size - `text-emphasis`: compact dark cards whose title/body copy is still flattened into a single dense text block - `text-overflow(width)`: text likely too wide for its box - `text-overflow(height)`: text likely too tall for its box Notes: - input may be either `.drawio` or `.drawio.svg` - when the input is `.drawio`, the checker also reads the companion draw.io geometry so `label-rect` and text-fit checks stay aligned with the editable source - when the input is `.drawio`, a companion `same-name.drawio.svg` is expected for routed-edge checks; if it is missing, export it first instead of treating the failure as non-actionable - if the checker reports `parsed 0 edges`, the SVG did not provide usable edge geometry; report that limitation and supplement with visual inspection or a small coordinate/geometry check for arrow-label overlap, arrow-box intrusion, and text overflow - never claim a diagram is final based only on visual review when the lint script was skipped or failed to inspect edges - `text-contrast` currently requires explicit hex `fillColor` and `fontColor` - text overflow detection is heuristic, not pixel-perfect - bundled fixtures cover simple box-border overlap, large frame-border overlap, supported non-rect shape border overlap, label-box collisions, text-cell overflow, low-contrast text, dense dark-card copy, and shape-aware text overflow - `edge-terminal`, `edge-label`, `label-rect`, and `text-emphasis` are heuristic checks intended to catch the common "tiny arrowhead tail", "line through label", "note card covering a label", and "dark card text visually blending together" draw.io failures seen in repository diagrams - lint passing does not replace visual verification When investigating findings: - if `edge-rect-border`, `edge-shape-border`, or `rect-shape-border` is intentional, keep the routing obvious, visually review the output, and document the exception in the surrounding workflow - if `edge-terminal` fires, add a longer straight segment before the arrowhead or move the last bend farther away from the target - if `edge-label` fires, reroute the edge or move the label so the text keeps clean breathing room - if `label-rect` fires, move the note/card/box or shift the label so they no longer partially overlap - if `text-contrast` fires, increase foreground/background contrast instead of relying on opacity, texture, or stroke - if `text-emphasis` fires, split the title from the body with a chip, separate text cell, stronger hierarchy, or more breathing room - if `text-overflow` looks like a false positive, first try widening the box, shortening the label, adding an intentional line break, or setting explicit fonts ## 7. XML And Layout Rules ### 7.0 Visual template selection For new diagrams, choose a visual template before writing the XML. If the user gives no style direction, use the polished technical light template from `references/aesthetic-templates.md`. Minimum visual baseline: - explicit `fontFamily=Noto Sans JP` for Japanese or mixed Japanese/English diagrams - explicit fill, stroke, and font colors; avoid default gray draw.io styling - rounded cards with restrained borders and enough internal padding - clear title/body hierarchy instead of one dense text block - one or two accent colors only, with adequate contrast - orthogonal routed connectors with enough terminal room near arrowheads If a diagram passes lint but still looks visually plain, revise hierarchy, spacing, and palette before presenting it. ### 7.1 Required XML structure Every diagram must use native mxGraphModel XML: ```xml ``` All normal diagram cells should live under `parent="1"` unless you intentionally use container parents. ### 7.2 Edge geometry is mandatory Every edge cell must contain geometry: ```xml ``` Never use self-closing edge cells. ### 7.3 Font settings For diagrams with Japanese text or slide usage, set the font family explicitly: ```xml ``` Also set `fontFamily` in text styles: ```xml style="text;html=1;fontSize=18;fontFamily=Noto Sans JP;" ``` ### 7.4 Spacing and routing - space nodes generously; prefer about 200px horizontal and 120px vertical gaps for routed diagrams - leave at least 20px of straight segment near arrowheads - use `edgeStyle=orthogonalEdgeStyle` for most technical diagrams - add explicit waypoints when auto-routing produces overlap or awkward bends - when using large outer frames or swimlanes, keep routed segments off the frame stroke and use the gutter between the frame and child boxes instead - align to a coarse grid when possible Example with waypoints: ```xml ``` ### 7.5 Containers and groups Do not fake containment by simply placing boxes on top of bigger boxes. - use `parent="containerId"` for child elements - use `swimlane` when the container needs a visible title bar - use `group;pointerEvents=0;` for invisible containers - add `container=1;pointerEvents=0;` when using a custom shape as a container ### 7.6 Japanese text width Allow roughly 30 to 40px per Japanese character. ```xml ``` If text is mixed Japanese and English, err on the wider side. ### 7.7 Backgrounds, frames, and margins - prefer transparent backgrounds over hard-coded white backgrounds - inside rounded frames or swimlanes, keep at least 30px margin from the boundary - account for stroke width and rounded corners - verify that titles and labels do not sit too close to frame edges ### 7.8 Labels and line breaks - use one line for short service names when possible - use `<br>` for intentional two-line labels - shorten redundant wording instead of forcing cramped boxes ### 7.9 Metadata and progressive disclosure When appropriate, include title, description, last updated, author, or version. Split complex systems into multiple diagrams when one canvas becomes dense: - context diagram - system diagram - component diagram - deployment diagram - data flow diagram - sequence diagram ## 8. AWS Icon Workflow When working on AWS diagrams: - use the latest official icon naming where possible - prefer current `mxgraph.aws4.*` icon references - remove decorative icons that do not add meaning Search icons with: ```sh uv run python scripts/find_aws_icon.py ec2 uv run python … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Sunwood-ai-labs](https://github.com/Sunwood-ai-labs) - **Source:** [Sunwood-ai-labs/draw-io-skill](https://github.com/Sunwood-ai-labs/draw-io-skill) - **License:** MIT - **Homepage:** https://sunwood-ai-labs.github.io/draw-io-skill/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-sunwood-ai-labs-draw-io-skill-draw-io-skill - Seller: https://agentstack.voostack.com/s/sunwood-ai-labs - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.