Skillsets

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

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:

Parameter Example

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

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

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

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, or json. For example, HTML pages can be converted to markdown for easier interpretation
• jsonpath: Use JSONPath to extract specific sections of JSON responses
• jmespath: Use JMESPath to extract specific sections of JSON responses

Example

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

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

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:

With Prefix for Namespacing:

Available MCP Integrations

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

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

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

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

Packs - Combining Multiple Abilities

A pack is a special action type that bundles multiple abilities together and uses an AI sub-agent to coordinate their execution. This is useful when you want to expose many related abilities to your bot while keeping token costs low and reducing complexity.

For example, ChatBotKit has over 20 different Google Drive-related tasks. By combining these into one pack, you can expose all those capabilities through a single ability, and the pack's internal AI decides which specific actions to take based on the user's request.

How Packs Work

When a pack ability is triggered, it spawns a sub-agent that has access to all the abilities bundled inside the pack. This sub-agent analyzes the task, determines which abilities to use, and executes them in the appropriate order. The results are then returned to the main conversation.

This approach has several benefits:

• Reduced token usage: Only one ability description is sent to the main bot, instead of dozens of individual abilities
• Better organization: Related abilities are grouped logically
• Automatic coordination: The pack's sub-agent handles multi-step workflows
• Simpler bot configuration: Attach one pack instead of many abilities

Properties

• backstory: Optional context for the sub-agent explaining its role
• model: The AI model to use for the sub-agent (defaults to claude-4.5-sonnet)
• task: The task description to pass to the sub-agent
• context: Optional key-value data to provide additional context
• abilities: Array of ability templates or inline ability definitions

Example

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
• Complex workflows: When tasks require multiple steps that need coordination
• Token budget concerns: Reduce the number of ability descriptions sent to the main bot

Tips for Creating Effective Packs

• Write a clear backstory: This helps the sub-agent understand its purpose
• Group by service or domain: Keep abilities that work together in the same pack
• Provide context when needed: Use the context property to pass relevant data
• Test with realistic tasks: Make sure the sub-agent correctly interprets and executes multi-step requests