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

Anthropic moved the Claude Skills API, computer use, and the Files API to general availability on August 20, 2026 — no more beta headers, multi-action turns for computer use, and a new browser use tool. One thing GA does not fix: skills still fire only when Claude decides to invoke them, so version pinning and activation design stay on your plate.

What GA actually changed on August 20

Existing beta integrations keep working while you migrate. Beyond that, Anthropic's launch post bundles several concrete changes:

• No beta-header dance. The current skills guide lists exactly two prerequisites: a Claude API key and code execution enabled in the request. The beta headers that pre-GA tutorials required are gone from the docs.
• Multi-action turns. The updated computer use tool executes several actions per model call (click, type, key press, screenshot) instead of one. Anthropic's @ClaudeDevs account reports early-access customers seeing 20–40% fewer round trips per task.
• A browser use tool. It combines screenshots with page structure, so the agent targets a specific field or button rather than pixel coordinates — aimed at web portals like insurance submissions.
• Files API scale. 1 TB of storage per organization, 5x higher rate limits (500 RPM per the @ClaudeDevs thread), and automatic file expiration.
• Compliance path. Computer use is now eligible for HIPAA-regulated workloads under Anthropic's BAA.
• Cloud availability. The Skills API and Files API are also live through Microsoft Foundry; the updated computer use and browser use tools are "coming soon" to Vertex AI with no date attached.

The three-API stack in one loop

Anthropic's claims-agent example shows the loop end to end: pull an intake document by file ID (Files API), apply a skill with the filing procedure (Skills API), complete the insurer portal with browser use (computer use), then save the confirmation back as a file. Uploads happen once and get referenced by file_id afterward, instead of being re-sent on every request.

Both number sets that arrived with the launch are vendor-side. In the launch post, research engineer Davide Locatelli reported the longest claims workflow falling from 32 minutes to 13 minutes with completion reaching 100%; separately, David Mlčoch, co-founder of Asteroid, tested healthcare computer-use flows during early access:

"32-52% fewer model calls, 25-32% lower cost per task, 100% completion on every workflow, up from 77%" — @MlcochDavid

Calling the Claude Skills API from the Messages API

Attaching a skill takes one parameter: a container object on your Messages API request holding a skills array. Each entry carries a type (anthropic or custom), a skill_id, and an optional version.

The mechanics around that parameter, from the official skills guide:

• Code execution must be enabled and the model must support it; the guide's examples use claude-opus-5 with the code_execution_20250825 tool type and max_tokens=4096.
• A single request supports up to 20 skills.
• Skills execute in Anthropic's code-execution sandbox: no network access, no runtime package installs, and a fresh container per request unless you reuse a returned container.id across turns (each response includes expires_at).
• You never host skill files yourself — Anthropic runs them in the container.

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    tools=[{"type": "code_execution_20250825"}],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "20251013"},
            {"type": "custom", "skill_id": "skill_01...", "version": "skver_01..."},
        ]
    },
    messages=[{"role": "user", "content": "Build the Q3 revenue summary"}],
)

Input documents follow the reverse path: upload them through the Files API first, then reference them in a container upload block. The request is the standard Anthropic Messages API shape, so it works with a direct key or an Anthropic-compatible relay such as AIReiter's Claude API.

Built-in skills use short, human-readable IDs — pptx, xlsx, docx, pdf — with date-formatted versions such as 20251013 or latest. Custom skills get skill_01... IDs scoped to your workspace.

Shipping a custom Skill: the rules that reject you

A custom skill is a directory whose top-level SKILL.md carries YAML frontmatter (name and description), optionally with scripts and reference files alongside it. The minimum viable file looks like this:

---
name: eu-claims-filing
description: Use when filing or amending EU insurance claims. Loads the
  carrier-specific submission procedure, required fields, and rejection
  codes before filling any portal form.
---

# EU claims filing procedure
1. Pull the intake document by file_id ...

Upload happens as a ZIP archive or as individual files (the Python SDK offers files_from_dir), and Anthropic enforces hard limits before the skill ever runs, all listed in the skills guide:

Management runs through the ant CLI or the API endpoints behind it, per the same guide. The path from file to pinned version:

