Claude API skills. Where they live and how to install them.

What skills are in the Claude API

On the Claude API, skills are not files that sit in a folder next to your code. They are resources attached to your workspace or referenced by ID, and they run inside the code execution tool's container. Anthropic documents two kinds. Pre-built skills are maintained by Anthropic and referenced by short IDs: pptx, xlsx, docx and pdf. Custom skills are ones you upload; each gets a generated ID that starts with skill_.

Because Skills need the code execution tool, every request that uses one must enable that tool and use a model that supports it.

Where skills live

There are no project or user folders. Custom skills are stored in your Anthropic workspace, and the documentation warns that they are workspace-wide: any API key with access to the workspace can read, invoke and delete every custom skill in it. If you build a multi-tenant product on the Skills API, Anthropic recommends a separate workspace per tenant.

Skills uploaded to claude.ai are not available here, and skills uploaded here do not appear in claude.ai or Claude Code.

Upload a custom skill

A skill bundle is a directory with a SKILL.md at the top level that has name and description frontmatter, plus any scripts or resources. The name can use lowercase letters, numbers and hyphens, up to 64 characters, and cannot contain anthropic or claude. The description can be up to 1,024 characters. The examples use frontend-design from anthropics/skills, located at skills/frontend-design.

First, get the folder:

git clone --depth 1 https://github.com/anthropics/skills.git skills-src
cp -r skills-src/skills/frontend-design frontend-design

Then upload it with the ant command-line tool, which uploads the directory itself:

ant apply frontend-design

Or send the files to the endpoint directly. One -F flag is needed for each file in the skill:

curl -X POST "https://api.anthropic.com/v1/skills" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "files[]=@frontend-design/SKILL.md;filename=frontend-design/SKILL.md"

You can also upload a zip archive. The Python SDK has a files_from_dir helper that takes a directory path. The Skills API is out of beta and does not need a beta header, although requests that still send skills-2025-10-02 keep working.

Use a skill in a request

Skills go in the container parameter of a Messages request, alongside the code execution tool. Each entry has a type (anthropic or custom), a skill_id and an optional version. You can include up to 20 skills per request. Anthropic's pre-built skills use date-based versions or latest; custom skills use a version ID or latest. See the skills guide for the exact request shape in cURL and each SDK.

When a skill creates a document, the response includes a file_id, and you download the file with the Files API.

Check that it worked

Call the list endpoint, GET /v1/skills, and filter with source=custom to see your uploads. Fetch one skill by ID to see its versions. A successful request that includes the skill in container.skills and produces output that follows the skill's instructions is the real test.

Update and remove

New versions are uploaded to the skill's /versions endpoint, and requests can pin a version or use latest. Deleting a skill with DELETE /v1/skills/{skill_id} now removes every version along with the skill, so check before calling it.

Troubleshooting

• Requests with skills fail: confirm the code execution tool is in the tools list and the model supports it.
• The skill cannot reach the internet or install packages: API containers have no network access and no runtime package installation, so skills must work with what is already installed.
• Upload is rejected: check that SKILL.md is at the top level of the bundle, the frontmatter has name and description, and the name avoids reserved words.
• A teammate's key can see your skill: this is expected, because custom skills are shared across the workspace.
• Zero data retention: Anthropic states that Agent Skills are not covered by zero data retention arrangements.

Safety

Anthropic advises using skills only from sources you trust and auditing everything in a skill, including scripts and any external URLs it fetches, because a malicious skill can direct Claude to misuse tools or code execution. Since every key in the workspace can invoke every custom skill, review uploads before they land in a shared workspace.