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

__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 customer 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
• final_skills — skills from this list will be executed on state exit

Example:

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

Skills execution on session start and finish

Instead of tying a skill to a specific workflow state, you can configure it to run automatically at the very beginning or the very end of a customer session.

To do this, add the session_init_call: true or session_finish_call: true parameter directly to the skill definition.

info

Skills configured with these session lifecycle flags do not need to be added to your workflow YAML. As long as the plugin containing the skill is connected to your agent (Tool Group is On), the platform will automatically execute them at the appropriate time

Example: Skill executed on session start

kind: Plugin
name: Dynamic FAQs
description: Load and format llms.txt into FAQs
dependencies:
  - submodules/llms_faq_init_skill.py
skills:
  - kind: Skill
    name: TableOfContentsInit
    description: Generate LLMS table of contents
    session_init_call: true      # Triggers automatically when session starts
    public_available: false      # Keeps the skill internal
    implementation: llms_faq_init_skill.table_contents_init

Example: Skill executed on session finish

skills:
  - kind: Skill
    name: FinalEmail
    description: Send final summarised info via email
    session_finish_call: true    # Triggers automatically when session closes
    public_available: false
    implementation: email_final_bikes.send_final_email

note

Skills executed on state entry/exit or session start/finish are blocking. The workflow waits until the skill execution finishes before continuing the state transition or completing the session initialization

Related Resources

• Workflow Configuration Guide
• Knowledge Base Setup