Skillsets

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.

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.

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.

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.

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.

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.

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