Skills

Skills are reusable, filesystem-based resources that give your agent domain-specific expertise: workflows, context, and best practices that turn a general-purpose agent into a specialist. Each skill you add incurs a modest cost on the session’s context window, adding instructions and metadata that help the model use the skill. Learn more in the Agent Skills overview. Skills reach your agent in two ways: attach them through the agent’s skills array, or load them from a GitHub repository mounted on the session. Attached skills come in two types. All skills work the same way: your agent invokes them automatically when they are relevant to the task.

Pre-built OMA skills: Common document tasks such as PowerPoint, Excel, Word, and PDF handling (pptx, xlsx, docx, pdf).
Custom skills: Skills you author and upload to your workspace.

To learn how to author custom skills, see Agent Skills and Skill authoring best practices. To upload a custom skill to your workspace, see Create a custom skill.

Managed Agents API requests require the managed-agents-2026-04-01 beta header, except memory store endpoints, which use agent-memory-2026-07-22 instead. The SDK sets the correct beta header automatically. See Beta headers.

Create a custom skill

A custom skill is a directory containing a SKILL.md file plus any supporting files, uploaded to your workspace as a zip archive or as individual files. Creating the skill returns the skill_* ID you reference when attaching it to an agent. OMA pre-built skills are already available in every workspace and don’t require this step. To use only pre-built skills, skip to Attach skills to an agent. When you call the Skills API directly with cURL, pass the anthropic-beta: skills-2025-10-02 header explicitly. The CLI and SDKs send it automatically. These examples omit the optional display_title field, so the skill’s title is derived from SKILL.md. An explicitly passed display_title must be unique among the custom skills in your workspace.

curl -X POST "http://localhost:38080/v1/skills" \
  -H "x-api-key: $OMA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: skills-2025-10-02" \
  -F "files[]=@example_skill.zip"

ant beta:skills create \
  --file example_skill.zip

import anthropic
from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

skill = client.beta.skills.create(
    files=files_from_dir("example_skill"),
)

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")

import Anthropic from "@anthropic-ai/sdk";
import { toFile } from "@anthropic-ai/sdk";
import fs from "node:fs";

const client = new Anthropic();

const skill = await client.beta.skills.create({
  files: [await toFile(fs.createReadStream("example_skill.zip"), "example_skill.zip")]
});

console.log(`Created skill: ${skill.id}`);
console.log(`Latest version: ${skill.latest_version}`);

using System.IO;
using Anthropic;
using Anthropic.Models.Beta.Skills;

AnthropicClient client = new();

var parameters = new SkillCreateParams
{
    Files = [
        new FileStream("example_skill.zip", FileMode.Open, FileAccess.Read)
    ],
};

var skill = await client.Beta.Skills.Create(parameters);

Console.WriteLine($"Created skill: {skill.ID}");
Console.WriteLine($"Latest version: {skill.LatestVersion}");

package main

import (
    "context"
    "fmt"
    "io"
    "log"
    "os"

    "github.com/anthropics/anthropic-sdk-go"
)

