Skillset Abilities

Abilities are the building blocks of skillsets, representing individual actions that your AI agents can perform. Each ability combines a natural language description with detailed executable instructions, allowing the AI to understand when to trigger the ability and how to execute it correctly. Think of abilities as the specific tools in your agent's toolbox - each one designed for a particular task.

When a user makes a request during a conversation, the AI examines the abilities in the attached skillset to determine which one matches the user's intent. The ability's description helps the AI understand what the ability does, while the instruction field contains the detailed implementation that gets executed when the ability is triggered. This separation between intent detection and execution allows for flexible and powerful agent behaviors.

Creating Abilities

Creating an ability involves defining three key components: a name that identifies the ability, a description that helps the AI understand when to use it, and detailed instructions that specify how to execute the action. The name should be concise and descriptive, while the description should focus on what the ability does and when it should be triggered. The instruction field is where you define the actual implementation using action code blocks and additional guidance.

Abilities can reference secrets for authentication, connect to files for context, or even delegate to other bots for complex workflows. These connections make abilities extremely flexible, allowing you to build sophisticated agent behaviors without hardcoding sensitive information or duplicating logic across multiple abilities.

POST /api/v1/skillset/{skillsetId}/ability/create
Content-Type: application/json

{
  "name": "Fetch Weather",
  "description": "Retrieves current weather information for a specified location using the weather API",
  "instruction": "```fetch\nGET https://api.weather.com/v1/current?location=$[location euc!|the city name]\nAuthorization: Bearer ${SECRET_WEATHER_API}\n```"
}

http

The instruction field uses a special syntax that combines markdown code blocks with action types (like fetch, search, email) and parameter placeholders. Parameters starting with $[...] are extracted by the AI from user messages, while parameters starting with ${...} reference secrets or conversation metadata. This parameterization system makes abilities dynamic and reusable across different contexts.

Key Components:

  • Name: Short, memorable identifier for the ability (e.g., "Fetch Weather", "Search Knowledge Base")
  • Description: Explains what the ability does and when to use it - this is crucial for intent detection
  • Instruction: Contains the executable action definition with parameters and implementation details
  • Secret: Optional reference to stored credentials for authenticated actions
  • File: Optional reference to documents or context that the ability should consider
  • Bot: Optional reference to another bot that this ability can delegate tasks to

Instruction Syntax Examples:

Fetch external data:

```fetch POST https://api.example.com/data Content-Type: application/json Authorization: Bearer ${SECRET_API_KEY} { "query": "$[query js|the search query]", "limit": 10 } ```

Search a dataset:

```search/datasetId=dataset_id_here $[query|what the user wants to search for] ```

Send an email:

```email/to=support@example.com/replyTo=$[email|user's email address] Please help this user: $[issue|description of their problem] ```

Best Practices:

  • Keep descriptions focused on user intent rather than technical implementation
  • Use clear parameter names that help the AI extract the right information
  • Include default values or constraints in parameter definitions when appropriate
  • Test abilities with various user inputs to ensure robust intent detection
  • Group related abilities into logical skillsets for better organization
  • Use secrets for API keys and sensitive data rather than hardcoding them
  • Consider using ability templates from the platform as starting points

Common Ability Patterns:

  • Data Retrieval: Fetching information from external APIs or databases
  • Search Operations: Querying datasets or knowledge bases for relevant information
  • Communication: Sending emails, notifications, or messages
  • Content Generation: Creating text, images, or other media using AI models
  • Workflow Triggers: Initiating processes in external systems
  • Delegation: Routing complex requests to specialized bots

Listing Abilities in a Skillset

To retrieve all abilities associated with a specific skillset, use the list endpoint. This operation provides a comprehensive view of all capabilities that have been added to a skillset, including their configuration, associated resources, and execution instructions. Understanding which abilities are available in a skillset is essential for managing bot capabilities, troubleshooting skill execution, and auditing skillset compositions.

Each ability represents a specific capability or action that bots can perform, such as querying external APIs, processing data, executing custom logic, or integrating with third-party services. When you list abilities, you can see the complete configuration of each ability including its instruction template, linked secrets for authentication, associated files for context, and connected bots that rely on specific abilities.

GET /api/v1/skillset/{skillsetId}/ability/list?take=50&order=desc
Content-Type: application/json

http

