draw-io

Overview of draw-io skill

The draw-io skill is a focused workflow for creating, editing, and reviewing .drawio diagrams as XML, then exporting them to .drawio.png for docs or slides. It is best for developers, technical writers, solution architects, and AI users who need repeatable diagram updates without manually clicking through the draw.io UI.

What draw-io is best at

This draw-io skill is strongest when you need to:

• edit existing .drawio files safely
• make precise layout changes by adjusting XML coordinates
• enforce diagram standards such as font settings
• generate high-resolution transparent PNGs
• use AWS architecture icons with the correct mxgraph.aws4.* identifiers

The real job-to-be-done

Most users do not need “diagram generation” in the abstract. They need an agent to update architecture diagrams reliably, keep styling consistent, and produce export-ready assets that fit a documentation pipeline. draw-io is useful because it turns that into a concrete workflow instead of a vague prompt.

What makes draw-io different from a generic prompt

A normal prompt might produce a diagram idea. This skill adds practical operating rules:

• edit .drawio XML, not the generated .drawio.png
• export PNGs with known CLI settings
• apply explicit font-family settings for slide compatibility
• follow layout guidance for grouping, flow direction, and readability
• look up AWS icons from a local reference instead of guessing icon names

Who should probably install it

Install draw-io if you already work with draw.io files in Git, generate docs or slides from source, or need architecture diagrams updated programmatically. If you only want a one-off visual brainstorm in a GUI, this is probably more process than you need.

How to Use draw-io skill

Install the draw-io skill

Use your skill manager to add it from the repository:

npx skills add softaworks/agent-toolkit --skill draw-io

If your environment uses a different installer, the important part is the skill path skills/draw-io in softaworks/agent-toolkit.

Confirm the local prerequisites

Before relying on draw-io install, check that your environment has:

• a drawio CLI available for export
• bash for the conversion script
• git if you want generated PNGs auto-staged
• optionally mise and pre-commit if your repo uses that workflow

The provided conversion script calls:

drawio -x -f png -s 2 -t -o output.drawio.png input.drawio

That means export mode, PNG format, 2x scale, transparent background, and explicit output path.

Read these files first

For quickest adoption, inspect these in order:

1. skills/draw-io/SKILL.md
2. skills/draw-io/README.md
3. skills/draw-io/references/layout-guidelines.md
4. skills/draw-io/references/aws-icons.md
5. skills/draw-io/scripts/convert-drawio-to-png.sh
6. skills/draw-io/scripts/find_aws_icon.py

This reading order matters because the skill is more operational than conceptual: rules, layout conventions, and helper scripts carry most of the value.

Know the core operating rule first

The most important usage constraint is simple:

• edit .drawio files
• do not directly edit .drawio.png files

The PNG is treated as a generated artifact. If your repo tracks both source and export, your agent should modify the XML source and regenerate the PNG afterward.

What input the skill needs

The draw-io usage quality depends heavily on the input you provide. Good inputs usually include:

• the target file path
• whether you are creating or editing
• the diagram type: architecture, flowchart, sequence-like flow, etc.
• the intended reading direction: left-to-right or top-to-bottom
• required services, nodes, labels, and connections
• any slide or documentation constraints
• whether AWS official icons are required
• whether PNG export is needed now

Without those details, the agent has to guess structure, spacing, and naming.

Turn a rough goal into a strong draw-io prompt

Weak prompt:

“Update our AWS diagram.”

Better prompt:

“Edit assets/system.drawio. Add Amazon S3 on the left as the ingestion source, route data to AWS Lambda, then to Amazon RDS. Keep a left-to-right flow. Preserve existing group structure. Use official AWS icons, avoid crossing arrows, and regenerate assets/system.drawio.png.”

Why this works better:

• it names the file
• it specifies added components
• it gives flow direction
• it requests icon fidelity
• it includes a layout goal
• it asks for the export artifact

Use draw-io for precise edits, not just generation

This skill is particularly useful when you already have a diagram and need targeted changes such as:

• move one cluster to avoid line overlap
• align service boxes horizontally
• replace a generic label with an official AWS service name
• change fonts for slide compatibility
• regenerate PNG after XML edits

That is where direct XML editing is often faster and more reproducible than manual UI work.

Follow the font settings if slides matter

If the diagram is used in Quarto slides or environments with font rendering issues, the skill recommends setting:

• defaultFontFamily on mxGraphModel
• fontFamily on individual text elements

The repository explicitly calls out Noto Sans JP as a recommended font for Japanese support. Even if you do not need Japanese, the broader lesson is important: specify fonts explicitly when you need consistent output across machines and export steps.

Use the conversion paths that match your repo

The skill supports multiple ways to export PNGs:

• all files via pre-commit: mise exec -- pre-commit run --all-files
• one file via pre-commit: mise exec -- pre-commit run convert-drawio-to-png --files assets/my-diagram.drawio
• direct script use: bash ~/.claude/skills/draw-io/scripts/convert-drawio-to-png.sh assets/diagram1.drawio