func main() {
    client := anthropic.NewClient()

    zipFile, err := os.Open("example_skill.zip")
    if err != nil {
        log.Fatal(err)
    }
    defer zipFile.Close()

    skill, err := client.Beta.Skills.New(context.TODO(), anthropic.BetaSkillNewParams{
        Files: []io.Reader{zipFile},
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Created skill: %s\n", skill.ID)
    fmt.Printf("Latest version: %s\n", skill.LatestVersion)
}

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.MultipartField;
import com.anthropic.models.beta.skills.SkillCreateParams;
import com.anthropic.models.beta.skills.SkillCreateResponse;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;

void main() throws IOException {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    SkillCreateParams params = SkillCreateParams.builder()
        .addFile(MultipartField.<InputStream>builder()
            .value(Files.newInputStream(Path.of("example_skill.zip")))
            .filename("example_skill.zip")
            .contentType("application/zip")
            .build())
        .build();

    SkillCreateResponse skill = client.beta().skills().create(params);

    IO.println("Created skill: " + skill.id());
    IO.println("Latest version: " + skill.latestVersion().orElseThrow());
}

<?php

use Anthropic\Client;
use Anthropic\Core\FileParam;

$client = new Client();

$skill = $client->beta->skills->create(
    files: [
        FileParam::fromResource(fopen('example_skill.zip', 'r'))
    ],
);

echo "Created skill: {$skill->id}\n";
echo "Latest version: {$skill->latestVersion}\n";

require "anthropic"

client = Anthropic::Client.new

skill = client.beta.skills.create(
  files: [
    File.open("example_skill.zip", "rb")
  ]
)

puts "Created skill: #{skill.id}"
puts "Latest version: #{skill.latest_version}"

To list, retrieve, delete, and version custom skills, see Managing custom skills. For the full request and response schemas, see the Create Skill API reference. Skill bundles upload directly to the Skills API rather than through the Files API.

Attach skills to an agent

Attach skills when creating an agent. Each session supports up to 500 skills, counted as the deduplicated set across every agent in the session (see Multiagent orchestration).

Mounting more skills increases the time it takes for the session’s sandbox to start. Attach only the skills each agent needs for its task.

Each entry in the skills array uses the following fields:

Field	Description
`type`	Either `anthropic` for pre-built skills or `custom` for workspace-authored skills.
`skill_id`	The skill identifier. For OMA skills, use the short name (for example, `xlsx`). For custom skills, use the `skill_*` ID returned at creation (see Create a custom skill).
`version`	Pin to a specific version or use `latest`. Optional. Defaults to `latest` when omitted. Applies to both OMA and custom skills.

agent=$(curl -sS http://localhost:38080/v1/agents \
  -H "x-api-key: $OMA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  --json @- <<'EOF'
{
  "name": "Financial Analyst",
  "model": "claude-opus-5",
  "system": "You are a financial analysis agent.",
  "skills": [
    {"type": "anthropic", "skill_id": "xlsx"},
    {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
  ]
}
EOF
)

ant beta:agents create <<'YAML'
name: Financial Analyst
model: claude-opus-5
system: You are a financial analysis agent.
skills:
  - type: anthropic
    skill_id: xlsx
  - type: custom
    skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
    version: latest
YAML

agent = client.beta.agents.create(
    name="Financial Analyst",
    model="claude-opus-5",
    system="You are a financial analysis agent.",
    skills=[
        {
            "type": "anthropic",
            "skill_id": "xlsx",
        },
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",
        },
    ],
)

const agent = await client.beta.agents.create({
  name: "Financial Analyst",
  model: "claude-opus-5",
  system: "You are a financial analysis agent.",
  skills: [
    {
      type: "anthropic",
      skill_id: "xlsx"
    },
    {
      type: "custom",
      skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv",
      version: "latest"
    }
  ]
});

using Anthropic.Models.Beta.Agents;

var agent = await client.Beta.Agents.Create(new()
{
    Name = "Financial Analyst",
    Model = BetaManagedAgentsModel.ClaudeOpus5,
    System = "You are a financial analysis agent.",
    Skills =
    [
        new BetaManagedAgentsAnthropicSkillParams { Type = BetaManagedAgentsAnthropicSkillParamsType.Anthropic, SkillID = "xlsx" },
        new BetaManagedAgentsCustomSkillParams { Type = BetaManagedAgentsCustomSkillParamsType.Custom, SkillID = "skill_01AbCdEfGhIjKlMnOpQrStUv", Version = "latest" },
    ],
});

agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
    Name: "Financial Analyst",
    Model: anthropic.BetaManagedAgentsModelConfigParams{
        ID: anthropic.BetaManagedAgentsModelClaudeOpus5,
    },
    System: anthropic.String("You are a financial analysis agent."),
    Skills: []anthropic.BetaManagedAgentsSkillParamsUnion{
        {OfAnthropic: &anthropic.BetaManagedAgentsAnthropicSkillParams{
            SkillID: "xlsx",
            Type:    anthropic.BetaManagedAgentsAnthropicSkillParamsTypeAnthropic,
        }},
        {OfCustom: &anthropic.BetaManagedAgentsCustomSkillParams{
            SkillID: "skill_01AbCdEfGhIjKlMnOpQrStUv",
            Type:    anthropic.BetaManagedAgentsCustomSkillParamsTypeCustom,
            Version: anthropic.String("latest"),
        }},
    },
})
if err != nil {
    panic(err)
}
_ = agent

