Skip to main content
A skill is a reusable procedure stored as SKILL.md, optionally with scripts and reference files. Attach skills to an agent instead of putting every procedure in its system prompt: the agent sees each skill’s short description on every turn and loads the full instructions only when a skill fits the task.
Creating, changing, or deleting skills and skill groups needs the organization developer or admin role. The organization user role can view them. See Organizations and roles. For the API, create a key on API keys and export it as RECURSION_API_KEY.

​
Write SKILL.md

SKILL.md starts with YAML frontmatter on the first line, followed by Markdown instructions. name and description are required. Write the description as a condition for using the skill, because it is what the model routes on.
Any other key has no effect. The whole SKILL.md can be at most 256 KiB, and it must have instructions below the frontmatter.When a session loads a skill, it removes HTML comments and escapes <, >, and & in the name, description, and instructions. The agent reads &lt;, &gt;, and &amp; in their place, so write procedures that don’t depend on those characters or on hidden comments. Instructions longer than 64,000 bytes of UTF-8 after this escaping are cut off, and the agent is told they were cut off. The catalog keeps your text as you wrote it.

​
Create a skill

Creating a skill also creates version 1. Versions are immutable.
  1. In the sidebar, click Skills.
  2. Click Create skill.
  3. Enter the document in SKILL.md, and optionally a Display title and a Group.
  4. Click Create skill.
A 200 response is the catalog entry. Some fields are left out here.
Keep skill_id to attach the skill and latest_skill_version_id to publish the next version. Next, attach it to an agent.
Skill names are unique in your organization. A name that another live skill already uses returns 409 conflict on name.

​
Upload a bundle

To include scripts and reference files, upload a zip archive of the skill’s directory instead. Put SKILL.md at the root of the archive, or inside one wrapper directory. Put runnable helpers in scripts/, supporting documents in references/, and other files in assets/. Files under scripts/ are made executable in the sandbox; all other files are not.
  1. In Skills, click Create skill.
  2. Drop the zip on Upload a bundle, or pick it. Optionally enter a Display title.
  3. Click Review and upload, check the file list, then click Create skill in the Upload bundle dialog.
The document, name, and description come from the SKILL.md inside the archive.
If you use a wrapper directory, its name must match the skill’s name, and every file must be inside it. Symbolic links and other non-regular files are refused.The multipart form also accepts skill_group_id, and metadata as a JSON string.

​
Attach skills to an agent

Skills are part of an agent version, in the skills field. The list is ordered: the API stores and returns it in the order you send it, and the model reads the skills in that order. Each entry is one of these:
  1. Open the agent and stay on the Configuration tab.
  2. In Skills, pick a skill or group in Attach a skill or group. Reorder the cards so the most important skills come first.
  3. Click Save new version.
The console attaches the latest version. To pin a version, use the API.
A 201 response is the agent at its new version. A version is a full replacement, so resend every other setting you want to keep. See Update an agent.
Entry order matters, because descriptions past the disclosure budget are dropped from the end. A group’s skills take the group’s place in the list, in the order they were created, oldest first. You can’t change that order; to order skills one by one, attach each skill instead of the group. Next, check the saved agent’s skills to see that the descriptions fit.
An agent can have at most 100 entries. The API checks every id when you save the version; an unknown skill, version, or group returns 400 invalid_request naming the entry, such as skills[0].skill_id.

​
Reorder skills

To change the order, save a new agent version with the same entries in the new order. A version is a full replacement, so the update rules apply.
  1. Open the agent and stay on the Configuration tab.
  2. In Skills, drag a card to its new place, or open the card’s menu and click Move to top or Move to bottom.
  3. Click Save new version.
A 201 response returns skills in the new order.

​
Check the skills of a saved agent

Every turn lists the session’s skills within a character budget. The budget depends on the agent’s model: a model with a larger context window allows a longer skill list. When the descriptions don’t fit, the ones at the end of the list are dropped and the model sees only those skills’ names, which makes it less likely to pick them. getAgentSkillDisclosure reports the list the agent’s next session gets, in one read.
  1. Open the agent and stay on the Configuration tab.
  2. In Skills, read the cards from the top. That is the order the model reads the skills. Click Show skills on a group’s card to see the skills it adds.
  3. Read the budget meter. Cards past the line marked “Past this line the model sees only skill names.” are flagged Name only.
