Claude Skills on claude.ai and the API

Skills started in Claude Code, but the format was designed to travel: the same folder-with-a-SKILL.md now runs on claude.ai, on the Claude API, inside Managed Agents, and in the Agent SDK. What changes per surface is how skills get there and what executes them. This guide covers each. (New to the format? Start with What Are Claude Skills?)

claude.ai: upload and go

On claude.ai (web and desktop), skills are a first-class capability:

1. Enable code execution under Settings → Capabilities — skills run inside it.
2. Zip your skill folder (the one containing SKILL.md) and upload it under Settings → Customize → Skills.

That's the whole flow, available on every plan. On Team and Enterprise, admins can enable skills workspace-wide so one upload serves the org.

Anthropic's document skills — Word (docx), Excel (xlsx), PowerPoint (pptx), and PDF — are pre-built and always active on claude.ai: ask for a spreadsheet and the xlsx skill is already doing the formatting. They're the best public demonstration of what a well-built skill looks like; the source is in the public anthropics/skills repo.

The Messages API: skills + code execution

On the API, skills attach to a request through the container parameter, and they execute inside the code-execution tool's sandbox. Two beta headers are required together:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "custom", "skill_id": "skill_01AbC...", "version": "latest"},
        ]
    },
    tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
    messages=[{"role": "user", "content": "Build a budget model in a spreadsheet"}],
)

Generated files (.xlsx, .pptx, …) are written inside the container; the response carries file IDs you download via the Files API (files-api-2025-04-14).

Custom skills: the /v1/skills endpoint

Upload your own skills once, reference them everywhere in the workspace:

• POST /v1/skills — upload a skill (returns the skill_id)
• GET /v1/skills — list pre-built and custom skills
• POST /v1/skills/{skill_id}/versions — publish a new version

Versions are epoch-stamped IDs, and "latest" always resolves to the newest — which gives API skills the real versioning story the SKILL.md format itself deliberately lacks (see the reference). Uploaded skills are shared workspace-wide.

Constraints to design around

• Max 8 skills per request — attach what the task needs, not your whole library.
• 30 MB per uploaded skill.
• No network access in the container, and no runtime package installs — a skill that shells out to pip install or calls an external API works in Claude Code and fails here. Bundle helpers as files; rely on the pre-installed scientific/document Python stack.

That last point is the practical portability rule: a skill built on reading bundled files and writing outputs ports cleanly across every surface; a skill built on network calls is Claude Code-only.

Managed Agents

Anthropic's hosted agents take skills as part of the persisted agent config — up to 20 per agent, mixed pre-built and custom:

agent = client.beta.agents.create(
    name="Financial Agent",
    model="claude-opus-4-8",
    skills=[
        {"type": "anthropic", "skill_id": "xlsx"},
        {"type": "custom", "skill_id": "skill_01AbC...", "version": "latest"},
    ],
)

Every session that references the agent gets its skills in the session container, loaded with the same progressive disclosure.

The Agent SDK

Building your own agent on the Claude Agent SDK? Skills load from the filesystem — the same ~/.claude/skills/ and .claude/skills/ directories Claude Code uses — controlled by two options: setting_sources (which directories to read) and skills ("all", a specific list, or []). There's no programmatic create-skill API; skills are artifacts, which means they live in git and deploy with your code.

One behavioral difference: the SDK ignores a skill's allowed-tools frontmatter — tool permissions come from the SDK's own allowedTools configuration.

One skill, many deploys

The mental model that makes this all manageable: the SKILL.md in your repo is the source of truth, and each surface is a deploy target. Nothing syncs — claude.ai, the API, and your filesystem each hold their own copy. Teams that use skills across surfaces keep them in one directory in git and treat "upload to claude.ai" and "publish to /v1/skills" as release steps, exactly like publishing a package. The packaging guide covers the Claude Code half of that story.