Teach assistants how to work with skills

Write down how work gets done as skills, or import skill packs from GitHub, and attach them to assistants, which follow them on every reply.

What a skill is#

A skill is a reusable piece of know-how, such as "steps for handling a complaint" or "the format for a quote". An assistant with a skill attached treats it as a standing instruction on every reply.

How skills differ from the knowledge library:

• Knowledge is material. The assistant retrieves from it by question and uses only the relevant parts.
• Skills are ways of working. Every attached skill goes in whole on every reply, with no retrieval.

Open Skills in the console. Skill library lists the workspace's shared skills and your own; Skill packs imports skills from GitHub.

Who can do what#

Create a skill#

1. Open Skills and scroll to Create a skill.
2. Enter a Name.
3. Optionally fill in Description (optional), saying when the skill applies.
4. Fill in Instructions: the step-by-step how-to the assistant follows when this skill applies.
5. Decide whether to turn on Keep it to myself (see Skills only you use).
6. Select Create.

The skill appears in the Skill library table with its Name and Description.

Skills only you use#

Turn on Keep it to myself when creating a skill and only you will see it; it isn't added to the workspace library. These skills are listed under My skills in the Skill library table, marked Only you.

• Members who aren't owners or admins can only write skills for themselves, so the switch is fixed on for them. Adding a skill to the workspace library takes a workspace owner or admin.
• Your own skills can only be attached to your own private assistants, under Other settings on the private assistant's page.
• A private assistant with one of your personal skills attached can't be shared. Detach the skill, or ask an admin to add it to the workspace library, then share again.
• You can edit, delete and restore your own skills without admin rights.

Import a skill pack from GitHub#

If your team already keeps skills on GitHub, import the whole repository and sync it later.

1. In the Skill packs section of the Skills page, enter the Repository URL, for example https://github.com/your-org/skills.
2. Optionally enter a Branch or tag. Left empty, main is used.
3. Select Import pack.

The page then reports what happened: "Added N, updated N, skipped N, kept locally N, malformed N, support files not imported N."

Repository format

Each folder in the repository that holds a SKILL.md is one skill:

---
name: Returns
description: Use when a customer asks to return an order
---

1. Confirm the order number and purchase date.
2. For orders older than 7 days, explain the return window and give the support email.

• name is required and becomes the skill's name; description is optional.
• The file must start with --- and the block must be closed with another ---.
• Everything after the closing --- is the instructions, and it can't be empty.
• Other files in the same folder as a SKILL.md aren't imported; they're counted under "support files not imported".
• A SKILL.md that doesn't follow this format, or exceeds the length limits, isn't imported and is counted as malformed.

Import and sync rules

• Only public repositories on github.com are supported.
• If the library already has a skill with the same name (ignoring case), that skill is skipped, not overwritten.
• Imported skills go into the workspace library and count toward its 50.
• Each pack is listed with its URL, branch or tag, and the commit it was last synced to. Sync fetches the repository's latest content: - A skill that changed upstream and that you haven't edited is updated; the old wording stays in its history. - A skill you edited in Agent Lab keeps your version and is counted as "kept locally". - A skill deleted upstream stays in the library; it isn't removed automatically.
• The repository itself is limited to 5,000 files, 32 MB in total and 4 MB per file. A repository over any of these isn't imported at all.

Attach to an assistant#

1. Open the assistant's page and find the Skills section.
2. Pick a skill under Choose a skill and select Attach.
3. To detach it, select the × on the skill's chip.

One assistant can have up to 20 skills. If the library has no skills yet, this section points you to the Skills page first. For the rest of an assistant's settings, see Assistants.

How assistants use skills#

On every reply, the assistant appends its attached skills, in the order they were attached, after its own instructions and before the knowledge it retrieves. Skills don't change with who is asking.

All attached skills together share a length limit of about 6,000 bytes (roughly 6,000 English characters, or about 2,000 Chinese characters). When adding the next skill would pass that limit, that skill and every one after it are left out, and the console doesn't warn you. If an assistant has many skills or long ones, attach the most important first and keep each one short.

Edit and history#

• Edit: select Edit on the skill's row, make the change and select Save changes. The editor shows the current Version N. Every assistant the skill is attached to uses the new wording right away.
• Editing at the same time: if someone else changed the skill while you were editing, your save is refused, the skill is reloaded, and you're asked to read what it says now before saving again.
• History: select History to see What "…" used to say, with each version's time and author. The version in force is marked In use now. To go back to one, select Use this wording again.

Delete a skill#

Select Delete on the skill's row. The dialog lists the assistants that use it and warns that their replies will change. Select Delete anyway to confirm, or Keep it to back out.

Deleting detaches the skill from every assistant. Attaching, detaching and deleting skills are recorded in the audit log under Team & access.

Limits#

Name, description and instructions are counted in characters, so a Chinese character counts as one, the same as an English letter. The combined limit for attached skills on a reply is different: it's counted in bytes, and a Chinese character takes three, so Chinese skills reach it at about 2,000 characters. If a name, description or instructions run over, creating shows "Couldn't create the skill. Check the name and instructions." and saving an edit shows "The skill could not be saved. Please try again."

Next#