• "create a diagram", "draw a flowchart", "generate an architecture diagram"
• "design a sequence diagram", "make a UML class diagram", "build an ER diagram"
• "add a .drawio file", "update the diagram", "visualise the flow"
• "document the architecture", "show the data model", "diagram the service interactions"
• Any request to produce or modify a

  .drawio

  ,

  .drawio.svg

  , or

  .drawio.png

  file

assets/templates/flowchart.drawio

assets/templates/architecture.drawio

assets/templates/sequence.drawio

assets/templates/er-diagram.drawio

assets/templates/uml-class.drawio

• If running with VS Code integration enabled, Install the drawio extension: draw.io VS Code extension —

  hediet.vscode-drawio

  (extension id). Install with:

  ext install hediet.vscode-drawio

• Supported file extensions:

  .drawio

  ,

  .drawio.svg

  ,

  .drawio.png

• Python 3.8+ (optional) — for the validation and shape-insertion scripts in

  scripts/

1. Diagram type — What kind of diagram? (flowchart, architecture, UML, ER, sequence, network...)
2. Entities / actors — What are the main components, actors, classes, or tables?
3. Relationships — How are they connected? What direction? What cardinality?
4. Output path — Where should the

   .drawio

   file be saved?
5. Existing file — Are we creating new or editing an existing file?

• Use a template when the diagram type matches one in

  assets/templates/

  . Copy the template structure and replace placeholder values.
• Start fresh for novel layouts. Begin with the minimal valid skeleton:

<!-- Set modified="" to the current ISO 8601 timestamp when generating a new file -->
<mxfile host="Electron" modified="" version="26.0.0">
  <diagram id="page-1" name="Page-1">
    <mxGraphModel dx="1422" dy="762" grid="1" gridSize="10" guides="1"
                  tooltips="1" connect="1" arrows="1" fold="1"
                  page="1" pageScale="1" pageWidth="1169" pageHeight="827"
                  math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- Your cells go here -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Rule: ids

0

and

1

are ALWAYS required and must be the first two cells. Never reuse them.

• Organise into rows or tiers (use swimlanes for layers)
• Horizontal spacing: 40–60px between same-row shapes
• Vertical spacing: 80–120px between tier rows
• Standard shape size:

  120x60

  px for process boxes,

  160x80

  px for swimlanes
• Default canvas: A4 landscape =

  1169 x 827

  px

<mxCell id="unique-id" value="Label"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
        vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="120" height="60" as="geometry" />
</mxCell>

<mxCell id="edge-id" value="Label (optional)"
        style="edgeStyle=orthogonalEdgeStyle;html=1;"
        edge="1" source="source-id" target="target-id" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

• Every cell id must be globally unique within the file
• Every vertex must have an

  mxGeometry

  child with

  x

  ,

  y

  ,

  width

  ,

  height

  ,

  as="geometry"

• Every edge must have

  source

  and

  target

  matching existing vertex ids — exception: floating edges (e.g. sequence diagram lifelines) use

  sourcePoint

  /

  targetPoint

  inside

  <mxGeometry>

  instead; see §4 Sequence Diagram
• Every cell's

  parent

  must reference an existing cell id
• Use

  html=1

  in style when the label contains HTML (

  <b>

  ,

  <i>

  ,

  <br>

  )
• Escape XML special characters in labels:

  &

  =>

  &

  ,

  <

  =>

  <

  ,

  >

  =>

  >

1. Write the file to the requested path with

   .drawio

   extension
2. Run the validator (optional but recommended):
   bash

   python .github/skills/draw-io-diagram-generator/scripts/validate-drawio.py <path-to-file.drawio>

3. Tell the user how to open the file:

   "Open

   <filename>

   in VS Code — it will render automatically with the draw.io extension. You can use draw.io's web app or desktop app as well if you prefer."

4. Provide a brief description of what is in the diagram so the user knows what to expect.

<!-- Tier swimlane -->
<mxCell id="tier1" value="Client Layer"
        style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;fontStyle=1;"
        vertex="1" parent="1">
  <mxGeometry x="60" y="100" width="1050" height="130" as="geometry" />
</mxCell>

<!-- Service inside tier (parent="tier1", coords are relative to tier) -->
<mxCell id="webapp" value="Web App"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
        vertex="1" parent="tier1">
  <mxGeometry x="80" y="40" width="120" height="60" as="geometry" />
</mxCell>

Connectors between tiers use absolute coordinates with

parent="1"

.

• Lifelines:

  edge="1"

  with

  endArrow=none

  and

  dashed=1

  , no source/target — use

  sourcePoint

  /

  targetPoint

  in geometry
• Synchronous message:

  endArrow=block;endFill=1

• Return message:

  endArrow=open;endFill=0;dashed=1

• Self-call: loop the edge via two Array points to the right and back

<!-- Actor (stick figure) -->
<mxCell id="actorA" value="Client"
        style="shape=mxgraph.uml.actor;pointerEvents=1;dashed=0;whiteSpace=wrap;html=1;aspect=fixed;"
        vertex="1" parent="1">
  <mxGeometry x="110" y="80" width="60" height="80" as="geometry" />