The meter is a preview of the cards on the page. It doesn’t count the skill for using apps that sessions of an agent with built-in integrations list first, and for a model the model list doesn’t include it measures against the smallest budget and says so. The API read is exact in both cases.
A 200 response is the list. This agent’s latest version is the one saved in Reorder skills, so the group’s skill comes first.
entries is in the order the model reads the skills. The first entry with description_included: false is where the line falls, and every entry after it is name only too. Those skills can still be activated, but the model sees only their names. attachmentIndex is the position, counted from 0, of the entry in the agent’s skills that a skill came from, so it tells you which entry to move. Move important skills earlier, or shorten descriptions, until they fit.
The read answers for the agent’s latest version, the way a session starting now would list its skills:
  • The agent’s own model. The budget comes from the model the agent is saved with, including a model the model list no longer offers. If that model’s context window can’t be read when you ask, the response measures against the smallest budget, 8,000 characters, and says so in warnings.
  • The skill for using apps. Sessions of an agent with built-in integrations list a skill for using apps first. The response lists it first too and counts it in used_chars. Its entry has no attachmentIndex and no skillId.
  • Groups and versions as they are now. Each group expands to the skills it holds now, and each entry without a pinned version resolves to the skill’s latest version.
An agent that doesn’t exist, is deleted, or belongs to another organization returns 404 not_found. An agent whose model can no longer start sessions returns 400 invalid_request on model. Save a new agent version with a model from the model list, then read again.

​
Preview prompt disclosure

To check a list before you save it, send it to the preview. The preview resolves groups exactly as a session start does and reports what fits, in the same shape as the read for a saved agent. It saves nothing.
  1. Open the agent and stay on the Configuration tab.
  2. In Skills, attach the skills or groups you plan to use.
  3. Read the budget meter. It measures against the model selected on the agent. For a model the model list doesn’t include, it measures against the smallest budget and says so. Cards past the line marked “Past this line the model sees only skill names.” are flagged Name only. When the list resolves to a different number of skills than it has cards, as with a group that holds several skills, the meter names the first affected skills instead of drawing the line.
Read the response as you read the one for a saved agent: entries is in the order the model reads the skills, and the first entry with description_included: false is where the line falls. Here attachmentIndex is the position, counted from 0, of the entry in the skills you sent. Move important skills earlier, or shorten descriptions, until they fit.
Here the group holds one skill, release-checklist, so the response lists it after release-notes, with the group’s attachmentIndex, 1. skillId is the catalog skill each entry resolved to. warnings also reports entries that could not be resolved, such as a deleted skill or group. context_window_tokens is optional. Without it, or when the model’s entry has no contextWindow to send, the preview measures against the smallest budget, 8,000 characters.The preview measures only the list and the context window you send. The model list holds the models you can choose for an agent today, so for an agent on a model it no longer lists there is no contextWindow to send. Sessions of an agent with built-in integrations also list a skill for using apps first, which the preview does not count. For a saved agent, getAgentSkillDisclosure is exact in both cases.

​
Publish a new version

Get the skill first, then send its current latest_skill_version_id as base_skill_version_id. The request is a full replacement: a display_title you leave out resets to the frontmatter name, and metadata you leave out is cleared. You cannot change the group here; use Move a skill to a group.
  1. In Skills, open the skill.
  2. Edit SKILL.md or Display title, or drop a new zip on Upload a bundle. A skill with bundled files keeps its instructions locked here; change them by uploading a new zip.
  3. Click Save new version. For a bundle, confirm in the Upload bundle dialog.
The JSON createSkillVersion operation returns the new version with 201; the multipart publishSkillVersionBundle action returns it with 200.
Agents that follow the latest version pick up version 2 in their next session. Sessions already running keep the skill version they have: a session resolves its skills again only when it moves to another agent version. If another writer published first, the API returns 409 revision_conflict and saves nothing. Get the skill again, apply your change, and retry.

​
Find a skill

List the catalog, or get one skill by id. Neither includes the instructions; get a version for those.
  1. In the sidebar, click Skills.
  2. Search by name, description, or id, or expand a group in the catalog.
  3. Click the skill to open its latest version.
The list is newest first and leaves out deleted skills. That is a browse order, unrelated to the order of an agent’s skills. Follow next_page_token to read the whole catalog; it is absent on the last page. A get returns one skill in the same shape as the create response.

​
List and get versions

