> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.bitbybit.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up custom AI skills

> Write a custom AI skill to guide replies, run an AI Custom Event automation, or hand a conversation to a selected human agent.

A **Custom skill** defines what your AI agent should do in a specific situation. It can guide the reply, mention an automation to run, or mention a human agent for handoff. Choose the intended outcome before writing the instructions.

## Prerequisites

* You have a saved AI agent and know how to [add a skill](https://knowledge.bitbybit.studio/ai-studio/how-to-setup-skillset-in-ai-studio.md).
* For automation actions, prepare an active automation that starts with an [AI Custom Event trigger](https://knowledge.bitbybit.studio/bitcrm/how-to-set-up-ai-custom-event-triggers-in-automation.md).
* For handoff, make sure the human agent is available in your workspace.

**1. Add a custom skill**

* Open your agent in **AI Studio > AI agent studio**, then select **Skills**.
* Select **Add skill**, choose **Custom skill**, and confirm the addition.
* Open the new skill to edit its details.

  ![Select skill window with Custom skill selected](https://mintcdn.com/asmaraku/1O91wDqYuDyPLKl-/images/ai-studio/ai-agent-select-custom-skill.png?fit=max\&auto=format\&n=1O91wDqYuDyPLKl-\&q=85\&s=fd1f6de3259fcec5d774d3846a78d680)

**2. Describe the skill**

In **Details**, fill in **Name** and **Description**. Use a name that identifies one task, such as **Wholesale enquiry intake**, and a description that explains when the skill is useful.

For example: "Collects the product, quantity, and event date for a wholesale enquiry before sales handoff."

**3. Write the situation and action**

* In **Instructions**, describe when the skill applies and what the AI agent should do.
* Type **@** and use the picker to select an available automation or human agent when the action requires one.
* Leave mentions out when you only want a behavior rule in the AI agent's replies.

  ![Custom skill instructions with an automation selected from the mention picker](https://mintcdn.com/asmaraku/1O91wDqYuDyPLKl-/images/ai-studio/ai-agent-custom-skill-mention-automation.png?fit=max\&auto=format\&n=1O91wDqYuDyPLKl-\&q=85\&s=c68b17b4f32f76d67d56d48dba59318f)

| Instructions mention | Intended action |
| - | - |
| Nothing | Follow the instruction as a behavior rule in the reply. |
| An automation | Trigger that automation when the described situation applies. |
| A human agent | Hand the conversation to that person. |
| An automation and a human agent | Trigger the automation, then hand the conversation to the person. |

Mentioning an automation does not create its steps. Triggering it before handoff does not confirm that all downstream steps finished.

**4. Save and test the skill**

* Use the back arrow to return to **Skills**, then confirm that the skill is enabled in **Custom**.
* Reopen it and check the instructions and selected references.
* Test a matching request and an unrelated request in the [Playground](https://knowledge.bitbybit.studio/ai-studio/test-your-ai-agent-in-playground.md).
* For actual automation execution, follow the [connected-channel test steps](https://knowledge.bitbybit.studio/bitcrm/how-to-set-up-ai-custom-event-triggers-in-automation.md#step-4-check-the-skill-and-automation). Playground simulates the custom-skill automation call.

## Example: Prepare a wholesale enquiry for sales

A customer asks, "Can I get a quote for 100 gift boxes for our company event?" Use a skill that gathers the details your sales team needs before taking over.

> When a customer asks for a wholesale quote, ask for the product, quantity, and event date. Once they provide those details, run @Wholesale enquiry intake, then hand off to @Wholesale sales. Do not promise that a quote has been created or sent unless the configured workflow confirms it.

The automation and agent names are examples. Use the **@** picker to select your actual active automation and human agent. Configure the intake steps in bitCRM before testing the full workflow.

> **Example: Create a behavior rule without an action**
>
> > When a customer says a purchase is a gift, ask whether they want a gift message. Explain only the gift options listed in our Knowledge Base. Do not promise free wrapping unless our policy includes it.
>
> This changes the reply. It does not create an order, run an automation, or transfer the conversation.

## Troubleshooting

* **The automation is missing from the picker:** check that it is active and starts with **AI Custom Event**.
* **The skill shows Needs attention:** check which mentioned agent or automation is no longer available, then select an existing one or remove that part of the instruction.
* **A test reply says the request was accepted:** inspect the configured result before treating it as completed. For a Playground automation test, check the live execution separately.

## Related articles

* [Configure AI agent skills](https://knowledge.bitbybit.studio/ai-studio/how-to-setup-skillset-in-ai-studio.md)
* [Set up AI custom events](https://knowledge.bitbybit.studio/bitcrm/how-to-set-up-ai-custom-event-triggers-in-automation.md)
* [Set up AI escalation](https://knowledge.bitbybit.studio/ai-studio/how-to-set-up-ai-escalation.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.