BPMN Skills
When you write a Prompt Template, you often want the LLM to know which workflow processes, tasks and events actually exist - so it can refer to them by name and ID instead of you having to spell them out by hand. The Skill Tree is a Markdown snapshot of exactly that, generated automatically from your BPMN documentation and inserted wherever you place the <skill.bpmn/> tag.
As a modeler, you decide where this information should appear simply by placing the tag in your Prompt Template - no additional configuration is needed.
The <skill.bpmn/> Tag
Add the tag anywhere inside a Prompt Template:
<skill.bpmn/>
At runtime it is replaced with the full Skill Tree for the current workitem.
The generated tree is cached in the item ai.skill.bpmn on the workitem, so it is only built once per case. If your process definitions change, the cached tree needs to be reset before a new one is generated.
Example
A Prompt Template using the BPMN Skill may looks like this:
You are a helpful assistant supporting employees with their business requests.
Here are the workflow processes you can offer to the user:
<bpmnskills/>
Always confirm the process and task name with the user before starting a case.
At runtime, the tag <skill.bpmn/> tag is replaced with the generated Skill Tree - for example:
# Available Workflow Processes:
## Contract Management
Handles the lifecycle of customer contracts from draft to signature.
### 1.0.0
Contract processes for the sales department.
#### New Contract Request
Starts a new contract based on a customer request.
(model: 1.0.0, taskid: 100, process.ref: a1b2c3d4-...)
- **Submit for Review** (eventid: 10)
Sends the contract to legal for review.
- **Save as Draft** (eventid: 20)
Keeps the contract editable without notifying anyone.
**Form Fields:**
- `customer.name` (string, required): Customer
- `contract.value` (double): Contract Value
- `contract.startdate` (date, required): Start Date
The LLM now knows there is a “Contract Management” process, a “New Contract Request” task with taskid: 100, two possible next events with their eventid, and which form fields to ask the user for - all without you having to hard-code any of this into the prompt text.
What Goes Into the Tree
The tree is assembled bottom-up from four BPMN levels, each nested under the one above:
| Level | Rendered as | Carries |
|---|---|---|
| Model | ### heading |
Model documentation |
| Process / Workflow Group | grouping only | Group documentation |
| Task | #### heading |
Task documentation, form fields |
| Event | bullet list entry | Event documentation, event ID |
Every rendered Task carries its taskid and the owning process.ref, and every rendered Event carries its eventid — these are exactly the identifiers you can have the LLM refer to directly in its response or reasoning.
Documentation Rules
Not every Model, Process, Task or Event is meant to show up in the tree. Two different rules apply, depending on the level:
| Level | Rule |
|---|---|
| Model | Excluded — together with everything beneath it — if its documentation is blank, or marked with the ignore tag. |
| Process / Workflow Group | Excluded — together with everything beneath it — if its documentation is blank, or marked with the ignore tag. |
| Task | Blank documentation is fine and does not exclude the task. Only excluded if marked with the ignore tag. |
| Event | Blank documentation is fine and does not exclude the event. Only excluded if marked with the ignore tag. |
The reasoning: Model and Process documentation is what gives the LLM the context to tell workflow groups apart, so a missing one there means the whole branch is incomplete and gets dropped. Tasks and Events are usually self-explanatory from their name alone (e.g. “Approve”, “Reject”), so a missing description there is not a reason to hide them — but you may still want to hide a specific technical Task or Event that isn't meant for the LLM at all, which is what the ignore tag is for.
This keeps the resulting tree always complete and consistent: if a Model or Process appears at all, its documentation is guaranteed to be present.
The Ignore Tag
Add the tag anywhere inside a documentation field to exclude that element from the Skill Tree, regardless of level:
<skill.ignore/>
Typical uses:
- A Model or Process that is still in draft and not yet ready to be exposed in a prompt.
- A technical Task or Event that exists purely for internal routing and would only confuse the LLM if it were offered as an option.
Designing Good BPMN Documentation for Prompts
A few habits that make the generated Skill Tree easier for the LLM to work with:
- Write Model and Process documentation for the LLM, not just for humans. It's what decides whether the branch is included at all, and it's the first context the LLM reads before drilling into individual tasks.
- Name Tasks and Events clearly. Since blank documentation is tolerated on these two levels, the name is often the only signal the LLM gets — make it unambiguous.
- Use the ignore tag deliberately, not as a stand-in for “not documented yet.” It's a permanent exclusion, not a placeholder — reach for it only when an element genuinely shouldn't be visible to the LLM.