Overview of how chatbot Skillsets and Skillset instructions work. Learn how to customize your chatbot's abilities and improve its performance.

Skillsets are instructions to your chatbot that are defined in natural language. They allow your chatbot to understand user intent and propose a suitable action based on the conversation. For example, if a user asks your chatbot to fetch the weather forecast for a specific location, the skillset will tell the chatbot how to extract the location from the conversation and use it to search for the weather forecast.

To access a skillset, you must specify the skillset id when starting a conversation with a chatbot. Typically the skillset is configured into the bot. There is only one skillset allowed per conversation / bot. The number of skillset you can have is determined by your monthly membership or subscription plan. If you need more skillsets, you can upgrade your plan or contact customer service for more information.

Understanding Abilities

Skillsets are made of abilities. Each ability has a number of fields which define the name, the purpose of the ability as well as how the ability will be used during the conversation:

  • name - a short but descriptive name for the ability
  • description - a short description for the ability
  • instruction - specific instructions how to apply the ability

Both the name and description fields are used during the intent detection stage of the conversation, i.e. when your bot is trying to figure out what it needs to do to serve the end user. The instruction field is only used once this specific ability is selected. The instruction is applied with the conversation in mind to fulfil the end user request.

It is essential to keep the name and description fields descriptive but not too long as they will be used during every stage of the conversation, thus consuming tokens. The instruction field can be much longer. It will be used only once per user request but still contributes to the total token usage.

Understanding Actions

A key component to an ability is to perform an action, such as fetch a web page. The action needs to be specified in markdown-style code block (fenced code block) with triple backtick notation. You must specify the action name after the first 3 backticks. This is similar to how you use fenced code blocks with language identifiers. For example:

```fetch POST https://some/url HTTP/1.1 Content-Type: application/json { "param": "value" } ```

The action can be mixed with free-form text instructions. These instructions define how the action need to be applied. It is recommended to be as descriptive as possible to ensure the action is applied as consistently as possible.

Consider the following table that summarises the list of available actions and properties:

search-Searches a dataset with a specific phrase.
datasetIdThe Id of the dataset to search for.
fetch-Fetches a URL. You can also use a full HTTP request. The action has builtin timeout and retry logic.
timeoutA parameter that controls the maximum timeout in milliseconds. By the default fetch action wait for 10 seconds (10000 ms) before aborting the request.
formatSpecifies the output format of the actions. Available options are text, markdown and json. For example, it makes sense to convert (format) HTML page to markdown so that they can be easily interpreted by your bot.
jsonpathUse can use a JSONPath to extract a specific section of a JSON document returned by the web request performed by the fetch action.
jmespathUse can use a JMESPath to extract a specific section of a JSON document returned by the web request performed by the fetch action.
email-Sends an email.
toThe email address to send the message to.
replyToThe email address to use for the reply-to email field.
subjectThe subject for the email. If not provided a default subject will be used.
view-Use vision model to describe an image from external URL. The input for the action must contain a URL string and optionally some description.
text-Generates text using input text as a prompt.
modelAny of the supported ChatBotKit language models can be used as the base model for the text: i.e. gpt-3.5-turbo, gpt4, mistral-large, etc.
image-Generates an image using input text as a prompt.
modelAny of the supported ChatBotKit image models can be used as the base model for the image, i.e. stablediffusion, dalle2 or dalle3, etc.
sizeAny of the supported sizes: 256x256 , 512x512 , or 1024x1024

Actions and other parts of the ability instruction can be customised with the help of parameters. This feature enables chatbots to perform a wide array of actions more effectively, from fetching data online to processing user requests, by understanding the context and specifics of each command. We support a wide range of flexible syntax, including ${name} or {{name}}, with descriptions added as ${name:A longer description} or using the separator | for alternative formats like ${name|A longer description}.

Using Parameters

Actions can be parametrised using several ${name} {{name}} $[name] and [[name]] syntax. The ${name} and {{name}} syntax can be used to access secrets and conversation information during action execution. The $[name] and [[name]] can to construct input parameters that will be filled in by the user (automatically through conversation).

Consider the following table as a guide:

${SECRET_NAME} or {{SECRET_NAME}}Use a secret defined by name.
${CONVERSATION_ID} or {{CONVERSATION_ID}}Use the current conversation id.
${CONVERSATION_META_FIELD} or {{CONVERSATION_META_FIELD}}Access a “field” from the meta properties of a conversation.
`$[paramparameter description]or[[param

Getting Started Examples

Fetching Pages

Consider the following skillset ability instruction that allows your chatbot to fetch and display web pages when requested by the user:

When the user asks the bot to read, fetch, or pull a web page, the bot must only output the URL of the root webpage as a markdown code block, with the language specified as "fetch". For example: ```fetch/format=markdown URL of the webpage, e.g https://... or HTTP request ```