Choose based on your repo workflow. If your project already uses pre-commit, use that path. If you just need a one-off local export, the script is the fastest route.

Use the AWS icon reference instead of guessing

If you are doing draw-io for Design Implementation in AWS-heavy diagrams, the icon reference is one of the most valuable parts of the skill. It documents:

• official service naming like Amazon ECS and AWS Lambda
• current icon style conventions using mxgraph.aws4.*
• resource and product icon patterns

The included helper script can search the reference:

python ~/.claude/skills/draw-io/scripts/find_aws_icon.py lambda

That is much safer than inventing resIcon names from memory.

Apply the layout guidance intentionally

The repository’s layout guidance is not filler. It gives practical defaults that improve output quality:

• group cloud boundaries and subnets clearly
• keep the main flow left-to-right when possible
• use different line styles for different flow types
• keep related elements close
• reduce arrow crossings
• leave enough whitespace for readability

If you want a useful first pass, tell the agent which of these principles matters most for your diagram.

draw-io skill FAQ

Is draw-io good for beginners?

Yes, if you already have draw.io files and want help editing them. The skill reduces guesswork by giving concrete rules and scripts. It is less ideal for a complete beginner who only wants to explore diagramming concepts with no file-based workflow.

When is draw-io better than a normal AI prompt?

draw-io is better when you need reproducible edits, proper file handling, export steps, or AWS icon correctness. A normal prompt may describe a diagram well, but it usually will not enforce .drawio source editing, export commands, font settings, and helper-script usage.

Does draw-io require the draw.io GUI?

Not necessarily. The skill is designed around source-file editing and CLI-based PNG export. That makes it useful in code-centric workflows, reviewable diffs, and documentation pipelines.

When should I not use draw-io?

Skip this draw-io guide if you need:

• freeform whiteboarding
• polished design mockups outside draw.io
• purely visual editing in a GUI
• diagram generation for formats unrelated to .drawio

This skill is specialized around draw.io XML and export operations, not general graphic design.

Can draw-io help with AWS architecture diagrams?

Yes. That is one of its clearest strengths. The AWS icon reference and lookup script help you use official names and mxgraph.aws4.* icons, which is valuable when consistency and recognizability matter.

Will draw-io automatically fix bad layout?

Not automatically in a magic sense. The skill gives a method for adjusting coordinates and layout deliberately. It improves outcomes when you provide clear placement intent, such as grouping, flow direction, spacing, and overlap priorities.

How to Improve draw-io skill

Give draw-io stronger structural inputs

The fastest way to improve draw-io usage is to provide structure, not adjectives. Instead of saying “make it cleaner,” say:

• move the database below the app tier
• keep all ingestion sources in the left column
• make arrows non-crossing if possible
• group public and private subnet resources separately
• keep labels short enough to avoid box expansion

That kind of instruction maps directly to XML and layout decisions.

Start from an existing diagram when possible

The skill performs best when it can edit an existing .drawio file rather than invent everything from scratch. Existing files give it:

• current element IDs
• layout patterns
• style conventions
• group structure
• known export targets

For teams, this usually produces more reliable results than asking for a brand-new diagram every time.

Be explicit about naming and icon fidelity

A common failure mode is vague service naming like “ECS” or “Lambda” without deciding whether labels should use the full official service names. If AWS diagrams matter, specify both:

• display labels: Amazon ECS, AWS Lambda, Amazon RDS
• icon requirement: use official mxgraph.aws4.* service icons

This prevents mixed naming styles and incorrect icon mapping.

Ask for edit-then-export as one workflow

If you want usable outputs, request both the source edit and the export step in one instruction. Example:

“Update docs/arch.drawio, then regenerate docs/arch.drawio.png with the skill’s standard PNG export settings.”

This reduces the common gap where the XML is changed but the preview artifact is stale.

Watch for the main failure modes

Common draw-io problems are usually practical, not conceptual:

• editing the PNG instead of the .drawio
• forgetting font settings and getting inconsistent text rendering
• using guessed AWS icon identifiers
• overpacking nodes so labels collide
• creating crossed connectors that hurt readability
• making layout changes without preserving the overall flow

You can prevent most of these by referencing the provided scripts and guides directly in your prompt.

Iterate with small, reviewable changes

For complex diagrams, do not request everything at once. A better pattern is:

1. adjust structure and grouping
2. review spacing and connectors
3. fix labels and fonts
4. export PNG
5. do one final pass for readability

This produces cleaner diffs and makes it easier to spot whether a layout problem came from grouping, icon choice, or text size.

Point the agent to repository helpers by name

If your agent supports file-aware prompting, mention the exact references:

• references/layout-guidelines.md for spacing and flow
• references/aws-icons.md for AWS naming and icons
• scripts/find_aws_icon.py for icon lookup
• scripts/convert-drawio-to-png.sh for export

That small step often improves first-pass quality because the agent uses the repository’s conventions instead of generic diagram advice.