Claude Skills API Hits GA: What Changed and How to Use It

The Claude Skills API is generally available as of August 20, 2026. You can now create, version, and manage custom skills through https://api.anthropic.com/v1/skills with standard headers, no beta flag required, and run them inside Claude’s code sandbox with nothing to host yourself. Anthropic shipped the GA in one wave with computer use, the new browser tool, and the Files API, framed in the announcement as the production stack for building agents on the Claude Platform.

If skills as a concept are new to you, our guide to Claude Skills covers the idea from the ground up. This article is about the API layer: the endpoints, the versioning model, the request shape that loads skills into a Messages call, and the sharp edges (workspace scoping, snapshot versioning) that GA didn’t sand off. Since it’s all plain HTTP, every call here can be built and regression-tested in Apidog as you follow along.

A 30-second refresher: what a skill is

A skill is a folder. At its top level sits a SKILL.md file with YAML frontmatter carrying a name and a description; around it go any scripts, templates, and reference files the task needs. When a request includes the skill, Claude loads the instructions only when the task calls for them, and executes any bundled scripts in its sandboxed code environment.

The frontmatter has real validation rules:

• name: max 64 characters, lowercase letters, numbers, and hyphens only. No XML tags, and the reserved words “anthropic” and “claude” are rejected.
• description: non-empty, max 1024 characters.
• An optional display_name (up to 255 characters) can be human-friendly.
• The whole upload must stay under 30 MB uncompressed.

Skills come from two sources. Anthropic-managed skills (type: "anthropic") ship prebuilt with short IDs like pptx, xlsx, docx, and pdf, and use date-based versions such as 20251013. Custom skills (type: "custom") are yours: uploaded through the API, private to your workspace, with generated IDs like skill_01AbCdEfGhIjKlMnOpQrStUv.

What GA actually changed

Three things are new or firmed up as of August 20, 2026:

1. No beta header. The Skills API works on the Claude API with just x-api-key and anthropic-version: 2023-06-01.
2. A simpler upload-and-version flow. Anthropic describes GA as bringing “a simpler API for uploading and versioning” custom skills. Versions are first-class resources with their own endpoints.
3. More platforms. The Skills API is available through Microsoft Foundry as well as the Claude API. Skills execute in Claude’s managed sandbox, so there’s still no infrastructure on your side.

The rest of the GA wave matters to skills users too: skills frequently generate files (a deck, a filled spreadsheet), and those outputs come back through the newly GA’d Files API.

The endpoint surface

Everything lives under /v1/skills:

Creating a skill uploads its full file set; creating a version does the same against an existing skill ID. In an Apidog project, this maps cleanly to one folder of six saved requests with {{skill_id}} and {{skill_version}} as environment variables, so promoting a new version through dev and prod environments is a variable change, not a request edit.

Uploading a custom skill

A minimal custom skill is two things: the folder and the upload call. Say you keep a brand-report skill in your repo:

brand-report/
  SKILL.md
  templates/report.html
  scripts/build_report.py

With SKILL.md starting like this:

---
name: brand-report
description: Generates the weekly brand performance report as a formatted HTML document from a CSV of metrics. Use when asked for a brand report, weekly summary deck, or performance writeup.
---

Upload it by posting the files as multipart form data:

curl -X POST https://api.anthropic.com/v1/skills \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F 'files[]=@brand-report/SKILL.md;filename=brand-report/SKILL.md' \
  -F 'files[]=@brand-report/templates/report.html;filename=brand-report/templates/report.html' \
  -F 'files[]=@brand-report/scripts/build_report.py;filename=brand-report/scripts/build_report.py'

The response returns the generated skill_id and the first version’s skver_* ID. Store both; the skill ID goes in your Messages requests, and the version ID is your rollback anchor. Check the exact multipart field names against the Skills API reference for your SDK version, since typed SDK helpers wrap this call in most languages.

Notice the description: it reads like a routing rule. Claude decides whether to load a skill by reading that field, so a description listing the trigger phrases your users say outperforms a one-line label every time.

Using a skill in a Messages request

