Skills API — the registry a custom skill needs before anything can name it

Why you'd careThe problem it solves

Your skill works perfectly in Claude Code. You move the same task to a Messages API call, copy the folder path into the request, and there is nowhere to put it — every field that takes a skill wants a skill_id, and your folder does not have one. This is the moment the two worlds separate. Local skills are resolved from a filesystem by the process running them; API skills are objects on Anthropic's side, addressed by ID. There is no bridge, no sync, and no path parameter anywhere in the API. The registry is the conversion step, and it is easy to miss because nothing about the local experience hints that it exists: no upload, no login, no ID to notice the absence of.

ConceptWhat it is

The Skills API is a small CRUD surface over two nested resources. A skill is the named object, created in your workspace, that gets an ID of the form skill_abc123. A version is a snapshot under that skill, and it is what a reference actually resolves to — every consumer's version field defaults to latest if you omit it.

What the registry gives you is nameability. Once the object exists, both consuming surfaces can point at it with the same reference shape: {"type": "custom", "skill_id": "skill_abc123", "version": "latest"} — inside container.skills on a Messages API request, or inside an Agent's skills array on Managed Agents. Anthropic's own pre-built skills use the same shape with type of anthropic and a bare name like pptx, and they need no registration because Anthropic already registered them.

The boundary against the local folder is total. Creating a registered skill from a folder's contents produces a separate object. It does not watch the folder, it does not update when you edit, and deleting the folder does not delete it. The two share content at one instant and then drift. Treat the local copy as source and the registered version as a build artefact, and give yourself a way to tell which version of the source a given registered version came from — because the registry will not tell you.

How it worksThe mechanics

Eight endpoints, four on each level:

POST   /v1/skills                                create the skill object
GET    /v1/skills                                list  -- returns next_page, null on the last page
GET    /v1/skills/{skill_id}                     fetch one
DELETE /v1/skills/{skill_id}                     delete  -- there is no archive

POST   /v1/skills/{skill_id}/versions            cut a version
GET    /v1/skills/{skill_id}/versions            list versions
GET    /v1/skills/{skill_id}/versions/{version}  fetch one version
DELETE /v1/skills/{skill_id}/versions/{version}  delete one version

The upload body is documented now: both POST /v1/skills and cutting a version are multipart form-data carrying a files array — a zip archive or the skill's individual files, SKILL.md included — and creating the skill also takes an optional display_name. Creating a skill uploads its first version in the same call; every later version is a complete snapshot, not a delta. Read the Skills API reference before you write that call anyway. A wrong literal here costs you more debugging time than a paragraph of prose does.

Three operational details that are confirmed and that bite:

• Header bookkeeping.The Skills API is out of beta and needs no beta header, whether you call it directly or from under Managed Agents, whose managed-agents-2026-04-01 header is scoped to /v1/agents, /v1/sessions and /v1/environments. skills-2025-10-02 still works, but only as an opt-in that switches a request back to the beta response shapes: display_title, epoch-microsecond version strings, oldest-first version lists, and a delete refused while versions exist. SDK releases before Python 1.2.0 / TypeScript 0.122.0 still send it from client.beta.skills; call client.skills.
• Delete only, no archive.Agents, environments, vaults, and memory stores all have an archive operation that makes them read-only. Skills do not — delete is the only removal, on both levels, and deleting a skill removes every version with it in one call. There is no soft state to fall back to.
• Separate meters.Managed Agents endpoints are rate-limited per organization (300 create and 1,200 read requests per minute), and the Files API has a per-organization limit of its own, both apart from the Messages API limits. The rate-limits page names no bucket for /v1/skills, so measure a bulk registration script against your own account rather than assuming which meter it draws on.

One thing to watch, and it is now stated for skills specifically: custom Skills are “shared workspace-wide: all workspace members can access them”, and API credentials are bound to an organization and a workspace, so resources created under one workspace's token are not listed by another's. If a skill you created "disappears", check which workspace your key belongs to before assuming a delete.

At a glanceSee it

The registry converts a folder into an ID that both API consuming surfaces can reference.

Where it runsSurfaces and availability

Consumption and management really are separate availability questions — but the useful correction is that they are both answerable, and the answers live on different pages. The per-feature availability table only tells you a platform can use skills; the Agent Skills overview is where Anthropic states who can create them, and it names Claude Platform on AWS and Microsoft Foundry explicitly. So the guidance stands with its verdict flipped: if your architecture depends on creating custom skills from a particular platform rather than just consuming pre-built ones, that path exists on both cloud platforms — check the hosting option on Foundry rather than the endpoint list. The genuine dead ends are elsewhere: Bedrock and Vertex have no registry to call, the Agent SDK offers no registration API, and claude.ai's per-user uploads are a different store that will never appear in a /v1/skills listing no matter how many people on the team have added them.

ExampleIn the real world

A team has a compliance-memo skill that has been running locally for a month: a SKILL.md, a template, and a script that pulls the current control list. It works. Now the same output has to come out of a nightly Managed Agents run, unattended.

The engineer creates the skill with POST /v1/skills, uploading the folder's current contents — raw HTTP, and no beta header needed. The response carries skill_abc123, and its latest_version_id names the first version, skver_01AbCd.

They then add {"type": "custom", "skill_id": "skill_abc123", "version": "skver_01AbCd"} to the Agent's skills array — pinning the version deliberately, so that a later edit to the local folder cannot change what the nightly job does without someone cutting a new version and updating the Agent.

Two weeks later the control list changes. They edit the folder, confirm it locally, and nothing happens to the nightly run — correctly, because the registered first version is frozen. They cut a second version with POST /v1/skills/skill_abc123/versions, update the Agent to point at its skver_ ID, and the change takes effect on the next run. The local folder and the registered object were never linked; the version pin is what made that safe instead of confusing.

Not thisWhat it is often confused with

• Not a package registrythere is no public index, no dependency resolution, no search across organizations. Skills are created in your own workspace and are visible only to callers with credentials scoped to it.
• Not a plugin marketplaceplugins are a distribution mechanism for harness-side skills and other assets. The Skills API is the API-side object store. They can carry the same content and are not the same system.
• Not where local skills liveClaude Code never reads this registry, and the registry never reads your filesystem. Registering is a one-way copy at a moment in time.
• Not versioned like an Agentan Agent versions implicitly on every update. A skill version is cut explicitly with its own endpoint, and versions can be deleted individually — except a skill's only version, which returns a 400 until you upload a replacement or delete the skill. Do not assume Agent versioning semantics transfer.
• Not archivableunlike agents, environments, vaults, and memory stores, skills have delete only. There is no read-only end state to park something in.

LimitsWhen not to reach for it

• You are still iterating.Registration adds a publish step to every change. Draft locally where the loop is a file save, and register once the content has stopped moving.
• You only need Anthropic's pre-built skills.pptx, xlsx, docx, and pdf are already registered. Reference them by name with type of anthropic and skip this surface entirely.
• The content is a corpus rather than a procedure.A skill is instructions plus a handful of bundled files. Thousands of documents that need query-time search are a retrieval problem, and the registry is not a document store.
• You want the harness to distribute it to a team.If the consumers are engineers on laptops rather than API calls, project scope in the repo or a plugin is the mechanism — the registry does not put anything on anyone's disk.
• You expect it to be a rollback mechanism for local behaviour.Deleting a registered version changes nothing about what any developer's Claude Code session does. The two never talk.

RelatedGo deeper