You can filter abilities by blueprint association if you're working with blueprint-based skillset organizations:

GET /api/v1/skillset/{skillsetId}/ability/list?blueprintId={blueprintId}
Content-Type: application/json

http

The response includes detailed information about each ability:

{
  "items": [
    {
      "id": "ability_abc123",
      "name": "Weather API Query",
      "description": "Fetches current weather data from external API",
      "instruction": "```fetch\\nmethod: GET\\nurl: https://api.weather.com/v1/current\\n```",
      "secretId": "secret_xyz789",
      "fileId": null,
      "botId": null,
      "skillsetId": "skillset_def456",
      "blueprintId": "blueprint_ghi012",
      "meta": {},
      "createdAt": "2025-11-20T10:00:00Z",
      "updatedAt": "2025-11-22T15:30:00Z"
    }
  ]
}

json

Key Response Fields:

  • instruction: The ability's execution template defining how it operates (e.g., API calls, data processing)
  • secretId: Reference to authentication credentials if the ability requires external service access
  • fileId: Associated file providing additional context or code for ability execution
  • botId: Specific bot this ability is dedicated to (if any), or null for shared abilities
  • blueprintId: Blueprint organization this ability belongs to, enabling grouped management

Common Use Cases:

  • Capability Auditing: Review all abilities available in a skillset to understand bot capabilities
  • Dependency Management: Identify which secrets and files are required for skillset operation
  • Bot Configuration: Verify that all necessary abilities are present before deploying a bot
  • Troubleshooting: Examine ability instructions when debugging skill execution issues
  • Skillset Cloning: Export ability configurations when creating duplicate or template skillsets

Pagination: The list endpoint supports cursor-based pagination for efficient handling of skillsets with many abilities. Use the cursor, order, and take parameters to navigate through large ability collections. The default order is descending by creation date, showing the most recently added abilities first.

Skillset Abilities represent the individual actions and capabilities that define what bots can accomplish beyond basic conversation. Each ability encapsulates a specific function, operation, or integration that can be invoked during conversations to perform tasks like fetching data from APIs, executing business logic, interacting with external services, or processing information in specialized ways.

Abilities are organized into Skillsets, which are collections of related capabilities that can be attached to bots. This modular approach enables building sophisticated bot behaviors by combining pre-defined abilities, custom integrations, and specialized functions into coherent capability sets.

Exporting Skillset Abilities

Export all abilities within a skillset to retrieve their complete configurations, instructions, and metadata. This endpoint is particularly valuable for backing up skillset configurations, migrating abilities between environments, analyzing capability implementations, or building automated deployment pipelines that version control bot functionality.

The export format provides abilities in a machine-readable structure that can be stored, version controlled, analyzed, or re-imported into other skillsets. This enables treating bot capabilities as portable, reusable components that can be shared across projects and environments.

GET /api/v1/skillset/{skillsetId}/ability/export

http

Export Response Structure

The export endpoint returns a paginated list of abilities with complete configuration details including ability instructions, linked resources, metadata, and creation timestamps. Each ability in the export includes:

Core Identification: Ability ID, name, and description that identify the capability and explain its purpose. Names should be descriptive and follow consistent naming conventions to maintain clarity in large skillsets.

Instruction Block: The complete instruction specification defining how the ability executes. Instructions can reference files, bots, secrets, or contain inline logic using template languages or action definitions. This is the core functional definition of what the ability does.

Resource References: IDs linking to external resources the ability depends on, including file IDs for stored code or configuration, bot IDs for delegated processing, and secret IDs for authentication credentials. These references ensure abilities can access required resources at runtime.

Blueprint Association: If the skillset belongs to a blueprint, abilities inherit that blueprint context, enabling coordinated deployments of related resources and capabilities as cohesive packages.

Metadata: YAML-formatted metadata containing additional configuration, version information, deployment tags, or custom attributes. The metadata field provides extensibility for storing ability-specific settings without modifying the core schema.

Common Export Use Cases

Configuration Backup and Version Control:

// Export all abilities for backup
const response = await fetch('/api/v1/skillset/sks_123/ability/export');
const { items: abilities } = await response.json();

// Store in version control
const backup = {
  timestamp: Date.now(),
  skillsetId: 'sks_123',
  abilities: abilities.map(a => ({
    name: a.name,
    description: a.description,
    instruction: a.instruction,
    metadata: a.meta.toString() // YAML format
  }))
};