This Skillset instruction tells the chatbot to listen for user requests to fetch web pages. When the chatbot detects such a request, it will output the URL of the requested web page in a markdown code block, using the identifier specified as fetch. If the user asks a question that is not related to fetching a web page, the chatbot will reply with a message indicating that it is unable to fulfil the request.

Retrieving Weather Forecast

Consider the following skillset ability instruction that allows your chatbot to fetch the latest weather forecast given a location:

To get the weather you need to perform the following request: ```fetch GET https://wttr.in/{location}?format=4 HTTP/1.1 User-Agent: curl/7.61.1 ``` The {location} parameter could be any city. For example: ```fetch GET https://wttr.in/London?format=4 HTTP/1.1 User-Agent: curl/7.61.1 ``` Multiple locations can be requested like this: ```fetch GET https://wttr.in/{London,Paris}?format=4 HTTP/1.1 User-Agent: curl/7.61.1 ``` The response is a text document with weather information.

Notice that we have described multiple examples how to fetch the weather based on the user-supplied input. The weather forecast will be obtained in accordance to these instructions.

Searching Dataset

The following skillset ability can be used to search a specific dataset for more information. Notice the datasetId field which points to the specific Dataset to be searched. We also use a parameterized input called query that also has a description to help the underlaying model pick the right search phrase.

```search/datasetId=clvmk6ksl0039vsm3k5wve3pp ${query|The search query related to search for information} ```

Sending Support Email

The following skillset ability can be used to summarise the current conversation and send a support email. Notice that we use the replyTo field in order to be able to reply to the user:

To email customer support use need to use the following action: ```email/to=contact@acme.com/replyTo={user email} [The summary of the conversation] ``` For example, if the user is asking for help and their email is test@test.com the action will be: ```email/to=contact@acme.com/replyTo=test@test.com [The summary of the conversation] ```

Generating Text

Consider the following skillset ability instruction that allows your chatbot to generate text based on user input:

To generate a song based on user input, perform the following action: ```text/model=gpt-3.5-turbo The user's input text converted to a prompt suitable for song generation ```

If the user asks a bot write a song, their input will be combined with the instructions in the ability to create the final action.

Generating an Image

Consider the following skillset ability instruction that allows your chatbot to generate an image based on user input:

To generate an image based on user input, perform the following action: ```image/model=stablediffusion The user's input text ```

You can specify further enhancements to the prompt used to generate the image. Have a look at the following hub examples:

  • Logo Maker - A skillset that helps you create logos using DALL-3.
  • Fashion AI 2.0 - Fashion AI is an advanced tool that leverages DALL-E 3 to enhance your ability to create stylish outfits with its comprehensive skillset.
  • Fashion AI 1.0 - Fashion AI powered by DALL-E 2 utilizes a skillset to effortlessly curate stylish outfits.

Using Parameters

Consider the following skillset ability instruction which uses parameters to provide further hints what input is expected in order to perform the fetch action:

```fetch POST https://httpbin.org/anything/collect/details Content-Type: application/json Test: Token ${SECRET_TEST} { "name": "${name: The name of the user.}" "email": "${email: The email of the user.}" } ```

In this example we call the fetch action as we normally do but there is a small difference. Rather than leaving the request parameters open to interpretation, we can provide additional hints. Notice that both the name and email JSON fields are clearly specified with the corresponding field name and description.

This process not only enhances the model's performance but also enriches the user experience by ensuring more relevant and accurate interactions.

How to create a Skillset

Follow these instructions to create a new skillset.

  1. Got to "Skillsets" from the navigation bar.
  2. Click "Create Skillset" button.
  3. Name your skillset and provide description.
  4. Save the skillset by clicking on the "Create" button.

Now you have an empty skillset but you do not have any abilities. Creating abilities is also very easy.

  1. With your skillset selected, click on the "Create Ability" button.
  2. Specify the ability name and description.
  3. Specify the ability instruction, be aware of the total token count.
  4. Save the new skillset ability by clicking on the "Create" button.


Overall, Skillsets are a powerful tool for customizing your chatbot's abilities and improving its performance. They allow you to define specific instructions for your chatbot in natural language, allowing it to better understand and respond to user requests. By creating and managing Skillsets, you can ensure that your chatbot is always ready to meet the needs of your users.


Do you provide any logs detailing the execution of actions?

Yes, we do provide detailed logs that track the execution of actions. These logs can be extremely helpful for debugging and understanding how your chatbot is performing. The logs can be accessed either in the skillset events or the events listed on action ability.

Does the fetch action supports automatic retries?

Yes, the fetch action has a built-in retry logic. If the initial request fails, the action will automatically retry 3 times with exponential delay of 1 second.