Using Skills on claude.ai, the Claude API, and the Agent SDK

Agent Skills use one open format, a folder with a SKILL.md, across Claude Code, claude.ai, the Claude API, and the Claude Agent SDK, but each surface installs and runs them differently. On claude.ai you upload the skill as a zip in Settings; on the Claude API you reference skills by skill_id in the container parameter alongside the code execution tool, and upload custom ones to /v1/skills; in the Agent SDK you load them from the filesystem with settingSources. Nothing syncs between surfaces, so a skill installed in one place must be installed separately in each of the others.

This guide covers each surface and what to change so one skill works everywhere.

How do skills differ across Claude surfaces?

	Claude Code	claude.ai	Claude API	Agent SDK
How you install	Folder in ~/.claude/skills or .claude/skills	Upload a zip in Settings	Pre-built by skill_id; custom via /v1/skills	Filesystem, same as Claude Code
Who sees it	You, or the repo	Only your account	The whole workspace	Your application
Runtime	Your machine	Code execution sandbox	Code execution container	Your machine or server
Network access	Yours	Depends on settings	None	Yours
Frontmatter	Standard plus Claude Code fields	Standard keys only	Standard keys only	Standard plus Claude Code fields
Plans	Any Claude Code user	Pro, Max, Team, Enterprise with code execution	API accounts	API accounts

The rest of this page goes through each column.

How do I use skills on claude.ai?

claude.ai supports custom skills on Pro, Max, Team, and Enterprise plans. Code execution must be enabled, because skills run scripts inside the code execution sandbox.

1. Get the skill as a zip. Every skill page on this site has a download button, or you can zip a folder yourself:

   cd ~/.claude/skills
   zip -r ~/Desktop/pr-summary.zip pr-summary

   The zip must contain the skill folder with SKILL.md inside it, not a loose SKILL.md and not a parent folder of several skills.

2. In claude.ai, open Settings, go to Capabilities, and find Skills.

3. Upload the zip, then make sure the skill is enabled in the list.

4. Test it with a prompt that matches the description.

Uploaded skills are per user. On Team and Enterprise plans, each person uploads the skills they want, unless your organization distributes them another way.

claude.ai naming and frontmatter rules

claude.ai validates uploads more strictly than Claude Code:

• name may not contain “anthropic” or “claude,” or XML tags. A skill named claude-helper works in Claude Code but must be renamed, for example to helper, before uploading. Rename the folder to match. Every skill on this site already follows this rule.
• Only the open-standard frontmatter keys are accepted: name, description, license, compatibility, metadata, and allowed-tools. Keys like disable-model-invocation, context, paths, model, or argument-hint cause the upload to be rejected.
• Claude Code body features such as !`command` dynamic context and $ARGUMENTS substitution are Claude Code behavior. On other surfaces they show up as literal text, so write portable skills without them.

How do I use skills with the Claude API?

On the API, skills run inside the code execution container. Each request needs three things:

1. The code execution tool in tools.
2. A container parameter listing the skills to make available.
3. The code execution beta flag.

Here is a request using Anthropic’s pre-built pptx skill in Python:

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    betas=["code-execution-2025-08-25"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
        ]
    },
    tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
    messages=[{"role": "user", "content": "Create a 5-slide deck summarizing Q3 churn drivers."}],
)

Beta flags and tool version strings change over time, so check the current API documentation before you ship. Files the skill generates, such as the .pptx, are written in the container, and the response includes a file ID you download through the Files API.

Pre-built skills

Anthropic provides pre-built skills for common document formats, referenced with "type": "anthropic":

skill_id	Purpose
pptx	Create and edit PowerPoint presentations
xlsx	Create and analyze Excel spreadsheets
docx	Create and edit Word documents
pdf	Read, fill, and generate PDFs

Custom skills via /v1/skills

To use your own skill, upload it to the Skills API. It becomes available to the whole workspace and is referenced with "type": "custom" and the returned ID:

