Claude API Skills: Integrate Agent Skills with the Messages API

Yes. You can use Claude Agent Skills through Anthropic’s Messages API. The Skills API is generally available, and Anthropic’s current release notes say requests no longer require the skills-2025-10-02 beta header. Skills run with the code execution tool; a request selects a Skill through container.skills. This is the direct Anthropic API workflow, not setup that you can assume will transfer from Claude’s web apps or Claude Code. (platform.claude.com)

What a Skill means in an API request

An Agent Skill packages instructions and resources for specialized tasks. In a Messages API request, you select it in the container.skills array and include the code execution tool. Anthropic’s prebuilt document Skills include pptx, xlsx, docx, and pdf; custom Skills are managed separately and use their own Skill IDs. (platform.claude.com)

Prerequisites

Before running the example, you need:

1. An Anthropic API key, available as the ANTHROPIC_API_KEY environment variable.
2. A model that supports code execution. The model compatibility list includes claude-sonnet-4-6; the example uses that exact model ID.
3. The code execution tool in the Messages request. code_execution_20250825 supports Bash and file operations. The current documentation says code execution tool versions do not require an anthropic-beta header. (platform.claude.com)

The Skills API and Files API are generally available on the Claude API. For the configuration below, send the standard anthropic-version header, but do not add the retired Skills beta header. (platform.claude.com)

Create a presentation with a prebuilt Skill

First, list Anthropic-managed Skills. The source=anthropic filter selects prebuilt Skills; the request uses the API key and API version headers, with no Skills beta header:

curl --fail-with-body -sS \
  "https://api.anthropic.com/v1/skills?source=anthropic" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

Then ask the pptx Skill to create a presentation. This request selects the supported model explicitly and includes the code execution tool required for Skills:

curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "Use the PowerPoint skill to create a one-slide presentation with three practical benefits of cycling to work."
      }
    ],
    "container": {
      "skills": [
        { "type": "anthropic", "skill_id": "pptx" }
      ]
    },
    "tools": [
      { "type": "code_execution_20250825", "name": "code_execution" }
    ]
  }'

The Skill is selected by its type and skill_id; a version can also be specified when you need to pin one. (platform.claude.com)

Inspect and download the result

A successful Messages response alone does not confirm that the presentation was created. Inspect the response’s content for a bash_code_execution_tool_result block and a returned file_id in its result content. Anthropic’s Skills cookbook describes generated file IDs in code-execution results. (github.com)

Use that ID to download the generated file from the Files API:

FILE_ID="file_id_from_the_response"

curl --fail-with-body -sS \
  "https://api.anthropic.com/v1/files/${FILE_ID}/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -o cycling-benefits.pptx

The download endpoint is GET /v1/files/{file_id}/content. Confirm that the command succeeds and that cycling-benefits.pptx opens as a presentation. (platform.claude.com)

Also check the Messages response’s stop_reason. If it is max_tokens, Anthropic’s guidance is to raise max_tokens or continue the response; do not treat a truncated result as complete. If no file_id is returned, the artifact has not been verified—inspect the response and resolve the incomplete run before treating the workflow as successful. (platform.claude.com)

Using a custom Skill

Custom Skills are uploaded and managed through the Skills API. To use one in a Messages request, replace the prebuilt Skill entry with its returned ID and set type to custom:

{
  "container": {
    "skills": [
      { "type": "custom", "skill_id": "YOUR_SKILL_ID" }
    ]
  }
}

The same Messages API and code execution requirements apply. Consult the Skills API reference for custom Skill upload and version-management request details. (platform.claude.com)

Production considerations

• Check model support when changing models. Skills require code execution, so confirm the model supports that tool before deploying a model change. (platform.claude.com)
• Review data-handling requirements. Anthropic’s code execution documentation marks the feature as not eligible for Zero Data Retention (ZDR) or HIPAA. If either eligibility is required, do not assume this workflow qualifies. (platform.claude.com)
• Protect generated file IDs. Files are accessible within their workspace. Keep file IDs server-side and do not accept untrusted IDs from end users. (platform.claude.com)
• Validate generated artifacts. Check that the expected file exists, opens, and contains the requested content before passing it to a downstream process.

Bottom line: Claude Agent Skills can be used through the direct Claude Messages API. Select a prebuilt or custom Skill in container.skills, use a model that supports code execution, inspect the response for a generated file_id, and retrieve the artifact through the Files API. The Skills API is generally available; the current release notes say the Skills beta header is no longer required. (platform.claude.com)

Sources

Claude Platform release notes

Using Agent Skills with the API

Get started with Agent Skills in the API

Code execution tool

Files API

Download File

Anthropic Claude Cookbook file utilities

Stop reasons and fallback