Skip to main content
A skill is a named bundle of instructions and files. Attaching one does not put its content in the prompt: the agent is offered the skill, and activating it materialises its files into the task workspace and injects its instructions. That is what keeps ten attached skills from costing ten skills’ worth of context. Skills are attached many-to-many, so the same skill serves several agents and is maintained once.

​
Prerequisites

​
Steps

1

Get a skill

Create one from inline content:
Import one from GitHub by passing github_url instead of content, upload a directory with POST /v1/workspaces/{workspace}/skills/upload, or install one from the catalog with POST /v1/workspaces/{workspace}/skills/{skill_id}/install. All four produce the same object; only source_type differs. Every one is stored as a package in object storage; the row holds only metadata.A catalog install is a pin: the skill points at the catalog item’s package and keeps that version until an admin updates it. Passing a catalog skill’s id in skill_ids installs it the same way. A catalog install and a GitHub URL import both ask the workspace’s install policy first; a GitHub URL import counts as the registry registry:github with trust community. See add a skill registry for the rules.
2

Attach it to the agent

skill_ids replaces the attached set, so send the full list you want.
3

Update an installed skill, when the catalog moves on

An installed skill whose catalog item has a new version reads "update_available": true. A workspace admin moves it to that version:
POST /v1/workspaces/{workspace}/skills/update-all updates every installed skill that has an update and was not edited in the workspace. An edited one reads "customized": true; update it alone with ?discard_changes=true, which replaces the edit with the catalog’s version.
4

Compose skills, if useful

A skill can contain skills, through POST /v1/workspaces/{workspace}/skills/{skill_id}/members. Attach the parent and the agent gets the set. POST /v1/workspaces/{workspace}/skills/{skill_id}/flatten resolves a composed skill into its effective content, which is the fastest way to see what an agent will actually receive.

​
Verify

Read back the agent and confirm the skill ids:
Then run a task whose description needs the skill and watch the event feed. Skill activation appears as a tool call, and file materialisation happens before the next model turn.

​
Troubleshooting

Activation is a model decision. If the skill’s description does not make its trigger obvious, the model has nothing to match on — the description is what appears in the catalog, not the content.
Files land in the task workspace at activation, not at attach time. A task that never activated the skill has no reason to have its files.
An install rule refuses the item’s registry or its trust level; the message names the rule. A GitHub URL import is refused by a rule on registry:github or on registry_trust:community. An admin changes the rule under Policies, or installs from a registry the rules allow.
A workspace install rule written after the install denies the skill’s registry or trust level; the task’s feed shows a skill.withheld event naming the rule. Activating it in a running task returns a tool error naming the rule. Lift or narrow the rule under Policies and the next task offers the skill again.
The skill was edited in this workspace. Pass discard_changes=true to replace the edit with the catalog’s version, or leave it as it is.
Attaching many skills still costs their catalog entries. Consider the dynamic context strategy — see context strategies .

Skills

A skill is a folder of files an agent loads only when a task calls for it

Create and configure an agent

Create an agent, bind it to a model instance, and give it instructions and tools

Add a skill registry

Your own source of skills, and the policy on where installs come from
Last modified on October 20, 2026