draw-io
Skill49 starsChanged 8 months agoMITView on GitHub
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.
- Installs packages
7 other projects use a version of this.
Adopted by
Most recently taken up by
- 0xsarwagya/agent-skills-alycdtheir own version, first seen Nov 8, 2026
- JustinWangJP/cc-agent-teams-action-monitortheir own version, first seen Nov 8, 2026
- imMamdouhaboammar/kaku-chatgpt-harnesstheir own version, first seen Oct 25, 2026
- alycd/agent-skillstheir own version, first seen Oct 20, 2026
- Samueladewole/claude-skillstheir own version, first seen Oct 13, 2026
- nbirkner/digital-braintheir own version, first seen Apr 12, 2026
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- JustinWangJP/cc-agent-teams-action-monitor★ 6same name
- huminglong/my_claude_skills★ 1same name
- 0xsarwagya/agent-skills-alycd★ 0same name
- alycd/agent-skills★ 0same name
- imMamdouhaboammar/kaku-chatgpt-harness★ 0same name
- nbirkner/digital-brain★ 0same name
- Samueladewole/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
58 rules. 0 are common, 31 are distinctive, and 27 are very specific to this project.
0
Common
Most of the 7 edited versions we read keep these.
31
Distinctive
This author's own choices. Worth a look.
27
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 10
Use this skill when an agent needs to:
- Very specific: line 12
create a new draw.io diagram as native .drawio XML
- Distinctive: line 15
check routed edges, box- or frame-border overlap, supported non-rect shape border overlap, box penetration, short arrowhead tails, label …
- Very specific: line 36
default visual templates and style tokens under references/aesthetic-templates.md
- Distinctive: line 46
When working inside this repository, these are the main maintenance commands:
- Distinctive: line 58
Use them this way:
- Distinctive: line 65
If you need to attach the repo as a skill in a local assistant environment, the repository docs use these conventions:
- Distinctive: line 82
Follow this order unless the user asks for something narrower:
- Very specific: line 84
Create or update the native .drawio file first.
- Very specific: line 85
When creating a diagram from scratch and the user did not specify a visual style, start from references/aesthetic-templates.md.
- Very specific: line 86
Keep .drawio as the editable source of truth for repository work.
- Very specific: line 87
If the user asked for an exported artifact, export to .drawio.png, .drawio.svg, .drawio.pdf, or .drawio.jpg.
- Distinctive: line 88
Before showing, attaching, or claiming a diagram is ready, export an SVG and run the lint script.
- Very specific: line 94
If the user only asks for a diagram and does not request a format, stop at the .drawio file.
- Very specific: line 99
Do not manually edit generated .drawio.png, .drawio.svg, or .drawio.pdf files.
- Distinctive: line 100
Prefer native mxGraphModel XML over Mermaid or CSV conversions.
- Distinctive: line 101
Keep source diagrams unless the user explicitly wants embedded-only cleanup after export.
- Distinctive: line 102
Use descriptive lowercase filenames with hyphens.
- Distinctive: line 131
Use the bundled helper first:
- Distinctive: line 147
If draw.io CLI discovery fails, rerun with an explicit executable path:
- Distinctive: line 157
If needed, call draw.io directly:
- Distinctive: line 190
After exporting SVG, run the bundled lint:
- Very specific: line 221
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 …
- Very specific: line 222
when the input is .drawio, a companion same-name.drawio.svg is expected for routed-edge checks.
- Very specific: line 223
if the checker reports parsed 0 edges, the SVG did not provide usable edge geometry.
- Distinctive: line 224
never claim a diagram is final based only on visual review when the lint script was skipped or failed to inspect edges
- Very specific: line 233
if edge-rect-border, edge-shape-border, or rect-shape-border is intentional, keep the routing obvious, visually review the output, and …
- Very specific: line 234
if edge-terminal fires, add a longer straight segment before the arrowhead or move the last bend farther away from the target
- Very specific: line 235
if edge-label fires, reroute the edge or move the label so the text keeps clean breathing room
- Very specific: line 236
if label-rect fires, move the note/card/box or shift the label so they no longer partially overlap
- Very specific: line 237
if text-contrast fires, increase foreground/background contrast instead of relying on opacity, texture, or stroke
- Very specific: line 238
if text-emphasis fires, split the title from the body with a chip, separate text cell, stronger hierarchy, or more breathing room
- Very specific: line 239
if text-overflow looks like a false positive, first try widening the box, shortening the label, adding an intentional line break, or …
- Distinctive: line 256
If a diagram passes lint but still looks visually plain, revise hierarchy, spacing, and palette before presenting it.
- Distinctive: line 260
Every diagram must use native mxGraphModel XML:
- Very specific: line 271
All normal diagram cells should live under parent="1" unless you intentionally use container parents.
- Distinctive: line 275
Every edge cell must contain geometry:
- Distinctive: line 283
Never use self-closing edge cells.
- Distinctive: line 302
leave at least 20px of straight segment near arrowheads
- Very specific: line 303
use edgeStyle=orthogonalEdgeStyle for most technical diagrams
- Distinctive: line 304
add explicit waypoints when auto-routing produces overlap or awkward bends
- Distinctive: line 305
when using large outer frames or swimlanes, keep routed segments off the frame stroke and use the gutter between the frame and child boxes …
- Distinctive: line 323
Do not fake containment by simply placing boxes on top of bigger boxes.
- Very specific: line 325
use parent="containerId" for child elements
- Very specific: line 326
use swimlane when the container needs a visible title bar
- Very specific: line 327
use group;pointerEvents=0.
- Very specific: line 328
add container=1;pointerEvents=0.
- Distinctive: line 338
If text is mixed Japanese and English, err on the wider side.
- Distinctive: line 342
prefer transparent backgrounds over hard-coded white backgrounds
- Distinctive: line 345
verify that titles and labels do not sit too close to frame edges
- Distinctive: line 349
use one line for short service names when possible
- Very specific: line 350
use <br> for intentional two-line labels
- Distinctive: line 355
When appropriate, include title, description, last updated, author, or version.
- Distinctive: line 368
When working on AWS diagrams:
- Distinctive: line 370
use the latest official icon naming where possible
- Very specific: line 371
prefer current mxgraph.aws4.* icon references
- Distinctive: line 372
remove decorative icons that do not add meaning
- Very specific: line 420
if GitHub Pages styling breaks after a repo rename, verify the VitePress base still matches /draw-io-skill/
“Common” is measured: kept by at least 6 in 10 of the 7 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
draw.io Diagram Skill
1. Purpose
Use this skill when an agent needs to:
- create a new draw.io diagram as native
.drawioXML - edit or refactor an existing
.drawiofile - export diagrams to
png,svg,pdf, orjpg - 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.
Image: draw-io-skill structure
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 underassets/draw-io-skill-structure-icons.ja.drawio* - a shape-focused lint review sample under
assets/draw-io-skill-structure-shapes.drawiowith exports atassets/draw-io-skill-structure-shapes.drawio.pngandassets/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, andassets/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, andassets/purpose-incident-timeline-template.drawio - three additional purpose-driven templates under
assets/purpose-hypothesis-helix-template.drawio,assets/purpose-feature-value-matrix-template.drawio, andassets/purpose-value-conversion-sheet-template.drawio - public showcase pages under
docs/guide/showcase.mdanddocs/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, andfixtures/shape-text-overflow
1.2 Repository-local commands
When working inside this repository, these are the main maintenance commands:
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.pyUse them this way:
npm run check: script syntax plus fixture-based lint verificationnpm run verify: full repository signoff, including docs buildnpm run docs:build: one-shot docs buildnpm 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:
- syntax checks for the JavaScript tools
- fixture-based lint verification
- 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:
- Create or update the native
.drawiofile first. - 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. - Keep
.drawioas the editable source of truth for repository work. - If the user asked for an exported artifact, export to
.drawio.png,.drawio.svg,.drawio.pdf, or.drawio.jpg. - Before showing, attaching, or claiming a diagram is ready, export an SVG and run the lint script.
- If the draw.io CLI is unavailable, do not silently skip linting. Create or locate the expected companion
*.drawio.svgif possible, run the lint script, and explicitly report any reduced coverage such asparsed 0 edges; then run a manual or scripted geometry sanity check for arrows, labels, and box intrusions before surfacing the image. - Open or surface the final artifact requested by the user only after linting and visual verification.
- Even when lint passes, visually verify the result.
- 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
.drawiofiles directly. - Do not manually edit generated
.drawio.png,.drawio.svg, or.drawio.pdffiles. - 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.drawiologin-flow.drawio.pnger-diagram.drawio.svgarchitecture-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:
.drawiowhile editing.drawio.svgwhen running lint.drawio.pngor.drawio.svgfor documentation embeds
5. Export Commands
5.1 Preferred export helper
Use the bundled helper first:
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.pdfWhat it does:
- locates the draw.io CLI on Windows, macOS, or Linux
- uses embedded XML for
png,svg, andpdf - defaults to transparent 2x PNG export
- supports explicit
--drawio <path>when automatic CLI discovery fails - supports optional
--delete-sourcewhen the user explicitly wants only the embedded export
If draw.io CLI discovery fails, rerun with an explicit executable path:
node scripts/export-drawio.mjs architecture.drawio --drawio "C:\\Program Files\\draw.io\\draw.io.exe" --format svgOn 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:
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.drawioKey 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:
bash scripts/convert-drawio-to-png.sh architecture.drawio6. 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:
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.drawioThe lint script currently checks:
edge-edge: edge crossings and collinear overlapsedge-rect-border: lines that run along or visibly overlap a box or large frame borderedge-shape-border: lines that run along supported non-rect shape borders such asdocument,hexagon,parallelogram, andtrapezoidedge-rect: lines penetrating boxesedge-terminal: final arrow runs that are too short after the last bendedge-label: routed lines crossing label text boxeslabel-rect: label text boxes colliding with another box or cardrect-shape-border: box or frame borders that run along those supported non-rect shape borderstext-contrast: text whose font color is too close to its fill color for the current font sizetext-emphasis: compact dark cards whose title/body copy is still flattened into a single dense text blocktext-overflow(width): text likely too wide for its boxtext-overflow(height): text likely too tall for its box
Notes:
- input may be either
.drawioor.drawio.svg - when the input is
.drawio, the checker also reads the companion draw.io geometry solabel-rectand text-fit checks stay aligned with the editable source - when the input is
.drawio, a companionsame-name.drawio.svgis 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-contrastcurrently requires explicit hexfillColorandfontColor- 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, andtext-emphasisare 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, orrect-shape-borderis intentional, keep the routing obvious, visually review the output, and document the exception in the surrounding workflow - if
edge-terminalfires, add a longer straight segment before the arrowhead or move the last bend farther away from the target - if
edge-labelfires, reroute the edge or move the label so the text keeps clean breathing room - if
label-rectfires, move the note/card/box or shift the label so they no longer partially overlap - if
text-contrastfires, increase foreground/background contrast instead of relying on opacity, texture, or stroke - if
text-emphasisfires, split the title from the body with a chip, separate text cell, stronger hierarchy, or more breathing room - if
text-overflowlooks 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 JPfor 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:
<mxGraphModel>
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
</root>
</mxGraphModel>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:
<mxCell id="e1" edge="1" parent="1" source="a" target="b" style="edgeStyle=orthogonalEdgeStyle;">
<mxGeometry relative="1" as="geometry"/>
</mxCell>Never use self-closing edge cells.
7.3 Font settings
For diagrams with Japanese text or slide usage, set the font family explicitly:
<mxGraphModel defaultFontFamily="Noto Sans JP" ...>Also set fontFamily in text styles:
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=orthogonalEdgeStylefor 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:
<mxCell id="e1" style="edgeStyle=orthogonalEdgeStyle;rounded=1;jettySize=auto;" edge="1" parent="1" source="a" target="b">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="300" y="150"/>
<mxPoint x="300" y="250"/>
</Array>
</mxGeometry>
</mxCell>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
swimlanewhen 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.
<mxGeometry x="140" y="60" width="400" height="40" />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:
uv run python scripts/find_aws_icon.py ec2
uv run python scripts/find_aws_icon.py lambda9. Checklist
- diagram source is a valid
.drawiofile - a visual template was chosen for new diagrams, defaulting to
references/aesthetic-templates.mdwhen unspecified - export filenames use
.drawio.<format>when exported - edge cells contain
<mxGeometry relative="1" as="geometry"/> - fonts are explicit when Japanese text is involved
- no hard-coded white page background unless the user asked for it
- containers have enough internal margin
- edge routing is visually clear and leaves room for arrowheads
- SVG lint passes for routing-heavy diagrams
- no
edge-terminalfindings remain unless a tiny terminal run is intentionally accepted - no
edge-labelorlabel-rectfindings remain - no
edge-rect-borderfindings remain unless a box or frame border overlap is intentionally accepted - no
edge-shape-borderorrect-shape-borderfindings remain unless a supported non-rect border contact is intentionally accepted - no
text-contrastfindings remain - no
text-emphasisfindings remain on compact dark cards unless the treatment is intentionally accepted after visual review - no
text-overflow(width)ortext-overflow(height)findings remain - final PNG/SVG/PDF was visually checked
10. Repository Docs
For repo-facing documentation and onboarding:
- README.md
- README.ja.md
- docs/guide/getting-started.md
- docs/guide/workflow.md
- docs/guide/architecture.md
- docs/guide/troubleshooting.md
- docs/ja/guide/getting-started.md
- docs/ja/guide/workflow.md
- docs/ja/guide/architecture.md
- docs/ja/guide/troubleshooting.md
- references/layout-guidelines.en.md
- references/aws-icons.en.md
Docs-specific repo note:
- if GitHub Pages styling breaks after a repo rename, verify the VitePress base still matches
/draw-io-skill/
11. References And Credits
This local version is intentionally a blended skill:
- editing and layout guidance inspired by
softaworks/agent-toolkit - native assistant workflow and export conventions inspired by
jgraph/drawio-mcp - SVG linting and repository-ready QA extensions added in this repository
Referenced repositories and sources:
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

