Working with Skills

Skills: The Agent's Knowledge of What Is Possible

The central concept of the Dynamixs.AI BPMNAgent are Skills. A skill describes a workflow action that the agent can invoke on behalf of the user — for example starting a new workflow process and filling in its form data.

Skills are not hardcoded. They are derived entirely from the BPMN models deployed in the system and the process configuration. This means the agent's capabilities grow automatically as new workflows are deployed — without any changes to the agent itself.

ProcessSkill
    └── ModelSkill
            └── WorkflowGroupSkill
                    └── TaskSkill
                            ├── EventSkill
                            └── ItemSkill (Form Fields)

# Available Workflow Processes:

## Human Resources

### vacation-request-en-1.0

This model covers all HR-related processes for employees and managers.

#### New Vacation Request

A new vacation request has been submitted by an employee.
The request needs to be reviewed and approved by the manager.
(model: vacation-request-en-1.0, taskid: 1000, process.ref: 6d0f...)

- **Submit** (eventid: 20)
  Submit for approval. Use this event only when ALL required fields are filled.
  The request will be forwarded to the manager for review.

- **[init]** (eventid: 10)
  Save as draft. Use this event when required fields are still missing.
  The process is saved but not yet submitted for approval.

**Form Fields:**

- `vacation.date` (html5date, required): From
- `vacation.due` (html5date, required): To
- `employee.department` (text, required): Department
- `vacation.description` (textarea, required): Description

The Two Roles

Working with skills requires two people with different responsibilities:

Both roles must work together. A perfectly written skill has no effect if the prompt modeller does not make it available to the agent. And a well-designed prompt cannot compensate for a skill that is missing or too vague.

Skill Structure

A skill is a document stored in the workflow system with the following fields:

The name and description are what the agent sees when choosing between skills. The content is what the agent reads when actually using the skill. Keep description short and precise — it is the agent's only basis for selection.

Writing Effective Skill Content

The content field is a free-form text document. There is no required structure — the skill expert decides what the agent needs to know. That said, the following structure has proven effective for classification tasks:

Purpose One sentence: what is this skill for?

Typical materials / subjects Which materials, products or cases does this skill cover?

Classification levels What does SIMPLE, MEDIUM and COMPLEX mean in this domain?

Classification dimensions Which properties determine complexity? For each dimension: what increases complexity, what reduces it?

Open points — when to ask When is information missing or ambiguous enough that the agent should ask the user before classifying?

Confidence rules When is HIGH confidence justified? When is MEDIUM acceptable? When should the agent ask instead of deciding?

Examples (recommended) One concrete SIMPLE case and one COMPLEX case, with a brief explanation why.

Static Skill Loading via the Prompt Template

The simplest way to make a skill available to an agent is to embed it directly in the prompt template using the <skill> tag. The SkillPromptHandler resolves this tag at runtime before the first LLM call — the agent receives the full skill content as part of its system prompt.

<skill id="MATERIAL_CLASSIFICATION" />

<skill category="material" />

<skill category="material" separator="---" />

<skill id="MATERIAL_CLASSIFICATION" category="material" />

Dynamic Skill Selection via Tool Calls

For scenarios where the right skill depends on the content of the request — and the modeller cannot know in advance which skill applies — the agent can select the skill itself at runtime using two tool calls.

This approach adds flexibility but also adds two LLM iterations to the agent loop. Use it when the number of skills per category is large and loading all of them at once would make the prompt too long.

[
  {
    "uniqueid": "a1b2c3",
    "name": "Technische Folien",
    "description": "Klassifizierung von Kunststofffolien für elektrische und mechanische Anwendungen"
  },
  {
    "uniqueid": "d4e5f6",
    "name": "Dichtungsmaterialien",
    "description": "Klassifizierung von Elastomeren, Schäumen und Dichtungsplatten"
  }
]

Combining Both Approaches in the System Prompt

When using dynamic skill selection, the system prompt must instruct the agent to call find_skill and get_skill before starting its actual task. The category is always provided by the prompt modeller — the agent does not invent it.

<PromptDefinition>
    <options>{"n_predict": 4096, "temperature": 0}</options>
    <prompt role="system"><![CDATA[
You are a calculation assistant for the manufacturing of specialty films.

PROCEDURE
1. Call find_skill with category="material" to see the available
   classification skills.
2. Select the skill that best matches the requested material based on
   its name and description.
3. Call get_skill with the uniqueid of the selected skill to load its
   full content.
4. Classify the material based on the loaded skill.

BEHAVIOUR
- Work exclusively with the information from the loaded skill
- Do not make assumptions when information is unclear or missing
    ]]></prompt>
    <prompt role="user"><![CDATA[
        <filedata ref="agent.workitem.ref">\.pdf$</filedata>
    ]]></prompt>
</PromptDefinition>

The category "material" is fixed in the prompt by the modeller. The agent decides only which skill within that category fits the request.

Choosing the Right Approach

What Happens Without Good Skills

If skills are missing or too vague, the agent's behaviour becomes unpredictable:

• It may ask unnecessary questions because it has no basis for classification
• It may reach a wrong conclusion because no dimension guided its reasoning
• It may select the wrong skill if descriptions are too similar or too generic
• It may produce inconsistent results across runs because the reasoning is unconstrained

None of these are failures of the agent — they are failures of the skill content. The agent can only be as good as the knowledge it is given.

Summary: Skills Checklist

Before deploying an agent that uses skills, verify the following:

For the Skill Expert:

• [ ] Each skill has a short, precise description that clearly distinguishes it from other skills in the same category
• [ ] The category field is set consistently across all related skills
• [ ] The content covers all dimensions the agent needs to reason about
• [ ] The content defines when the agent should ask for more information
• [ ] The content defines confidence rules so the agent knows when it can decide
• [ ] At least one SIMPLE and one COMPLEX example is included (recommended)

For the Prompt Modeller:

• [ ] The correct loading approach is chosen for the task (static ID, category, or dynamic tool calls)
• [ ] If dynamic tool calls are used, the system prompt instructs the agent to call find_skill before starting the task
• [ ] The category passed to find_skill is fixed in the prompt — the agent does not determine it
• [ ] The prompt instructs the agent to use only the loaded skill content — no assumptions from general knowledge