Skills

A skill is a folder of instructions and files that an agent loads when a task needs it. Its SKILL.md file names the skill and says when to use it. With this API you can upload a skill, list the skills your key can read and download any version.

A skill you create belongs to the key’s owner and is private to them until they share it in the Context app. Creating, versioning and deleting skills needs a personal key with skills:write, which the key’s owner must grant. A built-in skill (source.type is anthropic) is read-only.

Endpoints

Endpoint	What it does
`POST /v1/skills`	Creates a skill from uploaded files. The skill belongs to the owner of the API key.
`GET /v1/skills`	Lists the skills the key’s owner can read.
`GET /v1/skills/{skill_id}`	Returns a skill by its ID.
`DELETE /v1/skills/{skill_id}`	Deletes a skill, its versions and their files.
`POST /v1/skills/{skill_id}/versions`	Saves a new version of a skill from its complete set of files.
`GET /v1/skills/{skill_id}/versions`	Lists a skill’s versions, newest first.
`GET /v1/skills/{skill_id}/versions/{version}`	Returns one version of a skill, or its newest version if you pass `latest` as `version`.
`GET /v1/skills/{skill_id}/versions/{version}/content`	Returns a version’s files as one zip archive.

What an upload contains

Send the skill’s files as multipart/form-data. Either send each file as a files[] part whose filename is its path in the skill, or send one zip archive of the files.

SKILL.md sits at the root of the upload, or at the root of its one top-level folder. That folder’s name is dropped from every path.
SKILL.md is UTF-8 text with YAML front matter. name can be at most 64 characters of lowercase letters, digits and hyphens. If SKILL.md has no name, the skill takes the top-level folder’s name, and an upload with neither returns 400. description is required and can be at most 1,024 characters, with no XML tags.
The files total at most 30 MiB (31,457,280 bytes) uncompressed. A single file has no limit of its own. The request itself can be up to 32 MiB.
Paths are relative. A path returns 400 if it starts with /, contains a backslash or has an empty, . or .. segment. Sending the same path twice also returns 400. A zip’s __MACOSX/ and .DS_Store entries are skipped.

A key can have at most 2 uploads in progress at once.

A skill’s name is its SKILL.md name, and every version of a skill keeps that name. You can’t own two skills with the same name. Creating a skill whose name you already use returns 409 with the existing skill’s ID, so you can upload a new version of it instead.

A skill keeps its latest 500 versions, not counting versions given a name in the Context app. Saving more deletes the oldest unnamed versions.

The skill object

Field	Type	Description
`id`	`string`	The skill’s ID. A built-in skill’s ID is its slug, such as `pptx`.
`type`	`string`	Always `skill`.
`display_name`	`string`	The skill’s name, the same as the `name` in its `SKILL.md`.
`source`	`object`	Who made the skill. `source.type` is `custom` for a skill a user uploaded, or `anthropic` for one of your deployment’s built-in skills.
`latest_version_id`	`string`	The ID of the skill’s newest version. An agent always runs a skill’s newest version.
`created_at`	`string`	When the skill was created, as an RFC 3339 timestamp.
`updated_at`	`string`	When the skill last changed, as an RFC 3339 timestamp.

A skill version describes one saved state of the skill’s files:

Field	Type	Description
`id`	`string`	The version’s ID.
`type`	`string`	Always `skill_version`.
`skill_id`	`string`	The ID of the skill the version belongs to.
`name`	`string`	The `name` in `SKILL.md`. It is the same for every version of a skill.
`description`	`string`	The `description` in `SKILL.md` at this version.
`created_at`	`string`	When the version was saved, as an RFC 3339 timestamp.

{
  "id": "8b3f6c1e-2a4d-4f7b-9c1e-5d6a7b8c9d0e",
  "type": "skill",
  "created_at": "2026-10-27T15:02:11.204Z",
  "display_name": "pr-summary",
  "latest_version_id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
  "source": {
    "type": "custom"
  },
  "updated_at": "2026-10-27T15:02:11.204Z"
}

Differences from Anthropic’s API

This API follows Anthropic’s Managed Agents API, with these differences:

A skill is personal to the key’s owner. Requests carry no workspace, and a request that sends the anthropic-workspace-id header returns 400.
display_name must equal the name in SKILL.md, or be left out. A different value returns 400.
Deleting a skill version returns 400. Upload a new version, or delete the whole skill.
The built-in skills are this deployment’s own, listed by slug (pptx, xlsx, docx and others). The list has no pdf skill.
A list response holds at most 200 skills or 100 versions per page. Anthropic’s API allows up to 1,000.
Uploads are limited to 32 MiB per request and 2 in progress per key.

For every difference in one place, see Coming from Anthropic’s API.