agentleFS
Sunwood-ai-labsSunwood-ai-labs/draw-io-skill/SKILL.md

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

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
  1. Distinctive:

    Use this skill when an agent needs to:

    line 10
  2. Very specific:

    create a new draw.io diagram as native .drawio XML

    line 12
  3. Distinctive:

    check routed edges, box- or frame-border overlap, supported non-rect shape border overlap, box penetration, short arrowhead tails, label …

    line 15
  4. Very specific:

    default visual templates and style tokens under references/aesthetic-templates.md

    line 36
  5. Distinctive:

    When working inside this repository, these are the main maintenance commands:

    line 46
  6. Distinctive:

    Use them this way:

    line 58
  7. Distinctive:

    If you need to attach the repo as a skill in a local assistant environment, the repository docs use these conventions:

    line 65
  8. Distinctive:

    Follow this order unless the user asks for something narrower:

    line 82
  9. Very specific:

    Create or update the native .drawio file first.

    line 84
  10. Very specific:

    When creating a diagram from scratch and the user did not specify a visual style, start from references/aesthetic-templates.md.

    line 85
  11. Very specific:

    Keep .drawio as the editable source of truth for repository work.

    line 86
  12. Very specific:

    If the user asked for an exported artifact, export to .drawio.png, .drawio.svg, .drawio.pdf, or .drawio.jpg.

    line 87
  13. Distinctive:

    Before showing, attaching, or claiming a diagram is ready, export an SVG and run the lint script.

    line 88
  14. Very specific:

    If the user only asks for a diagram and does not request a format, stop at the .drawio file.

    line 94
  15. Very specific:

    Do not manually edit generated .drawio.png, .drawio.svg, or .drawio.pdf files.

    line 99
  16. Distinctive:

    Prefer native mxGraphModel XML over Mermaid or CSV conversions.

    line 100
  17. Distinctive:

    Keep source diagrams unless the user explicitly wants embedded-only cleanup after export.

    line 101
  18. Distinctive:

    Use descriptive lowercase filenames with hyphens.

    line 102
  19. Distinctive:

    Use the bundled helper first:

    line 131
  20. Distinctive:

    If draw.io CLI discovery fails, rerun with an explicit executable path:

    line 147
  21. Distinctive:

    If needed, call draw.io directly:

    line 157
  22. Distinctive:

    After exporting SVG, run the bundled lint:

    line 190
  23. Very specific:

    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 …

    line 221
  24. Very specific:

    when the input is .drawio, a companion same-name.drawio.svg is expected for routed-edge checks.

    line 222
  25. Very specific:

    if the checker reports parsed 0 edges, the SVG did not provide usable edge geometry.

    line 223
  26. Distinctive:

    never claim a diagram is final based only on visual review when the lint script was skipped or failed to inspect edges

    line 224
  27. Very specific:

    if edge-rect-border, edge-shape-border, or rect-shape-border is intentional, keep the routing obvious, visually review the output, and …

    line 233
  28. Very specific:

    if edge-terminal fires, add a longer straight segment before the arrowhead or move the last bend farther away from the target

    line 234
  29. Very specific:

    if edge-label fires, reroute the edge or move the label so the text keeps clean breathing room

    line 235
  30. Very specific:

    if label-rect fires, move the note/card/box or shift the label so they no longer partially overlap

    line 236
  31. Very specific:

    if text-contrast fires, increase foreground/background contrast instead of relying on opacity, texture, or stroke

    line 237
  32. Very specific:

    if text-emphasis fires, split the title from the body with a chip, separate text cell, stronger hierarchy, or more breathing room

    line 238
  33. Very specific:

    if text-overflow looks like a false positive, first try widening the box, shortening the label, adding an intentional line break, or …

    line 239
  34. Distinctive:

    If a diagram passes lint but still looks visually plain, revise hierarchy, spacing, and palette before presenting it.

    line 256
  35. Distinctive:

    Every diagram must use native mxGraphModel XML:

    line 260
  36. Very specific:

    All normal diagram cells should live under parent="1" unless you intentionally use container parents.

    line 271
  37. Distinctive:

    Every edge cell must contain geometry:

    line 275
  38. Distinctive:

    Never use self-closing edge cells.

    line 283
  39. Distinctive:

    leave at least 20px of straight segment near arrowheads

    line 302
  40. Very specific:

    use edgeStyle=orthogonalEdgeStyle for most technical diagrams

    line 303
  41. Distinctive:

    add explicit waypoints when auto-routing produces overlap or awkward bends

    line 304
  42. Distinctive:

    when using large outer frames or swimlanes, keep routed segments off the frame stroke and use the gutter between the frame and child boxes …

    line 305
  43. Distinctive:

    Do not fake containment by simply placing boxes on top of bigger boxes.

    line 323
  44. Very specific:

    use parent="containerId" for child elements

    line 325
  45. Very specific:

    use swimlane when the container needs a visible title bar

    line 326
  46. Very specific:

    use group;pointerEvents=0.

    line 327
  47. Very specific:

    add container=1;pointerEvents=0.

    line 328
  48. Distinctive:

    If text is mixed Japanese and English, err on the wider side.

    line 338
  49. Distinctive:

    prefer transparent backgrounds over hard-coded white backgrounds

    line 342
  50. Distinctive:

    verify that titles and labels do not sit too close to frame edges

    line 345
  51. Distinctive:

    use one line for short service names when possible

    line 349
  52. Very specific:

    use <br> for intentional two-line labels

    line 350
  53. Distinctive:

    When appropriate, include title, description, last updated, author, or version.

    line 355
  54. Distinctive:

    When working on AWS diagrams:

    line 368
  55. Distinctive:

    use the latest official icon naming where possible

    line 370
  56. Very specific:

    prefer current mxgraph.aws4.* icon references

    line 371
  57. Distinctive:

    remove decorative icons that do not add meaning

    line 372
  58. Very specific:

    if GitHub Pages styling breaks after a repo rename, verify the VitePress base still matches /draw-io-skill/

    line 420

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

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 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:

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

FormatEmbedded XMLRecommended use
.drawion/aEditable source diagram
pngYesDocs, slides, chat attachments
svgYesDocs, scalable output, lint input
pdfYesReview and print
jpgNoLast-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:

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 <path> 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:

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:

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:

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:

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:

<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=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:

<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 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.

<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 &lt;br&gt; 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 lambda

9. Checklist

  • diagram source is a valid .drawio file
  • a visual template was chosen for new diagrams, defaulting to references/aesthetic-templates.md when 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-terminal findings remain unless a tiny terminal run is intentionally accepted
  • no edge-label or label-rect findings remain
  • no edge-rect-border findings remain unless a box or frame border overlap is intentionally accepted
  • no edge-shape-border or rect-shape-border findings remain unless a supported non-rect border contact is intentionally accepted
  • no text-contrast findings remain
  • no text-emphasis findings remain on compact dark cards unless the treatment is intentionally accepted after visual review
  • no text-overflow(width) or text-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:

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.