The Skills API Is Not Where Your Skills Live

§1Two claims worth checking

A post went round this week with a clean, quotable shape: the Skills API and Files API went GA on the nineteenth and twentieth of August, and here is what you should do about it, move your skill sprawl onto versioned skills. We build on this platform every day and run a fleet of agents on local skill files, so before repeating either half we checked both against Anthropic's own API reference. Neither survived intact. The API is real, the idea behind it is real, and the label on both is wrong in a way that matters if you were about to act on it.

§2It is real, and it is beta

Start with what holds up. The Skills API exists and it is a proper piece of kit. You get POST /v1/skills to create one, GET /v1/skills to list, the usual get and delete, and versions underneath at /v1/skills/{id}/versions. Server-side versioning, a real store you publish to. That part of the excitement is earned.

What is not earned is "GA". Those endpoints sit behind a beta header, skills-2025-10-02. Beta is not an insult, it is a status, and it is the one the source of truth reports. The difference between beta and GA is the difference between "you can use this" and "you can depend on this": in beta the shape can still move, so you do not pour load-bearing infrastructure on top of it and assume the ground holds. A launch post flattens that distinction into a badge. The header is the fact. Read the header.

§3The part that actually matters: it is a different runtime

Here is the distinction the take skips, and it is the whole reason to write this down. There are two things called "skills" and they do not live in the same place.

• Your Claude Code skills are files on disk. A folder, a SKILL.md, loaded locally by the agent straight off the filesystem. That is where our fleet's skills live: the handoff routine, the triage routine, the scoping routine, all of them, sat in directories on our own box.
• The Skills API is a platform artefact store. You publish a skill to it, and API-driven agents (Managed Agents, and agents built on the Messages API) reference it by an ID and a version. At runtime the platform downloads it into that agent's working directory before its tools run. Twenty per agent, maximum.

Same word, two runtimes. One loads from your disk. The other is fetched from Anthropic's store by a different kind of agent entirely. So "migrate your skill sprawl onto the Skills API" is not moving a file from one folder to a neater folder. It is publishing a copy of a local skill so a separate execution path can load a versioned copy of it. Your Claude Code setup does not change. Nothing is relocated. The two systems barely touch.

§4So what is the API actually for

Once you see it as a store for API agents, the real use is obvious, and it is not "tidy up the laptop". If you run agents through the API, or through Managed Agents, the Skills API hands them versioned, centrally managed capabilities instead of whatever you happened to bundle at deploy time. Roll a skill forward once, every agent that references latest picks it up. For that architecture it is genuinely useful.

For a fleet of local Claude Code agents it is orthogonal. The only bridge between the two worlds is one you would build on purpose: choosing to publish select fleet skills to the platform so API-side workloads can load them too. That is a real option, and it is a strategic call with a standing cost, two copies of a skill kept in sync, not a free migration you were overdue. Worth doing if we grow API-driven workloads. Not worth pretending it is housekeeping.

§5What to take

Two things, and the second is the useful one. First, when a launch says a feature "went GA", check the header before you believe the badge. A beta header on the endpoint is the source of truth, and it outranks the announcement every time. Second, and this one long outlives this particular API: when two features share a name, confirm they share a runtime before you plan a migration. "Skills" on your disk and "Skills" in the API are one word for two different homes, and the wiring you already have does not move between them. If you want your capability in both places, that is a publish step you opt into, with a cost, not a cleanup you forgot to do.

We built a small tool to pin the boundary down rather than argue about it, a packager that takes a real local skill and produces the exact upload shape the Skills API wants. It runs offline and it works. We deliberately did not wire the live publish to a guessed request body, because the precise upload fields are not in the reference we trust, and posting a guess dressed as a working call is how wrong documentation gets born. That gate is the point. The honest version of "we tried it" includes the sentence "and here is where we stopped".