---
title: Skillsets
description: Skillsets are collections of abilities that define what actions your AI agents can perform, from fetching web data to sending emails and generating content.
category: Resources/Skillsets
tags:
  - skillset
  - abilities
  - actions
index: 7
source:
  - pages/api/v1/skillset/create.js
  - pages/api/v1/skillset/[skillsetId]/delete.js
  - pages/api/v1/skillset/[skillsetId]/fetch.js
  - pages/api/v1/skillset/[skillsetId]/update.js
  - pages/api/v1/skillset/list.js
---

Skillsets are powerful collections of abilities that define the actions your AI
agents can perform. Think of a skillset as a toolbox that gives your agent
specific capabilities - from fetching web pages and searching datasets to
sending emails and generating images. Each skillset contains multiple abilities,
and each ability contains detailed instructions for how to execute a specific
action.

When you attach a skillset to a conversation or agent, the AI can automatically
detect user intent and execute the appropriate abilities to fulfill requests.
This makes your agents significantly more capable and interactive, enabling
them to take real actions rather than just generating text responses.

**Note on Skillsets and Skills:** Skillsets in ChatBotKit have properties and
behavior similar to what are now commonly known as "skills" - a concept
popularized by Anthropic and other AI providers. However, ChatBotKit's skillset
implementation pre-dates this terminology. An important aspect of skillsets is
that the skillset's name and description are automatically known to the AI agent,
which directly impacts the agent's behavior and decision-making. When abilities
are connected to a skillset, they provide structured information that tells the
agent how to use those connected abilities effectively. This seamless integration
allows agents to understand both what capabilities they have available and how to
properly utilize them during conversations.

## Creating Skillsets

Creating a skillset is the foundation for building capable AI agents. When you
create a skillset, you're establishing a container for abilities that your
agents will be able to use during conversations. The skillset acts as a logical
grouping of related capabilities, making it easier to manage and reuse
functionality across multiple agents.

To create a skillset, you need to provide basic information including a name
and description. The name should clearly indicate the skillset's purpose, while
the description helps you and your team understand what capabilities this
skillset provides. You can also configure visibility settings to control
whether the skillset is private to your account or can be shared with others.

```http
POST /api/v1/skillset/create
Content-Type: application/json

{
  "name": "Customer Support Toolkit",
  "description": "Abilities for handling customer support inquiries including knowledge base search, ticket creation, and email notifications",
  "visibility": "private"
}
```

The API will return the ID of the newly created skillset, which you can then
use to add abilities. After creating a skillset, your next step is typically
to add abilities that define specific actions the agent can perform. You can
add abilities one at a time or use ability templates to quickly set up common
functionality.

**Important Notes:**

- Skillsets start empty - you need to add abilities separately after creation
- The visibility setting controls who can see and use the skillset
- You can optionally link skillsets to blueprints for organized project management
- Skillset names should be descriptive to make them easy to identify later
- Consider creating separate skillsets for different functional areas (support, sales, analytics)

## Deleting Skillsets

When a skillset is no longer needed, you can permanently delete it from your
account. This operation removes the skillset and all of its associated
abilities in a single action. Deleting skillsets is useful for cleaning up
test configurations, removing deprecated functionality, or simplifying your
skillset library.

Before deleting a skillset, it's important to understand the implications.
When you delete a skillset, all abilities contained within it are also
removed. Any conversations or agents that reference the deleted skillset will
no longer have access to those capabilities. This is an irreversible operation,
so ensure you have backups or exports of any abilities you might need later.

```http
POST /api/v1/skillset/{skillsetId}/delete
Content-Type: application/json

{}
```

The deletion process handles all cleanup automatically, including removing
ability records and any associated metadata. If the skillset is part of a
blueprint, the blueprint structure is updated to reflect the removal. However,
the deletion does not affect historical conversation data - past conversations
that used the skillset remain intact, but they cannot access the deleted
abilities for new interactions.

**Warning:**

- Deletion is permanent and cannot be undone
- All abilities within the skillset are deleted along with the skillset
- Active conversations using this skillset will lose access to its capabilities
- Consider exporting ability configurations before deletion if you might need them later
- Verify the skillset is not in use by critical agents before deleting