listSkillVersions returns every version, newest first, without pages and without instructions. getSkillVersion returns one version with its instructions.
  1. In Skills, open the skill.
  2. Use Compare with under Changes to see what changed between versions.
Every version has a bundle, and bundle.entries always includes SKILL.md. A skill created from a document alone has a bundle that holds only SKILL.md. Some fields are left out of this sample.
A version with bundled files lists them in bundle.entries. mode is 493 (octal 0755) for files under scripts/ and 420 (octal 0644) for everything else.
getSkillVersionContent returns the version’s files as a gzipped tarball, exactly as a session receives them: SKILL.md plus any bundled files.

​
Organize skills in groups

A skill group is a folder in the catalog and a way to attach a whole set of skills to an agent in one entry. The model never sees the group. Filing a skill in a group never creates a skill version.

​
Create a group

  1. In the sidebar, click Skills.
  2. Click New group.
  3. Fill in Name, and optionally Display title and Description.
  4. Click Save group.
A 201 response is the group. Keep skill_group_id to file skills under it and to attach it to an agent.
name is required, follows the same rule as a skill name, and must be unique among your organization’s groups; a taken name returns 409 conflict on name. display_title is at most 256 characters and defaults to name. description is for people browsing the catalog, at most 1,024 characters.

​
Move a skill to a group

updateSkill files a skill under a group. Send an empty skill_group_id to take the skill out of its group. The skill’s versions don’t change.
  1. In Skills, open the skill.
  2. In the header, pick a group in Group, or Ungrouped. The change saves at once.
listSkillGroups returns skill_groups newest first, with limit (default 100, at most 500) and page_token. getSkillGroup returns one group. updateSkillGroup changes only the fields you send, so renaming a group is safe: agents attach it by id.In the console, open the group’s menu in the catalog in Skills, click Edit group, change the fields, and click Save group.
listSkillsInGroup returns the group’s skills in the order a group attachment expands them, oldest first. That order decides whose description is dropped first when the disclosure budget runs out. It takes limit and page_token like listSkills, and the response has the same shape as the list in Find a skill. In the console, open an agent that attaches the group and click Show skills on the group’s card to see the same order. The catalog in Skills sorts a group’s skills by name.
In the console, open the group’s menu in the catalog in Skills, click Archive group, then confirm.
A delete returns { "deleted": true }. The group’s skills stay in the catalog. Agents that attach the group keep the entry, and their next session runs without the group’s skills.

​
Delete a skill

A delete is a soft delete. The skill leaves the catalog and stops resolving into new sessions, and its versions can no longer be read through the API. A session that already started keeps the version it loaded until it moves to another agent version. Agents that reference the skill keep the entry, and their next session runs without it. A deleted skill cannot be restored.
  1. In Skills, open the skill.
  2. At the bottom of the page, click Archive skill, then confirm Archive skill.

​
How an agent uses a skill

  1. When a session starts, it resolves the agent’s skills and skill groups and fixes the version of each skill. It does so again only when the session moves to another agent version.
  2. Every turn lists each skill’s name and, while the budget allows, its description. See Check the skills of a saved agent.
  3. When a skill fits, the agent calls activate_skill with the skill’s name. The full instructions and the list of bundled files enter the conversation and stay in effect for the rest of the session. After a move to another agent version, the agent activates a skill whose content changed again to read the new instructions.
  4. Bundled files are placed under /workspace/.managed-agents/skills in the sandbox. The agent reads or runs a file only when the instructions point it there.
activate_skill is offered only when the session has at least one usable skill.

​
What can go wrong

The most common problems:
  • The agent never activates a skill. Its description was dropped by the disclosure budget, or doesn’t say when to use the skill. Check the saved agent’s skills, move the skill earlier, and write the description as a condition.
  • A new skill version doesn’t reach a running session. Sessions fix skill versions when they start, and again only when they move to another agent version. Start a new session, or save a new agent version and move the session to it. Pinned entries never move; update version to change them.
  • 400 invalid_request on document or bundle. The frontmatter, instructions, or archive layout is wrong, or the document or bundle is over a limit. Read the full cause below.
The full error catalog is on Errors.

​
Limits

Skill description, bundle, entry, list page, and search limits are in Limits, with request sizes and rates. These apply too:

​
Next steps

Agents

Publish an agent version with skills and groups attached.

Tools

See what else the agent can call once a skill is active.

Sessions

Start a session and watch the agent activate a skill.

Artifacts

Collect the files a skill tells the agent to produce.