---
title: Skillsets
description: Overview of how chatbot Skillsets and Skillset instructions work. Learn how to customize your chatbot's abilities and improve its performance.
category: Resources
tags:
  - skillsets
  - abilities
  - actions
  - tools
  - skills
---
Skillsets are collections of abilities that teach your AI bots how to perform specific actions and tasks. Think of a skillset as giving your bot a toolbox of capabilities - from simple actions like fetching web pages or searching data, to complex operations like sending emails, creating calendar events, or analyzing documents.

When you connect a skillset to your bot, the AI automatically understands what actions it can take and when to use them. For example, if your bot has a skillset with email-sending abilities, it can automatically send confirmation emails when users request them, or trigger notifications based on conversation context.

## What You Can Do with Skillsets

**Create Custom Actions**: Build skillsets that give your bots the exact capabilities your business needs. Whether you need to connect to your internal APIs, interact with external services, or perform specialized tasks, skillsets make it possible.

**Connect to Services**: Integrate with popular tools and platforms like Slack, Gmail, Google Calendar, Airtable, and hundreds of others. Each connection becomes an ability your bot can use automatically during conversations.

**Combine Abilities**: A single skillset can contain multiple related abilities. For example, a "Customer Support" skillset might include abilities to search your knowledge base, create support tickets, send email notifications, and update your CRM - all working together seamlessly.

**Reuse Across Bots**: Once you create a skillset, you can attach it to multiple bots. This means you can build a library of capabilities once and use them across your entire organization.

## How Skillsets Work

Every skillset has a **name** and **description** that help both you and your AI understand its purpose. Importantly, these aren't just labels - the AI actually reads and uses this information to understand when and how to use the skillset's abilities. Think of it as giving your bot context about the tools it has available.

Inside each skillset, you add **abilities** - individual actions the bot can perform. Each ability includes detailed instructions that tell the AI exactly how to execute that action, what information it needs, and how to handle the results.

When your bot is having a conversation, it can see all the abilities from its connected skillsets. The AI analyzes what the user is asking for, determines which ability (if any) would be helpful, and executes it automatically. The results are then incorporated naturally into the conversation.

## Getting Started

Creating your first skillset is simple:

1. Click **"Create Skillset"** from your Skillsets dashboard
2. Give it a **descriptive name** that clearly indicates its purpose (like "Customer Support Tools" or "Sales Assistant")
3. Add a **detailed description** explaining what capabilities this skillset provides and when to use them - remember, the AI reads this!
4. Start adding **abilities** - you can build custom abilities or use pre-made templates for popular services
5. **Connect the skillset** to your bots by editing the bot settings and selecting the skillset

You can create as many skillsets as you need. Many users organize them by function (Support, Sales, Operations) or by service (Gmail Integration, Database Tools, Analytics).