ant skills create ./eu-claims-filing   # returns skill_01...
ant skills:versions create skill_01...  # returns skver_01... — pin this in production

Two behaviors surprise teams the first time: a new version is a full snapshot — you re-upload the entire file set, and anything omitted does not carry forward — and deleting a skill deletes every version of it.

Production checklist: pin, isolate, cache

The failure modes that bite in production are mutable versions, workspace-wide permissions, and cache misses — the skills guide is explicit about all three.

1. Pin versions. With latest or no version at all, anyone with workspace access who uploads a new version instantly changes what your deployed agent executes. Pin skver_... IDs in production; keep latest for active development.
2. Treat the workspace as the tenant boundary. Every API key in a workspace can read, invoke, and delete all custom skills in it — the isolation boundary is the workspace, not the user or session. Multi-tenant applications should use one workspace per tenant, and note the 100-workspace default cap.
3. Keep the skill list stable for caching. Changing the skill list, including its order, changes the system-prompt prefix and busts the prompt cache. Pinning custom versions also protects that prefix, because a re-uploaded latest description would otherwise rewrite it. On per-token billing, a skill list that drifts between requests quietly erases your cache-hit savings.
4. Handle pause_turn. Long-running skills return stop_reason: "pause_turn"; resend the returned content in a later request to continue, or modify the conversation to interrupt.
5. Know your retention posture. Agent Skills are not covered by zero-data-retention arrangements — skill definitions and execution data follow Anthropic's standard retention policy. With the Compliance API enabled, the Activity Feed logs skill and skill-version creation and deletion (only from enablement onward).
6. Catch the right errors. Wrap calls to catch anthropic.BadRequestError and separate skill-related failures from other invalid-request errors.
7. Don't attach unused skills. The docs state this outright: including unused skills impacts performance.

The activation problem no API change fixes

GA upgraded the infrastructure around skills, not how Claude chooses them. A recurring concern in the user threads below: skills behave as triggered procedures, not as a second system prompt.

"My problem with Claude Skills is that they are not skills. Nothing forces Claude to actually use them. Claude does whatever it wants... These are just md files." — @Yampeleg, written pre-GA; the invocation mechanism is unchanged

The r/ClaudeAI thread on whether skills actually work distills the practical fixes:

"userstyle gets prepended every turn but skills only fire when claude decides to invoke based on the description." — u/samxu01

"Skills must have a simple, clear metadata description that also focuses on an action that Claude is doing." — u/Chadum

Four rules fall out of those threads:

• Write the description around trigger phrases and the action, not a persona.
• Put steps, checks, rules, and tool choices in the body — u/MartinMystikJonas's test: "If your skills define steps agent should do, things it should check, rules it should follow and tools it should use then it is useful."
• Encode things Claude does poorly natively, per u/Actual_Committee4670.
• Push always-on requirements into your system prompt or CLAUDE.md — prepended every turn, per u/samxu01 above — and reserve hooks for lifecycle moments like before a commit.

Quick answers

Do I still need beta headers for the Skills API?

No. Since the August 20, 2026 GA, the prerequisites are a Claude API key and code execution enabled, with no beta header in the current docs.

Do skills eat my context window?

Only their metadata at first. Per the skills guide, Claude receives each skill's frontmatter up front, copies the files into the container, and loads full instructions only when the task calls for them — which is why the docs warn against attaching unused skills.

What is the difference between a Skill and MCP?

A skill is a package of instructions and scripts that runs inside Claude's sandbox with no network access; MCP connects Claude to live external systems — the distinction Anthropic draws in its skills overview. A claims workflow can use both — an MCP server for the policy database, a skill for the filing procedure.

Can one SKILL.md run in Claude.ai, Claude Code, and the API?

The SKILL.md format is shared, but delivery differs per surface: workspace-uploaded skills on the API, .claude/skills directories in Claude Code, and plan-level uploads in the Claude.ai app.

Does the Skills API work under zero data retention?

No — Agent Skills are excluded from zero-data-retention arrangements; skill definitions and execution data follow the standard retention policy.

Which mechanism for which requirement

Choose by invocation timing:

August 20 made the skill mechanism production-ready; it did not make the rows in this table interchangeable.

Related reading: Claude API pricing per model and token and recording a Claude skill in Claude Code.