Skills don’t attach to a request on their own. They ride on the code execution tool, declared through the container parameter:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
            {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Build the Q3 revenue deck from the attached numbers"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

The rules that govern this block:

• The code execution tool must be enabled in tools, since skills execute inside that sandbox. Model support follows the code execution tool’s compatibility list.
• Up to 20 skills per request. Claude reads each skill’s description and loads instructions only for the ones the task needs.
• Version pinning is yours to control. "latest" floats to the newest version; a pinned skver_* ID (or date version for Anthropic skills) freezes behavior. Pin in production, float in dev.

When a skill produces a document, the response carries a file_id you download through the Files API’s GET /v1/files/{file_id}/content. That two-API handshake (Skills to generate, Files to retrieve) is the core production loop.

Versioning: snapshots, not diffs

The versioning model is the part most teams get wrong on the first try. A new version is a complete snapshot, not a delta. When you POST /v1/skills/{skill_id}/versions, you upload the skill’s entire file set again; files you omit are not carried over from the previous version. The name in the new version’s SKILL.md must also match the skill’s existing name.

Treat skill folders like build artifacts: keep the source of truth in your repo, package the whole folder in CI, and push it as a new version. Rollback is then trivial, since old versions remain addressable by their skver_* IDs and a production incident is fixed by re-pinning one string.

Workspace scoping: the multi-tenant trap

Custom skills are accessible to your entire workspace. They are not scoped to an end user, a conversation, or a session, and every API key in the workspace shares them. If you run a multi-tenant product where tenants upload their own skills, one workspace is a data leak waiting to happen.

The fix is the same as for the Files API: create a separate workspace per tenant. The workspace is the isolation boundary, and each organization gets up to 100 workspaces before needing to talk to an account team. Keys, files, and skills all inherit that boundary, so one decision isolates all three.

Long-running skills: pause_turn and container reuse

Skill executions can outlast a single model turn. Two mechanics handle it:

• pause_turn: when a response stops with stop_reason: "pause_turn", append the assistant content to your message history and call again, passing the same container.id. The sandbox picks up where it left off.
• Container reuse: the container object accepts an id from a previous response, keeping installed files and state alive across a multi-turn conversation. That means a skill can build a spreadsheet in turn one and revise it in turn three without regenerating from scratch.

Both patterns are stateful HTTP sequences, which makes them awkward to test by hand and pleasant to test as an Apidog scenario: request one asserts on stop_reason, a script lifts container.id into a variable, request two reuses it, and the final step asserts the generated file_id downloads cleanly. The Apidog CLI runs the same scenario in CI, so a skill version bump can’t silently break your pipeline. If you want to see how skills behave inside another vendor’s ecosystem for comparison, we took Postman’s Claude skill apart in an earlier review.

Where it runs

At GA the Skills API is available on the Claude API and through Microsoft Foundry. Skills execute in Anthropic’s sandbox regardless, so “deployment” is an upload, and there’s no container image, no runtime patching, and no scaling knob on your side. Note the model dependency rather than a platform one: the request must use a model the code execution tool supports, such as claude-opus-5 in the examples above. Our Claude Opus 5 API guide covers that model’s request basics if you’re starting fresh.

FAQ

Do I still need the skills beta header? No. Since August 20, 2026, /v1/skills and the container.skills parameter work with standard headers on the Claude API. Remove any pinned beta flags when you upgrade your SDK.

Can a skill call external APIs while it runs? Skills execute inside Claude’s code sandbox with the code execution tool’s network constraints. Bundle what the skill needs in its folder rather than assuming open egress, and keep API-calling logic in your application layer where you can test it properly.

How many skills can one request load? Up to 20. Claude reads each skill’s description frontmatter to decide which ones the task needs, so descriptions are load-bearing: write them like routing rules, not marketing copy.

What’s the difference between this and Claude Code skills? Same concept, different runtime. Claude Code discovers skill folders on your filesystem; the Skills API hosts them server-side, versioned, for Messages API calls. The folder format with SKILL.md frontmatter is shared, so a skill you wrote for Claude Code usually ports with little change.

Wrapping up

GA turns skills from an experiment into an operational surface: six endpoints, snapshot versioning, workspace isolation, and a clean handoff to the Files API for outputs. The teams that get value fastest treat skills like any other deployable artifact, which means CI packaging, pinned versions in production, and automated tests around the container lifecycle. Model the six endpoints in Apidog, wire the version bump into a test scenario, and you’ll know a bad skill version broke your deck generator before your users do. Download Apidog free and build the harness in an afternoon.