Skills

Skills are functions that run automatically at predefined points in the workflow lifecycle, such as at session start or during state transitions. Unlike tools, skills aren’t invoked by the agent during response generation. Instead, they’re triggered by workflow events.

---

Basic Skill Structure

Skills are defined in Plugin files (YAML format) almost the same way as tools.

The key differences are:

• The kind field must be set to Skill
• The platform injects arguments automatically, instead of the agent providing them

These differences are highlighted in the examples with comments.

For a detailed description of available fields, see the Tool Configuration Fields section.

Example YAML (customer_skills.yaml):

kind: Plugin
name: Customer Support Skills
description: Skills for customer service operations
dependencies:
  - customer_skills_impl.py
skills:                      
  - kind: Skill              # Defines that this is a skill, not a tool
    object_name: LoadCustomerData
    name: LoadCustomerData
    description: Automatically loads customer data at the start of the session
    parameters: []           # Usually empty, as skills rely on system arguments
    implementation: customer_skills_impl.load_data

Ensure that the skill name in the workflow matches the plugin definition exactly. If a skill name is misspelled or not registered, it will not be executed.

Correct ✅	Incorrect ❌
Plugin skill name: LoadCustomerData Workflow: LoadCustomerData	Plugin skill name: LoadCustomerData Workflow: LoadCustomerDataS (extra character)

Skill Implementation (Python)

When implementing a skill in Python, the platform automatically injects standard arguments with a __ prefix.

Important Note: __sys_parameters are also passed as **kwargs directly to skills. For example, if system parameters contain the key client_id, it will be available in the skill code as kwargs.get('client_id').

Here is how the implementation for the YAML example above looks in Python:

from loguru import logger

async def load_data(__global_heap: dict, **kwargs):
    """
    Python implementation for the LoadCustomerData skill.
    """
    # Accessing sys_parameters passed directly to kwargs
    client_id = kwargs.get('client_id')
    
    if client_id:
        logger.info(f"Skill triggered: Loading data for client {client_id}")
        
        # Modifying the global heap so tools can use this data later
        __global_heap["customer_segment"] = "VIP"
    else:
        logger.warning("No client_id found in system parameters.")

Standard Arguments Passed to Skills

Standard arguments are injected automatically by the platform. You do not need to declare them in the skill parameters section.

Argument	Type	Purpose
__data_model	dict[str, FormInfoField]	Conversation result fields
__chat_history	list[Record]	Conversation history (messages from user and agent)
__env_parameters	dict	Environment parameters
__sys_parameters	dict	Session-related constants
__global_heap	dict	Shared dictionary for passing data between skill and tool calls within the same session
__statemachine	StateMachine	Configuration of the process states
__flow_config	FlowConfig	Configuration of the current process
__event_name	str	Name of the event which triggered this skill execution

💡 Tip: For information on types of those fields refer to section tools argument details.

Custom Skill Parameters

A skill can define custom input parameters in the plugin YAML under parameters.

Custom parameters:

• are declared explicitly in the skill configuration
• are specific to a particular skill
• are passed to the skill as input data during execution

Custom skill parameters are not configured in state definitions. Their values come from data collected earlier in the conversation. For example, form fields or conversation results.

Skills execution on state changes

In every state you can configure two following lists:

• init_skills — skills from this list will be executed on state entry
• finalization_skills — skills from this list will be executed on state exit

Example:

init_state: true
final_state: true
init_skills:
  - InitState
finalization_skills:
  - FinalizeState

Also skill can be configured to be called on session start.

Example:

kind: Plugin
name: Customer Support Skills
description: Skills for customer service operations
session_init_call: true      # This skill will be called on session start
dependencies:
  - customer_skills_impl.py
...

⚠️ Note: Skills executed on state entry or exit are blocking. The workflow waits until the skill execution finishes before continuing the state transition.

---

Related Resources

• Workflow Configuration Guide
• Knowledge Base Setup