Skip to main content
A skill is a named block of instructions an agent reads when it needs it. The agent’s prompt carries one line per skill — its name and when to load it — and the agent fetches the full text with a tool call the first time a conversation calls for it. The text then stays in the conversation. Use a skill for guidance that is long, that only some conversations need, or that several agents share: a refund policy, a reporting format, a procedure for a rare case, the house rules for a particular customer. Keep in the prompt what every turn needs: who the agent is, its tone, the two or three rules that always apply.

​
A skill has three parts

The description does the real work: an agent that never loads a skill was not told when to. Say what the skill covers and the moment to reach for it. Write the instructions themselves as positive, imperative rules — what to do, in what order — rather than examples of mistakes to avoid; smaller models copy whatever they read.

​
Creating and publishing

A skill is versioned, but not quite like an agent or a prompt block: there is no separate draft. Every save that changes the text creates a new version, and the newest version is the working copy. Agents get the active version, the one publish points them at:
  • PATCH /v1/skills/{id} saves name, description or instructions. A change becomes a new version; agents keep getting the active one.
  • POST /v1/skills/{id}/publish makes the latest version active. Every agent referencing the skill gets it on its next turn — no agent republish.
  • POST /v1/skills/{id}/activate with a version_id points agents at an earlier version: that is how you roll back.
  • GET /v1/skills/{id} returns the record with latest (the working copy), active (what agents get) and dirty, which is true when the two differ.
A skill that has never been published is skipped by the agents that reference it, and the skip is reported in the agent’s rebuild summary.

​
Attaching skills to an agent

On the agent draft, skills lists the skills by id:
The reference is by id, not pinned to a version. That is deliberate: a skill is reference material the model asks for, and when you publish a correction every agent should see it. (Prompt blocks pin a version at publish time because they are part of the authored prompt; skills are not.) Every id must be one of your organization’s skills, or the save is refused. Two skills on one agent may not share a name. GET /v1/skills/{id}/references lists the agents using a skill, and DELETE /v1/skills/{id} is refused with a 409 while an agent draft or active version still references it (?force=true overrides; those agents then skip the skill until the reference is removed).

​
What the agent sees

The agent’s prompt gains one block:
and three tools: skill (load one by name), skill_search (search across the skills’ text) and skill_read (read a skill’s reference files, none today). The loaded instructions arrive as that tool call’s result and stay in the conversation, so a skill is loaded once per conversation, and again only if it has fallen out of the context window. The chat widget shows the call like any other tool call.

​
Reference