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

# Skills and skill-based routing

> Create skills, give them to agents on the Members page, and use a workflow to assign sessions only to team members who hold every skill the session needs.

Skills describe what an agent can handle, such as Billing or Spanish. Give skills to agents, add the skills a session needs with a workflow, and OpenCX assigns the session only to team members who have all of them.

> [!NOTE]
>
> **Settings → Skills** in your [OpenCX dashboard](https://platform.open.cx/settings/skills). Viewing skills requires the **Skills settings** permission; creating, editing, deleting and assigning skills requires write access to it.

## What skill routing needs

Skills on their own do not change who gets a session. Routing by skill needs all three of these:

1. **Agents hold skills.** You give them skills on the Members page.
2. **The session carries skills.** The **Assign Skills to Ticket** workflow action adds them. Sessions get skills no other way.
3. **The workflow assigns the session with skill routing on.** **Assign Ticket to Support Team** or **Auto Assign to Support Team** with **Skill-based routing** turned on. It is off by default.

The target team also needs support enabled and the **Least busy** assignment strategy. See [Teams](https://docs.open.cx/teams.md#team-editor-settings).

## Create a skill

![Creating the skill Spanish with a description in Settings, Skills](https://mintcdn.com/openchat/hiyaCL2S28Hya6Q7/images/ticketing/skill-create.gif?s=14a7618b15a6958489b050b9d4748187)

Create a skill called Spanish with a description, and it appears at the top of All skills.

**1. Open the form**

Click **New skill**.

**2. Name it**

Enter a **Name** of up to 64 characters, such as **Billing**. Names are unique in your workspace, ignoring capitalization.

**3. Describe when it applies**

Add a **Description**, then click **Create**. Workflows can read every skill's name and description through the `{{routingSkills}}` variable, so an AI step can decide which skills a session needs. Write the description as the situation the skill covers, for example "Refunds, invoices and failed payments".

Renaming a skill is safe: agents and sessions keep it. Deleting a skill removes it from every agent and session that has it.

## Give skills to agents

1. Open [Settings → Members](https://docs.open.cx/ticketing/members.md).
2. Open the member's three-dot menu and choose **Assign skills**.
3. Select every skill the member has, then click **Save**. The list you save replaces the member's previous skills.

The Members table shows each member's skills in the **Skills** column. If your workspace has no skills yet, the dialog offers **Create Skills** instead.

## Add skills to a session

In a workflow, add the **Assign Skills to Ticket** action. Pick skills from the list, or pass skill names from an earlier step, such as an AI step that reads `{{routingSkills}}`.

* Skills are added. Skills already on the session stay.
* Names that match no skill are skipped and returned as **Unresolved Skills**.
* The session timeline shows which skills were added, and the **Session skills** card in the Inbox sidebar lists them. You cannot edit a session's skills from the Inbox.

## Assign to an agent with the right skills

After **Assign Skills to Ticket**, add **Assign Ticket to Support Team** or **Auto Assign to Support Team** and turn on **Skill-based routing**.

| Situation | Result |
| - | - |
| The session has no skills | It is assigned the usual way, to any eligible team member. |
| Eligible team members hold every skill on the session | The least busy of them gets the session. |
| No eligible team member holds every skill | The session moves to the team unassigned. |
| **Shallow assignment** is on | No agent is picked, so skill routing has no effect. |

An eligible member is online, available in that team, and has free capacity, and the team is within its office hours. See [Human routing](https://docs.open.cx/ticketing/human-routing.md). When nobody qualifies, the assignment note in the session timeline explains it, for example "no available team member had all the required skills".

> [!WARNING]
>
> Skills are checked only at the moment the workflow assigns the session. If it ends up waiting in the team queue, because nobody qualified or other sessions were already waiting, the queue later hands it to the next eligible team member regardless of skills.

## Other places skills are used

* **Team in the loop**: when the AI asks your team for help, it mentions members who have the skills it needs. See [Handoff settings](https://docs.open.cx/handoff/settings.md#team-in-the-loop).
* **API**: manage skills and each user's skills with the [Skills API](https://docs.open.cx/api-reference/skills/list-skills.md).

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| "A skill with this name already exists" | Another skill has the same name, ignoring capitalization. | Use a different name, or edit the existing skill. |
| Sessions go to agents without the skill | **Skill-based routing** is off in the assign step, the session has no skills yet, or the session was assigned later from the team queue. | Turn on **Skill-based routing** and run **Assign Skills to Ticket** before the assign step. |
| **Assign skills** is greyed out on the Members page | Your role can view skills but not change them. | Ask an admin for write access to **Skills settings**. |
| None of the above | | Contact OpenCX support with the session link. |

***

## Related Documentation

> [card] [Human routing](https://docs.open.cx/ticketing/human-routing.md)
>
> Availability and capacity per agent

> [card] [Teams](https://docs.open.cx/teams.md)
>
> Support teams and assignment strategy

> [card] [Members](https://docs.open.cx/ticketing/members.md)
>
> Invite teammates and assign skills

> [card] [Skills API](https://docs.open.cx/api-reference/skills/list-skills.md)
>
> Manage skills programmatically


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