import com.anthropic.models.beta.agents.*;

var agent = client.beta().agents().create(
    AgentCreateParams.builder()
        .name("Financial Analyst")
        .model(BetaManagedAgentsModel.CLAUDE_OPUS_5)
        .system("You are a financial analysis agent.")
        .addSkill(
            BetaManagedAgentsAnthropicSkillParams.builder()
                .type(BetaManagedAgentsAnthropicSkillParams.Type.ANTHROPIC)
                .skillId("xlsx")
                .build()
        )
        .addSkill(
            BetaManagedAgentsCustomSkillParams.builder()
                .type(BetaManagedAgentsCustomSkillParams.Type.CUSTOM)
                .skillId("skill_01AbCdEfGhIjKlMnOpQrStUv")
                .version("latest")
                .build()
        )
        .build()
);

$agent = $client->beta->agents->create(
    name: 'Financial Analyst',
    model: 'claude-opus-5',
    system: 'You are a financial analysis agent.',
    skills: [
        ['type' => 'anthropic', 'skill_id' => 'xlsx'],
        ['type' => 'custom', 'skill_id' => 'skill_01AbCdEfGhIjKlMnOpQrStUv', 'version' => 'latest'],
    ],
);

agent = client.beta.agents.create(
  name: "Financial Analyst",
  model: "claude-opus-5",
  system_: "You are a financial analysis agent.",
  skills: [
    {type: "anthropic", skill_id: "xlsx"},
    {type: "custom", skill_id: "skill_01AbCdEfGhIjKlMnOpQrStUv", version: "latest"}
  ]
)

Load skills from a GitHub repository

Skills can also live in your codebase. When a session mounts a repository through the github_repository resource, the repository’s root .claude/skills directory is scanned at session start, and each skill found there becomes available to the agent. No upload and no entry in the agent’s skills array are required. The agent sees each discovered skill’s name, description, and path in the sandbox, and reads the skill’s SKILL.md when a task matches, including any scripts and resources the skill ships. Discovery relies on the agent’s read tool from the agent toolset, which is enabled by default; an agent with read disabled doesn’t load repository skills.

Repository skills are agent instructions, so a mounted repository is part of your agent’s trust boundary. Anyone who can commit to the repository (a merged external pull request, a compromised dependency, a contributor) can add or change a skill, the platform loads it at session start without a review step, and session tools such as bash and web_fetch give those instructions real reach. Mount only repositories you trust, and review .claude/skills before mounting a repository that accepts outside contributions.

Repository skill discovery runs in cloud sandboxes. Self-hosted sandboxes don’t support GitHub repository resources.

Discovery finds skills at exactly .claude/skills/<skill-name>/SKILL.md, one directory level deep at the repository root:

your-repo/
- .claude/
  - skills/
    - code-review/
      - SKILL.md
    - release-process/
      - SKILL.md
      - scripts/
        
        run_checks.sh
- src/

Locations that don’t match this layout aren’t discovered at session start:

.claude/skills/SKILL.md: a SKILL.md with no skill directory around it
.claude/skills/tools/code-review/SKILL.md: nested more than one directory level deep
skills/code-review/SKILL.md: a skills directory outside .claude

A .claude/skills directory elsewhere in the repository, such as inside a package subdirectory, isn’t announced at session start; those skills can still surface when the agent reads files under that subtree. Repository skills use the same SKILL.md format as the custom skills you upload. For the format and authoring guidance, see Agent Skills and Skill authoring best practices. To load skills from a repository, create a session that mounts it. This is the same request shown in Accessing GitHub; mount_path is optional and defaults to /workspace/<repo-name>:

