Skip to main content
POST
Create a skill and immutable version

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Body

Request body for creating or updating a skill. The document is the source of truth: the skill's name and description come from its frontmatter. Publishing a new version of an existing skill goes through createSkillVersion, which mints one rather than editing the last.

document
string
required

The complete SKILL.md: YAML frontmatter delimited by --- on the very first line, then Markdown instructions. name and description are required in the frontmatter and are read from it.

display_title
string

Human-readable title for listings. Defaults to the frontmatter name.

manifest
string[]

Relative paths of files bundled with the skill, listed to the model when it activates the skill. Paths must stay inside the skill directory.

metadata
object

Caller-owned key/value data stored with the skill and returned unchanged.

skill_group_id
null | string

Catalog group to file this skill under. Send an empty string to remove it from its group; omit to leave the group unchanged. Grouping is for browsing and bulk attachment only and is never disclosed to the model.

Response

A reusable procedure an agent loads when it judges the procedure relevant. Its name and description are disclosed in every turn; the instructions enter the conversation only when the agent activates it. Updating a skill mints a new immutable SkillVersion.

A reusable procedure an agent loads when it judges the procedure relevant. Its name and description are disclosed in every turn; the instructions enter the conversation only when the agent activates it. Updating a skill mints a new immutable SkillVersion.

created_at
string<date-time>
required

Server-assigned RFC 3339 timestamp of when the skill was created.

description
string
required

When to use this skill. Disclosed to the model in every turn, so it is the whole routing signal: write it as the condition under which the skill applies.

name
string
required

The skill's addressable name, lowercase with single hyphens, e.g. cut-release. This is what an agent passes to the activation tool.

organization_id
string
required

Organization that owns the skill. Server-assigned from the caller's credentials; a value sent in a request body is ignored.

skill_id
string
required

Server-assigned id of the skill, used in the skill and skill-version routes.

source
string
required

Where the skill came from: platform, organization, or repository. Decides which skill wins a name collision, most specific first.

updated_at
string<date-time>
required

Server-assigned RFC 3339 timestamp of the most recent update to the skill.

display_title
string

Human-readable title shown wherever skills are listed. Defaults to the name.

latest_instruction_chars
integer<int64>

Length in characters of the newest version's instructions, the body disclosed to the model when it activates the skill. Zero for a skill with no version yet. Instructions are truncated at 64000 characters when a session assembles them.

latest_skill_version_id
string

Server-maintained id of the newest version of this skill; agents that attach it without pinning a version use this one.

latest_version_number
integer<int64>

How many versions this skill has, which is also the number of the newest one, since versions are numbered from 1 in creation order. Zero for a skill with no version yet.

metadata
object

Caller-owned key/value data stored with the skill and returned unchanged.

skill_group_id
string

Catalog group this skill is filed under, if any. Grouping is for browsing and for attaching a set of skills to an agent in one entry; it is never disclosed to the model and does not scope the skill's name.