**Note on Skillsets and AI Skills:** ChatBotKit Skillsets share properties and
behaviors with what are now commonly known as "skills" in AI systems (such as
those popularized by Anthropic's Claude), although ChatBotKit's skillsets
pre-date this terminology. Like modern AI skills, a skillset's **name and
description are automatically known to the AI agent** and directly influence its
behavior. The agent uses these fields to understand when and how to apply the
skillset's capabilities. Additionally, connected abilities provide the agent
with detailed information about how to use each connected capability, making
skillsets a comprehensive system for extending AI agent functionality.

## Tips for Success

**Write Clear Names and Descriptions**: Since the AI reads your skillset's name and description, make them informative. Instead of "Tools," try "Customer Support Knowledge Base and Ticketing Tools." This helps the AI understand when these abilities are relevant.

**Group Related Abilities**: Keep abilities that work together in the same skillset. For example, if you have abilities for reading and writing to a database, keep them together so the AI can perform complete workflows.

**Start Simple**: Begin with one or two abilities and test them thoroughly before adding more. This makes it easier to troubleshoot and understand how your bot behaves.

**Test in Conversations**: Use the built-in chat feature on each skillset's page to test how your abilities work in real conversations. This helps you refine the instructions and see what the AI understands.

**Keep Abilities Focused**: Each ability should do one thing well. Instead of one giant "handle customer request" ability, create separate abilities for "search knowledge base," "create ticket," and "send notification." The AI can combine them as needed.

## Configuring Your Skillset

When you're setting up or editing a skillset, you have several important configuration options that control how your bot understands and uses the abilities you've defined.

### Name and Description Matter

The most important thing to understand about skillsets is that the **name** and **description** fields aren't just for your reference - the AI actually reads and uses them to understand what the skillset does and when to use its abilities. This is a powerful feature that helps your bot work more intelligently.

When you write your skillset name, be descriptive and specific. Instead of just "Tools," use something like "Customer Support and Knowledge Base Tools." This immediately tells the AI (and your team) what this skillset is designed for.

The description field is even more important. Use it to explain:
- What types of tasks this skillset helps with
- When the bot should consider using these abilities
- Any important context about how the abilities work together

For example: "This skillset provides customer support capabilities including searching our product documentation, creating support tickets, and sending follow-up emails. Use these abilities when customers need help with product questions or technical issues."

### Adding Abilities

The heart of any skillset is its abilities - the individual actions your bot can perform. After creating a skillset, you'll need to add at least one ability before your bot can do anything with it.

Click **"Create Ability"** to add a new capability. You can either:
- **Build a custom ability** by writing your own instructions and configuration
- **Use a template** to quickly set up common integrations with popular services

Each ability you add appears in the Skillset Abilities list, where you can edit, test, or remove them as needed.

### Testing Your Skillset

One of the most valuable features is the built-in chat interface available on every skillset's page. This lets you test your abilities in real conversations before deploying them to your production bots.

The test chat creates a temporary bot that uses only this skillset, so you can see exactly how the AI interprets your abilities and when it chooses to use them. Try different conversation styles and requests to ensure your abilities trigger appropriately.

When testing, pay attention to:
- **Does the AI understand when to use each ability?** If not, refine your skillset description and ability instructions
- **Do the abilities return the right information?** Check that the data or actions match what you expect
- **Does the conversation flow naturally?** The AI should incorporate ability results smoothly into its responses

### Visibility Settings

Under Advanced Options, you can control who has access to your skillset:
- **Private**: Only you can see and use this skillset
- **Protected**: You and your team members (sub-accounts) can access it
- **Public**: Available to all platform users - useful if you're sharing a useful integration with the community

Most users keep skillsets private unless they're specifically designed for sharing.

### Connecting to Bots

Once your skillset is configured and has abilities, you can connect it to any of your bots. Go to the bot's settings page and select your skillset from the available options. You can connect multiple skillsets to a single bot, giving it access to all the combined abilities.

Remember that the bot sees all abilities from all connected skillsets, so organize your skillsets thoughtfully to avoid overwhelming the AI with too many unrelated options.

## 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.

## Using Actions in Abilities

The instruction field is where you specify what your ability should do. You can include actions that your AI agent will execute, along with text instructions that guide when and how those actions should be used. Be as descriptive as possible to ensure your ability works consistently.

## Actions - The Building Blocks of Abilities

Actions are the executable components within skillset abilities that perform specific tasks. Each action is specified using a markdown-style code block (fenced code block) with triple backtick notation, where you specify the action name after the first 3 backticks - similar to how you use fenced code blocks with language identifiers.

### Action Syntax Example

`````markdown
```fetch
url: https://api.example.com/data
method: POST
headers:
  Content-Type: application/json
  Authorization: Bearer ${API_KEY}
body:
  query: $[query! ys|the search query]
```
`````

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

## Using Parameters

Actions and other parts of the ability instruction can be customized with parameters. Parameters allow you to create dynamic abilities that adapt based on user input, secrets, or conversation context.

### Parameter Syntax

ChatBotKit supports several parameter syntaxes for different purposes:

| Syntax                                                                | Description                                                  |
| --------------------------------------------------------------------- | ------------------------------------------------------------ |
| `${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. |
| `$[param|parameter description]` or `[[param|parameter description]]` | Define a parameter to be filled by the AI from user input.   |

### Parameter Example

Here's an example showing how to use parameters in a fetch action:

`````markdown
```fetch
url: https://httpbin.org/anything/collect/details
method: POST
headers:
  Content-Type: application/json
  Authorization: Bearer ${SECRET_TEST}
body:
  name: $[name! ys|The name of the user]
  email: $[email! ys|The email of the user]
```
`````

In this example:
- `${SECRET_TEST}` references a secret for authentication
- `$[name! ys|...]` and `$[email! ys|...]` are required parameters that the AI will extract from the user's input
- The `!` marks them as required, `ys` handles YAML string escaping
- The descriptions after `|` help guide the AI in understanding what information to extract

## Rating Actions

Rating actions let skillsets create, inspect, list, and delete structured
feedback records for bots and contacts using the current conversation scope.

## Search Action - Finding Information

The search action allows your chatbot to search the web or specific datasets for information. It supports different search types including web, news, images, and videos. You can also search your own datasets by providing a dataset ID.

### Properties

- **type**: The web search to perform - valid values are `web`, `news`, `images`, and `videos`
- **datasetId**: The ID of the dataset to search within your ChatBotKit account

### Example

`````markdown
```search
datasetId: ((datasetId! ys|the dataset ID to search))
query: $[query! ys|the search query]
```
`````

## Fetch Action - Retrieving External Data

The fetch action allows your chatbot to retrieve data from external URLs and APIs. It supports full HTTP requests with customizable headers, authentication, and response formatting. The action has built-in timeout and retry logic to ensure reliable data retrieval.

### Properties

- **timeout**: Controls the maximum timeout in milliseconds (default: 10000 ms / 10 seconds)
- **format**: Specifies output format - `text`, `markdown`, `json`, or `toon`. Use `toon` for token-optimized notation that reduces token usage when passing data to LLMs
- **jsonpath**: Use JSONPath to extract specific sections of JSON responses
- **jmespath**: Use JMESPath to extract specific sections of JSON responses

### NDJSON Support

The fetch action automatically parses newline-delimited JSON (NDJSON) responses when the content type is `application/x-ndjson` or `application/jsonl`. Each line is parsed as a separate JSON object and combined into an array. JSONPath, JMESPath, and toon format transformations work seamlessly with NDJSON data.

### Example

`````markdown
```fetch
url: $[url! ys|the URL to fetch]
format: ((format ys|output format: text, markdown, json, or toon))
```
`````

## Email Action - Sending Messages

The email action allows your chatbot to send emails to specified recipients. This is useful for notifications, support requests, confirmations, and other communication needs.

### Properties

- **to**: The email address to send the message to (required)
- **replyTo**: The email address to use for the reply-to field
- **subject**: The subject for the email. If not provided, a default subject will be used

### Example

`````markdown
```email
to: $[to! ys|recipient email address]
replyTo: $[replyTo ys|sender email address for replies]
subject: $[subject ys|email subject line]
content: $[content! ys|the message to send]
```
`````

## Time Action - Current Date And Time

The time action returns the current date and time in a single requested
format. Use it when an ability needs a reliable timestamp without calling an
external service.

### Properties

- **timezone**: Optional IANA timezone for `time.now`, such as `UTC` or `America/New_York`. Defaults to the request context timezone when available
- **format**: Optional output format for `time.now`: `datetime`, `date`, `time`, `iso`, or `unix`

### Example

`````markdown
```time.now
timezone: ((timezone ys|optional IANA timezone such as UTC or Europe/London))
format: ((format ys|optional output format: datetime, date, time, iso, or unix))
```
`````

## View Action - Image Analysis

The view action uses a vision model to describe and analyze images from external URLs. The input for the action must contain a URL string and optionally some description or instructions for what to look for in the image.

This action is useful for:
- Describing images for accessibility
- Extracting text from images (OCR)
- Identifying objects, people, or scenes
- Answering questions about image content
- Verifying image content matches requirements

The view action will analyze the image at the provided URL and return a detailed description based on the vision model's capabilities.

### Example

`````markdown
```view
url: $[url! ys|the URL of the image to analyze]
instructions: $[instructions ys|what to look for in the image]
```
`````

## MCP Action - Model Context Protocol Integration

The Model Context Protocol (MCP) action provides a powerful way to dynamically extend your skillset's capabilities by loading tools from external MCP servers. MCP is an open standard that enables AI applications to seamlessly connect to external data sources and tools. ChatBotKit's MCP action implementation allows your skillsets to discover and utilize MCP-compatible tools in real-time.

### What is MCP

Model Context Protocol (MCP) is an open standard that provides a unified way for AI applications to connect with external tools and data sources. Instead of building custom integrations for every service, MCP provides a standardized interface that allows AI models to discover available tools, understand their capabilities, and execute them safely and securely.

### How MCP Actions Work

When you use an MCP action in your skillset, ChatBotKit:

1. **Connects** to the specified MCP server endpoint
2. **Discovers** available tools and their schemas
3. **Loads** the tool definitions into your conversation context
4. **Enables** your chatbot to use these tools as if they were native abilities
5. **Maintains** secure execution through proper authentication and isolation

### MCP Action Syntax

The MCP action supports flexible syntax for loading tools from different sources:

Basic URL Loading:

`````markdown
```mcp/install
https://mcp.example.com/tools
```
`````

With Prefix for Namespacing:

`````markdown
```mcp/install
url: https://mcp.notion.com/mcp
prefix: notion
```
`````

### Available MCP Integrations

ChatBotKit provides built-in support for several popular MCP servers:

| Service        | URL                                                              | Prefix       | Capabilities                                        |
| -------------- | ---------------------------------------------------------------- | ------------ | --------------------------------------------------- |
| **Notion**     | [https://mcp.notion.com/mcp](https://mcp.notion.com/mcp)         | `notion`     | Page management, database queries, content creation |
| **Linear**     | [https://mcp.linear.app/mcp](https://mcp.linear.app/mcp)         | `linear`     | Issue tracking, project management, team workflows  |
| **Box**        | [https://mcp.box.com/](https://mcp.box.com/)                     | `box`        | File management, sharing, cloud storage             |
| **Stripe**     | [https://mcp.stripe.com](https://mcp.stripe.com/)                | `stripe`     | Payment processing, subscription management         |
| **PayPal**     | [https://mcp.paypal.com/mcp](https://mcp.paypal.com/mcp)         | `paypal`     | Payment processing, transaction management          |
| **Sentry**     | [https://mcp.sentry.io/mcp](https://mcp.sentry.io/mcp)           | `sentry`     | Error tracking, performance monitoring              |
| **Cloudinary** | [https://mcp.cloudinary.com/mcp](https://mcp.cloudinary.com/mcp) | `cloudinary` | Media management, image/video transformation        |
| **Canva**      | [https://mcp.canva.com/mcp](https://mcp.canva.com/mcp)           | `canva`      | Design creation, template management                |

### Integration Benefits

Using MCP actions in your skillsets provides several advantages:

- **Dynamic Loading**: Tools are loaded on-demand, reducing initial setup complexity
- **Real-time Updates**: Changes to MCP servers are automatically reflected in your abilities
- **Standardized Interface**: Consistent tool discovery and execution across different services
- **Secure Execution**: All tool calls maintain ChatBotKit's security and access control
- **Namespace Support**: Prefixes prevent naming conflicts when using multiple MCP servers

### Best Practices for MCP Actions

- **Test Tool Availability**: Always verify that MCP tools are loaded before attempting complex operations
- **Use Descriptive Prefixes**: Choose clear, service-specific prefixes to avoid confusion
- **Handle Loading Errors**: Consider what happens if an MCP server is unavailable
- **Document Dependencies**: Clearly specify which MCP tools your abilities require
- **Monitor Performance**: Some MCP operations may take longer than local actions

### Example

`````markdown
```mcp/install
url: ((url! ys|the MCP server URL))
prefix: ((prefix ys|namespace prefix for tools))
```
`````

## Text Action - Generating Content

The text action generates text content using a language model based on the input prompt. This is useful for creating dynamic content, transforming text, generating creative writing, or producing structured output.

### Properties

- **model**: Any of the supported ChatBotKit language models can be used, such as `gpt-3.5-turbo`, `gpt-4`, `claude-3-opus`, `mistral-large`, etc.

### Example

`````markdown
```text
model: ((model ys|the language model to use))
input: $[input! ys|the text generation prompt]
```
`````

## Image Action - Generating Images

The image action generates images using AI models based on text prompts. This is useful for creating visual content, illustrations, logos, product mockups, or any other image-based assets.

### Properties

- **model**: Any of the supported ChatBotKit image models, such as `stablediffusion`, `dalle2`, or `dalle3`
- **size**: Supported sizes include `256x256`, `512x512`, or `1024x1024`

### Example

`````markdown
```image
model: ((model ys|the image model to use))
size: ((size ys|image dimensions))
prompt: $[prompt! ys|the image generation prompt]
```
`````

## Packs - Installing Multiple Abilities at Once

A pack is a special action type that installs multiple abilities into the
current conversation context. When triggered, the pack unpacks each ability
and registers them as callable tools, allowing the main bot to use them
directly without a sub-agent.

For example, ChatBotKit has over 20 different Google Drive-related tasks. By
combining these into one pack, you can install all those capabilities through
a single ability call. The bot then has direct access to each individual tool.

### How Packs Work

When a pack ability is triggered, it resolves each ability in the list
(either from the template catalogue or inline definitions), extracts their
parameters, and installs them as environment tools in the conversation. The
main bot can then call these tools directly.

This approach has several benefits:

- **Reduced token usage**: Only one ability description is sent to the main
  bot initially, instead of dozens of individual abilities
- **Better organization**: Related abilities are grouped logically
- **Direct execution**: The main bot calls tools directly for better accuracy
- **Simpler bot configuration**: Attach one pack instead of many abilities

### Properties

- **abilities**: Array of ability templates or inline ability definitions
- **prefix**: Optional prefix for installed tool names

### Example

`````markdown
```pack
abilities:
  - google-drive-list-files
  - google-drive-create-file
  - google-drive-delete-file
  - google-drive-share-file
```
`````

### When to Use Packs

Use packs when you have:

- **Many related abilities**: Group abilities for a single service (Google Drive,
  Slack, your internal API) into one pack
- **Dynamic tool loading**: When you want to install tools on demand rather than
  having them all available from the start
- **Token budget concerns**: Reduce the number of ability descriptions sent to
  the main bot until they are needed

### Tips for Creating Effective Packs

- **Group by service or domain**: Keep abilities that work together in the same pack
- **Use prefixes**: Add a prefix to avoid name collisions when installing
  multiple packs
- **Mix templates and inline**: You can combine catalogue templates with custom
  inline ability definitions in the same pack