await fs.writeFile(
  `skillset-backup-${Date.now()}.json`,
  JSON.stringify(backup, null, 2)
);

javascript

Environment Migration:

// Export from production
const prodExport = await fetch(
  'https://api.chatbotkit.com/api/v1/skillset/sks_prod/ability/export',
  { headers: { Authorization: `Bearer ${prodToken}` } }
);
const { items: prodAbilities } = await prodExport.json();

// Import to staging, creating new abilities
for (const ability of prodAbilities) {
  await fetch('/api/v1/skillset/sks_staging/ability/create', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${stagingToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: ability.name,
      description: ability.description,
      instruction: ability.instruction
    })
  });
}

javascript

Pagination and Large Skillsets

The export endpoint supports pagination for skillsets with many abilities. Use the cursor, order, and take query parameters to control pagination:

Cursor-Based Pagination: The cursor parameter enables efficient pagination through large ability collections. After fetching a page, use the last item's ID as the cursor for the next request to continue where you left off.

Order Control: Set order to asc for chronological ordering (oldest first) or desc for reverse chronological (newest first). This affects both initial results and pagination continuity.

Page Size: The take parameter controls how many abilities are returned per request. Balance between fewer requests (larger pages) and faster individual responses (smaller pages) based on your use case.

Metadata Format and Usage

The meta field in exported abilities contains YAML-formatted metadata that can be converted to string format for storage or parsing. This metadata often includes:

  • Version Information: Track ability versions for change management
  • Environment Tags: Mark abilities for specific deployment environments
  • Dependencies: Document required resources or external service versions
  • Configuration Options: Store ability-specific settings and parameters
  • Documentation: Include usage notes, examples, or API references

Access metadata in string form using meta.toString(), which returns properly formatted YAML suitable for storage or editing.

Export Analysis and Validation

Exported abilities can be analyzed programmatically to ensure consistency, identify dependencies, or validate configurations before deployment:

// Analyze exported abilities
const { items: abilities } = await response.json();

// Find abilities with secret dependencies
const secretDependencies = abilities
  .filter(a => a.secretId)
  .map(a => ({ name: a.name, secretId: a.secretId }));

// Identify file-based abilities
const fileBased = abilities
  .filter(a => a.fileId)
  .map(a => ({ name: a.name, fileId: a.fileId }));

// Validate naming conventions
const invalidNames = abilities.filter(a =>
  !a.name.match(/^[a-z][a-z0-9-]*[a-z0-9]$/)
);

javascript

Best Practices for Export Operations

Regular Backups: Export skillset abilities regularly to maintain backups of your bot capabilities. This provides recovery options if abilities are accidentally modified or deleted, and enables rollback to previous versions.

Documentation Generation: Use exports to automatically generate capability documentation showing what abilities are available, their purposes, and dependencies. This aids team collaboration and onboarding.

Dependency Mapping: Analyze exports to understand resource dependencies before making changes. Identifying which abilities depend on specific files or secrets prevents breaking changes.

Environment Consistency: Compare exports across environments to ensure staging and production maintain consistent capability sets. Differences might indicate incomplete deployments or configuration drift.

Important Note: Exported abilities contain complete configuration including resource references, but do not include the actual files, secrets, or linked resources themselves. When migrating abilities, ensure dependent resources exist in the destination environment or update references accordingly.

Fetching Individual Ability Details

To retrieve comprehensive information about a specific ability within a skillset, including its instruction template, associated resources, and configuration details, use the fetch endpoint. This operation provides a complete view of how an ability is configured to operate, which external services it integrates with, and what resources it depends on. Understanding ability details is essential for troubleshooting execution issues, auditing capability configurations, and preparing to update or replicate ability definitions.

The fetch operation returns the full ability configuration including the instruction template that defines its behavior, references to authentication secrets for external API access, associated files that provide context or code, and linked bots if the ability is dedicated to a specific bot rather than shared across the skillset.

GET /api/v1/skillset/{skillsetId}/ability/{abilityId}/fetch
Content-Type: application/json

http

The response includes all ability configuration details:

{
  "id": "ability_abc123",
  "name": "Weather API Query",
  "description": "Fetches current weather data from OpenWeatherMap API",
  "instruction": "```fetch\\nmethod: GET\\nurl: https://api.openweathermap.org/data/2.5/weather\\nheaders:\\n  Authorization: ${SECRET_DEFAULT}\\nquery:\\n  q: ((location! ys|the location to query))\\n  units: metric\\n```",
  "secretId": "secret_xyz789",
  "fileId": null,
  "botId": null,
  "skillsetId": "skillset_def456",
  "blueprintId": "blueprint_ghi012",
  "meta": {},
  "createdAt": "2025-11-20T10:00:00Z",
  "updatedAt": "2025-11-22T15:30:00Z"
}

json

Key Response Fields Explained:

instruction: The ability's execution template that defines its behavior. This typically contains action definitions such as API calls, data transformations, or custom logic. The instruction uses a specialized format with parameter placeholders and may include multiple action types like fetch, pack, bot, or dataset.

secretId: Reference to stored authentication credentials used by the ability when accessing external services. When this field is set, the ability can securely authenticate with third-party APIs without exposing credentials in the instruction.

fileId: Associated file that provides additional context, code, or configuration for the ability. This could be a script, data file, or documentation that supports ability execution.

botId: If set, indicates that this ability is dedicated to a specific bot rather than being shared across all bots using the skillset. This is useful for bot-specific capabilities that shouldn't be available to other bots.

blueprintId: Blueprint organization this ability belongs to, enabling grouped management and lifecycle control of related abilities.

Common Use Cases:

  • Debugging Execution Issues: Examine the instruction template when an ability fails to execute correctly
  • Configuration Auditing: Review ability settings to ensure they match expected behavior
  • Capability Replication: Copy ability configurations when creating similar capabilities
  • Dependency Verification: Confirm that required secrets and files are properly associated
  • Integration Documentation: Understand how abilities integrate with external services

Instruction Format: The instruction field contains structured templates that define how abilities operate. These templates use special syntax for parameters, authentication, and action definitions. Understanding this format is crucial for creating or modifying abilities to match your specific integration requirements.

Updating Ability Configuration

To modify an existing ability's configuration, including updating its instruction template, changing associated resources, or adjusting metadata, use the update endpoint. This operation enables you to refine ability behavior as requirements evolve, correct configuration errors, update authentication credentials, or adapt abilities to changes in external APIs or business logic. Updating abilities is a common maintenance task as integrations mature and requirements become clearer.

Ability updates take effect immediately for all future executions, but do not affect abilities currently being executed by bots or agents. This ensures that in-progress operations complete successfully with their original configuration before new settings are applied. You can update any combination of configuration parameters in a single request, and unchanged fields will retain their existing values.

POST /api/v1/skillset/{skillsetId}/ability/{abilityId}/update
Content-Type: application/json

{
  "name": "Enhanced Weather Query",
  "description": "Fetches weather data with extended forecast",
  "instruction": "```fetch\\nmethod: GET\\nurl: https://api.openweathermap.org/data/2.5/forecast\\nheaders:\\n  Authorization: ${SECRET_DEFAULT}\\nquery:\\n  q: ((location! ys|the location))\\n  cnt: 5\\n```",
  "secretId": "secret_new123"
}

http

Updatable Configuration Fields:

  • name: Update the ability's display name for better organization and clarity
  • description: Modify the description to reflect current functionality or purpose
  • blueprintId: Reassign the ability to a different blueprint for organizational purposes
  • secretId: Change the authentication credentials used for external API access
  • fileId: Update or add an associated file that provides context or code
  • botId: Dedicate the ability to a specific bot or make it shared (null for shared)
  • instruction: Modify the execution template that defines ability behavior
  • meta: Update custom metadata for tracking or organizational purposes

Common Update Scenarios:

Updating API Integration Details:

{
  "instruction": "```fetch\\nmethod: GET\\nurl: https://api.newprovider.com/v2/data\\n```"
}

json

Essential when external APIs change endpoints or introduce new versions.

Changing Authentication Credentials:

{
  "secretId": "secret_rotated456"
}

json

Required when API keys or tokens are rotated for security.

Refining Instruction Parameters:

{
  "instruction": "```fetch\\nmethod: POST\\nurl: https://api.example.com/data\\nbody:\\n  query: ((query! ys|search query))\\n  limit: 10\\n  fields: [\"id\", \"name\", \"description\"]\\n```"
}

json