</mxCell>

<!-- Service box -->
<mxCell id="actorB" value="API Server"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;"
        vertex="1" parent="1">
  <mxGeometry x="480" y="100" width="160" height="60" as="geometry" />
</mxCell>

<!-- Lifeline — floating edge: uses sourcePoint/targetPoint, NOT source/target attributes -->
<mxCell id="lifA" value=""
        style="edgeStyle=none;dashed=1;endArrow=none;"
        edge="1" parent="1">
  <mxGeometry relative="1" as="geometry">
    <mxPoint x="140" y="160" as="sourcePoint" />
    <mxPoint x="140" y="700" as="targetPoint" />
  </mxGeometry>
</mxCell>

<!-- Activation box (thin rectangle on lifeline) -->
<mxCell id="actA1" value=""
        style="fillColor=#dae8fc;strokeColor=#6c8ebf;"
        vertex="1" parent="1">
  <mxGeometry x="130" y="220" width="20" height="180" as="geometry" />
</mxCell>

<!-- Synchronous message -->
<mxCell id="msg1" value="POST /orders"
        style="edgeStyle=elbowEdgeStyle;elbow=vertical;html=1;endArrow=block;endFill=1;"
        edge="1" source="actA1" target="actorB" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

<!-- Return message (dashed) -->
<mxCell id="msg2" value="201 Created"
        style="edgeStyle=elbowEdgeStyle;elbow=vertical;dashed=1;html=1;endArrow=open;endFill=0;"
        edge="1" source="actorB" target="actA1" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

Note: Lifelines are floating edges that use

sourcePoint

/

targetPoint

in

<mxGeometry>

instead of

source

/

target

attributes. This is the standard draw.io pattern for sequence diagrams.

shape=table

childLayout=tableLayout

shape=tableRow

portConstraint=eastwest

shape=partialRectangle

edgeStyle=entityRelationEdgeStyle

• One-to-One:

  startArrow=ERone;endArrow=ERone

• One-to-Many:

  startArrow=ERone;endArrow=ERmany

• Many-to-Many:

  startArrow=ERmany;endArrow=ERmany

• Mandatory:

  ERmandOne

  , Optional:

  ERzeroToOne

.drawio

1. Read the file first to understand existing cell ids, positions, and parent hierarchy
2. Identify the target diagram page — by index or

   name

   attribute
3. Assign new unique ids that do not collide with existing ids
4. Respect the container hierarchy — children of a swimlane use coordinates relative to their parent
5. Verify edges — after repositioning nodes, confirm edge source/target ids remain valid

scripts/add-shape.py

python .github/skills/draw-io-diagram-generator/scripts/add-shape.py docs/arch.drawio "New Service" 700 380

• Align shapes to the 10px grid (all coordinates divisible by 10)
• Group related shapes inside swimlane containers
• One diagram topic per page; use multi-page files for complex systems
• Aim for 40 or fewer cells per page for readability

• Add a title text cell (

  text;strokeColor=none;fillColor=none;fontSize=18;fontStyle=1

  ) at top of every page
• Always set

  whiteSpace=wrap;html=1

  on vertex shapes
• Keep labels concise — 3 words or fewer per shape where possible

• Use the semantic color palette from Section 3 Step 5 consistently across a project
• Prefer

  edgeStyle=orthogonalEdgeStyle

  for clean right-angle connectors
• Do not inline arbitrary HTML in labels unless necessary

• Use kebab-case:

  order-service-flow.drawio

  ,

  database-schema.drawio

• Place diagrams alongside the code they document:

  docs/

  or

  architecture/

.drawio

• File starts with

  <mxfile>

  root element
• Every

  <diagram>

  has a non-empty

  id

  attribute

• <mxCell id="0" />

  is the first cell in every diagram

• <mxCell id="1" parent="0" />

  is the second cell in every diagram
• All cell

  id

  values are unique within each diagram
• Every vertex cell has

  vertex="1"

  and a child

  <mxGeometry as="geometry">

• Every edge cell has

  edge="1"

  and either: (a)

  source

  /

  target

  pointing to existing vertex ids, or (b)

  <mxPoint as="sourcePoint">

  and

  <mxPoint as="targetPoint">

  in its

  <mxGeometry>

  (floating edge — used for sequence diagram lifelines)
• Every cell (except id=0) has a

  parent

  pointing to an existing id

• html=1

  is in the style for any label containing HTML tags
• XML is well-formed (no unclosed tags, no unescaped

  &

  ,

  <

  ,

  >

  in attribute values)
• A title label cell exists at the top of each page

python .github/skills/draw-io-diagram-generator/scripts/validate-drawio.py <file.drawio>

1. The

   .drawio

   file written to the requested path
2. A one-sentence summary of what the diagram shows
3. How to open it:

   "Open

   <filename>

   in VS Code — the draw.io extension will render it automatically. Or you can open it in the draw.io web app or desktop app if you prefer."

4. How to edit it (if the user is likely to customise):

   "Click any shape to select it. Double-click to edit the label. Drag to reposition."

5. Validation status — whether the validator script was run and passed