Method	Endpoint	Purpose
POST	/v1/skills	Create a skill from uploaded files
GET	/v1/skills	List skills in the workspace
GET	/v1/skills/{skill_id}	Get one skill
DELETE	/v1/skills/{skill_id}	Delete a skill
POST	/v1/skills/{skill_id}/versions	Upload a new version
GET	/v1/skills/{skill_id}/versions	List versions

container={
    "skills": [
        {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
        {"type": "custom", "skill_id": "skill_abc123", "version": "latest"},
    ]
}

Pin a specific version instead of latest in production so a new upload does not change behavior under you.

API runtime constraints

The code execution container is deliberately locked down:

• No network access. A skill cannot call external APIs, fetch URLs, or reach your database.
• No runtime package installs. pip install at runtime will not work. Use libraries already available in the container, or ship pure-Python helpers inside the skill’s scripts/ folder.
• Inputs come from the request. Pass data in the conversation or through uploaded files.

A skill that shells out to gh, psql, or curl will work in Claude Code and fail on the API. Design API skills around local computation on provided files.

How do I use skills with the Claude Agent SDK?

The Agent SDK runs the same harness as Claude Code, so skills load from the filesystem: .claude/skills/ in the project directory and ~/.claude/skills/ for the user. The SDK does not read filesystem settings unless you ask it to. Set settingSources and allow the Skill tool:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Review the migration in migrations/20261012_add_region.sql",
  options: {
    cwd: "/path/to/repo",
    settingSources: ["user", "project"], // load ~/.claude and ./.claude, including skills
    allowedTools: ["Skill", "Read", "Grep", "Bash"],
  },
})) {
  if (message.type === "result") console.log(message.result);
}

With "project" in settingSources, a skill committed to the repo at .claude/skills/migration-review/ is available to your agent exactly as it is in Claude Code, including Claude Code-only frontmatter fields. In Python the option is setting_sources. See the Agent SDK documentation for current option names.

Because the SDK runs on your infrastructure, skills have whatever network and filesystem access your process has. Apply the same review you would for any dependency; the skill safety guide explains what to check.

What is portable between surfaces?

Feature	Claude Code and Agent SDK	claude.ai and API
name, description	Yes	Yes, with naming restrictions
license, compatibility, metadata	Yes	Yes
allowed-tools	Yes	Accepted (experimental in the spec)
disable-model-invocation, user-invocable	Yes	Rejected on upload
context: fork, agent, model, effort	Yes	Rejected on upload
paths, hooks, shell, arguments	Yes	Rejected on upload
!`command` dynamic context	Yes	Not processed
$ARGUMENTS, ${CLAUDE_SKILL_DIR}	Yes	Not substituted
references/, scripts/, assets/	Yes	Yes
Scripts using network or CLIs	Yes	No on the API

A checklist for portable skills

If a skill should work everywhere:

• Name avoids “claude” and “anthropic”; folder matches
• Frontmatter uses only name, description, license, compatibility, metadata, allowed-tools
• No !`command` lines; tell Claude to run the command as a step instead
• Scripts referenced by relative path (scripts/fill_form.py), not ${CLAUDE_SKILL_DIR}
• Scripts use only the standard library or commonly available packages, with no network calls
• compatibility states requirements honestly, for example "Requires Python 3 with pypdf. No network access needed."

A portable frontmatter block:

---
name: pdf-form-filler
description: Fills PDF forms from structured data and verifies every field was written. Use when the user wants to fill, complete, or populate a PDF form.
license: MIT
compatibility: "Python 3 with pypdf. Works offline."
metadata:
  version: "1.2.0"
---

If you need Claude Code-only behavior as well, keep two variants: a portable base for uploads and a Claude Code edition with extra fields. Some teams generate the portable zip from the Claude Code version in CI by stripping the extra keys.

Next steps

• Field reference with portability notes: SKILL.md format reference
• Install methods for each surface: How to install Claude Code skills
• Document skills that suit the API: pdf-toolkit, xlsx-spreadsheets, and the documents category
• Build agents on the SDK: headless-ci-agent
• Official sources: Agent Skills specification, Anthropic’s skills repository