Useful for adding new parameters or adjusting defaults as usage patterns emerge.

Making Ability Bot-Specific:

{
  "botId": "bot_xyz789"
}

json

Restricts the ability to a single bot when it shouldn't be shared across the skillset.

Important Considerations:

  • Instruction changes take effect immediately for new ability executions
  • Changing secretId requires the new secret to exist and be accessible to your account
  • Setting botId to a specific bot restricts the ability to that bot only
  • Setting botId to null makes the ability available to all bots using the skillset
  • Instruction syntax must be valid according to the ability template format
  • Complex instructions with multiple actions should be thoroughly tested after updates

Validation and Testing: After updating ability instructions, especially when modifying API endpoints, parameters, or authentication methods, test the ability execution to ensure it works as expected. Invalid instruction syntax or incorrect secret references can cause ability execution failures, so verify configurations before deploying to production bots.

Instruction Format: Abilities use a specialized instruction format with action blocks (like fetch, pack, bot) and parameter placeholders. When updating instructions, ensure you maintain proper syntax including correct indentation, parameter definitions, and action type specifications. Refer to ability documentation for detailed instruction format guidelines.

Rollback Strategy: If an ability update causes unexpected behavior, you can quickly rollback by updating the ability again with its previous instruction and configuration. Consider keeping records of working configurations before making significant changes to enable fast recovery if needed.

Deleting an Ability from a Skillset

To permanently remove an ability from a skillset, use the delete endpoint. This operation irreversibly removes the ability configuration and prevents any bots using the skillset from accessing this capability in future operations. Deleting abilities is typically done when capabilities are no longer needed, when consolidating duplicate functionality, or when removing deprecated or malfunctioning integrations from your skillset portfolio.

Deleting an ability does not immediately affect bots currently executing tasks that use this ability. In-progress operations will complete with the ability still available. However, any new bot conversations, tasks, or operations started after the deletion will not have access to the removed ability. This ensures graceful degradation without interrupting active bot operations.

POST /api/v1/skillset/{skillsetId}/ability/{abilityId}/delete
Content-Type: application/json

{}

http

The response confirms successful deletion:

{
  "id": "ability_abc123"
}

json

What Gets Deleted:

  • The ability configuration including all instruction templates
  • References to associated secrets, files, and bots
  • Metadata and configuration history for the ability
  • The ability's presence in the skillset's capability list

What Is NOT Deleted:

  • The associated secret (if configured) remains available for other abilities
  • The associated file (if configured) remains available for other uses
  • Historical audit logs showing past ability executions
  • The skillset itself continues to function with remaining abilities
  • Bots using the skillset continue to operate (with reduced capabilities)

Important Considerations:

Before Deleting:

  • Verify that no bots depend on this ability for critical functionality
  • Check if other abilities in the skillset reference or depend on this ability
  • Export the ability configuration (instruction, secrets, parameters) if you might need to recreate it
  • Review recent execution logs to confirm the ability is not actively being used
  • Consider whether the ability should be disabled rather than deleted if you might need it later

After Deletion:

  • Bots will no longer be able to execute this ability in new operations
  • Any bot instructions or workflows that reference the deleted ability will fail when attempted
  • The ability cannot be recovered; you must recreate it from scratch if needed
  • Consider updating bot prompts or instructions that may have referenced this capability
  • Monitor bot performance to ensure the missing ability doesn't impact expected functionality

Impact on Bot Behavior: When an ability is deleted, bots using the skillset lose that specific capability. If the ability was essential for certain bot functions, those functions will no longer work. Bots may need updated instructions or prompts to handle the absence of the deleted ability gracefully, or you may need to add an alternative ability to maintain functionality.

Cascading Effects: If other abilities in the skillset use pack actions that include the deleted ability, those pack executions will fail when they attempt to invoke the missing capability. Review any pack abilities that might reference the deleted ability and update them accordingly.

Alternative to Deletion: If you want to temporarily disable an ability without losing its configuration, consider:

  • Making the ability bot-specific and assigning it to an unused bot (effectively hiding it)
  • Modifying the instruction to return an error message instead of executing
  • Documenting the ability as deprecated in its description while keeping it available

These approaches preserve the ability configuration for future use while preventing it from being actively executed by production bots. When ready to fully remove the capability, you can then delete it with confidence that its configuration has been properly documented and backed up.

Go to cbk.ai