session_id=$(curl -fsS http://localhost:38080/v1/sessions \
  -H "x-api-key: $OMA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<JSON | jq -r '.id'
{
  "agent": "$agent_id",
  "environment_id": "$environment_id",
  "resources": [
    {
      "type": "github_repository",
      "url": "https://github.com/org/repo",
      "mount_path": "/workspace/repo",
      "authorization_token": "ghp_your_github_token"
    }
  ]
}
JSON
)

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --transform id --raw-output <<'EOF'
resources:
  - type: github_repository
    url: https://github.com/org/repo
    mount_path: /workspace/repo
    authorization_token: ghp_your_github_token
EOF
)

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "github_repository",
            "url": "https://github.com/org/repo",
            "mount_path": "/workspace/repo",
            "authorization_token": "ghp_your_github_token",
        },
    ],
)

const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  resources: [
    {
      type: "github_repository",
      url: "https://github.com/org/repo",
      mount_path: "/workspace/repo",
      authorization_token: "ghp_your_github_token",
    },
  ],
});

var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    Resources =
    [
        new BetaManagedAgentsGitHubRepositoryResourceParams
        {
            Type = "github_repository",
            Url = "https://github.com/org/repo",
            MountPath = "/workspace/repo",
            AuthorizationToken = "ghp_your_github_token",
        },
    ],
});

session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
    Agent:         anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
    EnvironmentID: environment.ID,
    Resources: []anthropic.BetaSessionNewParamsResourceUnion{
        {
            OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{
                Type:               anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository,
                URL:                "https://github.com/org/repo",
                MountPath:          anthropic.String("/workspace/repo"),
                AuthorizationToken: "ghp_your_github_token",
            },
        },
    },
})
if err != nil {
    panic(err)
}

var session = client.beta().sessions().create(SessionCreateParams.builder()
    .agent(agent.id())
    .environmentId(environment.id())
    .addResource(BetaManagedAgentsGitHubRepositoryResourceParams.builder()
        .type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY)
        .url("https://github.com/org/repo")
        .mountPath("/workspace/repo")
        .authorizationToken("ghp_your_github_token")
        .build())
    .build());

$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
    resources: [
        [
            'type' => 'github_repository',
            'url' => 'https://github.com/org/repo',
            'mountPath' => '/workspace/repo',
            'authorizationToken' => 'ghp_your_github_token',
        ],
    ],
);

session = client.beta.sessions.create(
  agent: agent.id,
  environment_id: environment.id,
  resources: [
    {
      type: "github_repository",
      url: "https://github.com/org/repo",
      mount_path: "/workspace/repo",
      authorization_token: "ghp_your_github_token"
    }
  ]
)

For private repositories, the resource’s authorization_token must have access to the repository. This is the same personal access token flow used for any repository mount; see Accessing GitHub. Discovered skills follow the checked-out state of the repository: the checkout branch or commit when the resource sets one, otherwise the repository’s default branch. The scan runs once, when the session starts. Commits pushed mid-session are not picked up; to load updated skills, start a new session. Repository skills work alongside skills attached through the agent’s skills array. If a repository skill shares a name with an attached skill, or with a skill from another mounted repository, both are available; each is announced with its own path.

Next steps

Cloud environment setup

Customize cloud sandboxes for your sessions.

Using Agent Skills with the API

Learn how to use Agent Skills to extend agent capabilities through the API.

Files API

Upload files once and reference them across API requests.

Get started with Agent Skills in the API

Learn how to use Agent Skills to create documents with the OMA API in under 10 minutes.

First steps

Define your agent

Configure agent environment

Delegate work to your agent

Manage agent context

Advanced orchestration

Reference

Create a custom skill

Attach skills to an agent

Load skills from a GitHub repository

Next steps

Cloud environment setup

Using Agent Skills with the API

Files API

Get started with Agent Skills in the API

​Create a custom skill

​Attach skills to an agent

​Load skills from a GitHub repository

​Next steps

Cloud environment setup

Using Agent Skills with the API

Files API

Get started with Agent Skills in the API

Create a custom skill

Attach skills to an agent

Load skills from a GitHub repository

Next steps