bpmn

Overview of bpmn skill

The bpmn skill helps you create business process and integration diagrams in PlantUML using BPMN, EIP, and Lean Mapping stencil icons. It is a strong fit when you need a diagram that explains workflow automation, approvals, orchestration, messaging, or ETL logic clearly enough for teammates to act on it.

Use the bpmn skill when your real job is to turn a rough process idea into a structured diagram with the right gateway, event, task, and pool/lane choices. It is less useful for generic software architecture diagrams or charts that are really data visuals.

What bpmn is best for

• Workflow Automation: approvals, escalations, handoffs, retries, and SLA paths
• Message-based integration: routers, channels, translators, adapters, and dead-letter handling
• Operational flows: order processing, support triage, saga orchestration, ETL, and value streams

Why this skill is different

The repo is optimized around stencil discipline, not freeform drawing. That means better output when you need BPMN-specific elements like start/end events, message flows, gateways, and lanes instead of plain boxes and arrows. The bpmn skill also makes it easier to choose the right visual language for process vs integration vs value-stream problems.

When not to use it

If you want class diagrams, component diagrams, or general software modeling, use uml instead. If you need dashboards, charts, or data visualization, use vega instead. Those misfits usually produce weaker results than a prompt built around the bpmn skill.

How to Use bpmn skill

Install and open the skill files

Install the bpmn skill with:

npx skills add markdown-viewer/skills --skill bpmn

Then open SKILL.md first, followed by the example files that match your process type. The examples are the fastest way to learn the repo’s notation choices and avoid malformed PlantUML.

Build a good prompt for bpmn

A strong bpmn prompt should include:

• the process name
• the trigger or start event
• the main actors or pools
• key decisions and exceptions
• whether it is BPMN, EIP, or Lean Mapping focused
• any SLA, retry, or compensation behavior

Example prompt shape:

“Create a bpmn skill diagram for an invoice approval workflow. Start with invoice submission, route small invoices to auto-approval, medium invoices to manager review, and large invoices to manager plus finance. Include an SLA timer, escalation path, and rejection end state.”

That gives the model enough structure to pick the right stencil family and flow logic.

Read these files first

Start with:

• SKILL.md for the core rules and fence requirements
• examples/approval-workflow.md for decision-heavy BPMN
• examples/microservice-orchestration.md for saga-style orchestration
• examples/eip-messaging.md for integration-pattern diagrams
• examples/etl-pipeline.md for batch and data movement flows

These files are the most useful bpmn guide because they show which stencil families map to which use cases.

Practical tips that improve output

• Use ```plantuml or ```puml fences only.
• Keep the diagram in @startuml / @enduml.
• Prefer left to right direction for process flows that read from start to finish.
• Specify pools/lanes early if responsibility matters.
• Say whether flows are sequence flows or message flows.
• Name decision points as questions, not labels.

For example, “Payment OK?” is more actionable than “Payment status.”

bpmn skill FAQ

Is bpmn only for process diagrams?

No. The bpmn skill covers BPMN process flows plus EIP integration patterns and Lean Mapping symbols. That makes it useful for workflow automation, service orchestration, and operational value-stream diagrams as well as classic approval flows.

Do I need to know BPMN before using bpmn?

No, but basic process language helps. If you can describe who starts the work, what decision points exist, and where work can fail or pause, the skill can usually turn that into a useful diagram.

How is bpmn better than a normal prompt?

A normal prompt may produce generic boxes and arrows. The bpmn skill biases the output toward correct stencil families, PlantUML formatting, and workflow-specific conventions, which reduces cleanup and makes the diagram easier to read in a workflow automation context.

When should I choose something else?

Choose another skill if the main goal is software structure, UI mockups, analytics charts, or data visualization. The bpmn skill is strongest when the question is “how does work move?” rather than “what does the system contain?”

How to Improve bpmn skill

Give the process state, not just the topic

The best bpmn results come from inputs that describe the actual workflow state machine. Include start, branches, exceptions, completion, and handoff boundaries. For example:

• weak: “Make an order diagram”
• stronger: “Order starts after checkout, validates payment, checks inventory in parallel, sends shipment and notification after reserve, and routes failures to cancel or backorder paths”

That extra detail improves both structure and stencil selection.

Tell the skill what matters most

If your priority is approval policy, say so. If it is integration reliability, say so. If it is throughput or handoff clarity, say so. The bpmn skill can emphasize different parts of the flow, but only if you state the decision criterion.

Watch for common failure modes

The most common issues are vague gateways, missing lane ownership, and mixing message flows with sequence flows. Another frequent problem is overbuilding the diagram with too many decorative steps. Keep only the steps that change routing, responsibility, or system behavior.

Iterate with targeted corrections

After the first output, improve the next version by correcting one thing at a time:

• “Add a timer escalation after 48 hours”
• “Split human tasks into manager and finance lanes”
• “Replace generic task boxes with EIP message translator and router icons”
• “Show compensation steps for payment failure”

That approach is more effective than asking for a full rewrite, and it keeps the bpmn skill focused on the part that is blocking your workflow automation design.