bpmn

BPMN 2.0: read and edit process diagrams

What this skill does

Helps you understand existing .bpmn files in plain language and produce new or edited ones that are valid and visually clean when opened in any modeler (Camunda Modeler, bpmn.io, Cawemo, etc.).

The job splits cleanly:

• You do the semantic reasoning: what the process means, what to add or change.
• The bundled script does the deterministic mechanics: parsing, regenerating layout, and validating. Lean on it instead of hand-rolling these each time.

The one idea that makes BPMN tractable: two layers

A .bpmn file holds two layers in one XML document:

1. Semantics - the actual process: bpmn:process with tasks, gateways, events, and sequenceFlows connecting them. This is the meaning.
2. Diagram interchange (DI) - bpmndi:BPMNDiagram with x/y coordinates for every shape and waypoints for every edge. This is only the picture.

Editing DI by hand is where BPMN work goes wrong: coordinates drift, shapes overlap, edges cross. So we never hand-write DI. You edit semantics; the layout command owns the DI. That is exactly what makes the diagram "clear" - a tidy left-to-right layout, generated deterministically.

layout is non-destructive by default, which is the rule that keeps you out of trouble: on a file that already has a diagram it preserves the existing layout and only syncs it to your edit (prune shapes for deleted elements, place shapes for new ones). On a file with no DI it generates a fresh layout. It only throws the whole diagram away and rebuilds from scratch when you pass --rebuild. So the habit is simple: after editing semantics, always run layout; it never destroys a good diagram.

Setup (once per machine)

The script needs two npm packages. From the skill's own directory:

npm install --prefix "<SKILL_DIR>"

<SKILL_DIR> is the folder containing this SKILL.md. After that, the four commands below are available. If a run fails with "Cannot find package", the install step was skipped - run it and retry.