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.
  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. 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. Next, preview prompt disclosure to check 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.

​
Preview prompt disclosure

Every turn lists the session’s skills within a character budget. 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. The preview resolves groups exactly as a session start does and reports what fits.
  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. Cards past the line marked “Past this line the model sees only skill names.” are flagged Name only.
An entry with description_included: false can still be activated, but the model sees only its name. 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. warnings also names entries that could not be resolved, such as a deleted skill or group. context_window_tokens is optional; omit it to use a conservative default of 8,000 characters, which is also what the console’s meter uses.

​
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 drop a new zip on Upload a bundle.
  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 version they started with. 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. 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. 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, expand the group in the catalog in Skills.
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. 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 for the whole session.
  2. Every turn lists each skill’s name and, while the budget allows, its description. See Preview prompt disclosure.
  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.
  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. Run Preview prompt disclosure, 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. Start a new session. 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.