## Fetching Skillset Details

Retrieving detailed information about a specific skillset allows you to
inspect its configuration, properties, and metadata. This is essential for
debugging, auditing, or displaying skillset information in your application's
user interface. The fetch operation returns complete details about the
skillset, including when it was created and last modified.

When you fetch a skillset, you receive all of its properties including the
name, description, visibility settings, blueprint associations, and metadata.
However, the fetch operation does not include the list of abilities - you'll
need to use the ability list endpoint separately to retrieve those. This
separation allows for efficient querying when you only need the skillset's
basic information.

```http
GET /api/v1/skillset/{skillsetId}/fetch
```

The response includes timestamps that show when the skillset was created and
when it was last updated. These timestamps are useful for tracking changes,
implementing caching strategies, or displaying activity information to users.
The metadata field contains any custom data you've associated with the
skillset, which can be useful for storing application-specific information.

**Response includes:**

- Skillset ID and basic identification information
- Name and description for human-readable context
- Visibility settings that control access permissions
- Blueprint association for project organization
- Creation and modification timestamps
- Custom metadata if previously stored
- All configuration properties set during creation or updates

## Updating Skillsets

As your requirements evolve, you'll need to update skillset properties such as
the name, description, or visibility settings. Updating a skillset allows you
to refine its configuration without affecting the abilities it contains. This
is particularly useful when you want to reorganize your skillsets, clarify
their purposes, or adjust access controls.

When updating a skillset, you can modify any of the properties that were set
during creation, including the name, description, blueprint association, and
visibility settings. The abilities contained within the skillset remain
unchanged - you manage those separately through the ability endpoints.

```http
POST /api/v1/skillset/{skillsetId}/update
Content-Type: application/json

{
  "name": "Enhanced Customer Support Toolkit",
  "description": "Expanded abilities for comprehensive customer support including multi-language support and advanced analytics",
  "visibility": "private"
}
```

The update operation is atomic, meaning all changes are applied together or
none are applied if there's an error. This ensures your skillset always
remains in a consistent state. After updating a skillset, the changes take
effect immediately for any conversations or agents using that skillset.

**Important Considerations:**

- Updating a skillset does not modify its abilities - those must be updated separately
- Changes to skillset properties take effect immediately for active conversations
- You can change the blueprint association to reorganize your project structure
- Updating visibility affects who can see and use the skillset
- The skillset ID remains constant, so existing references remain valid

## Listing Your Skillsets

Retrieving a list of all your skillsets provides an overview of the
capabilities available across your account. This is essential for building
management interfaces, selecting skillsets to attach to agents, or auditing
your account's configuration. The list endpoint returns summary information
about each skillset, making it efficient for displaying large collections.

The list operation supports pagination through cursor-based navigation,
allowing you to retrieve skillsets in manageable batches. You can control the
order of results (ascending or descending by creation date) and the number of
items returned per request. This flexibility is important when dealing with
accounts that have many skillsets, as it enables you to build responsive user
interfaces that don't load excessive data at once.

```http
GET /api/v1/skillset/list?take=20&order=desc
```

Each skillset in the response includes key information such as the ID, name,
description, visibility settings, and timestamps. You can use the blueprint
filter to retrieve only skillsets associated with a specific project, or the
metadata filter to find skillsets with particular custom properties. The
response does not include the abilities within each skillset - those must be
retrieved separately for the specific skillsets you're interested in.

**Query Parameters:**

- `cursor` - Pagination cursor from a previous response to fetch the next page
- `order` - Sort order for results, either "asc" or "desc" (default: "desc")
- `take` - Number of skillsets to return per request (default: 20)
- `blueprintId` - Filter skillsets by blueprint association
- `meta` - Filter skillsets by custom metadata properties

**Use Cases:**

- Building skillset selection interfaces for agent configuration
- Displaying management dashboards with skillset inventory
- Implementing search and filtering functionality
- Exporting skillset metadata for analysis or backup
- Auditing skillset usage across your organization