技能 - Open Managed Agents

“技能”（Skill）是可复用的、基于文件系统的资源，为您的智能体提供特定领域的专业知识：工作流、上下文和最佳实践，将通用智能体转变为专家。您添加的每个技能都会对会话的上下文窗口产生适度的开销，因为它会添加帮助模型使用该技能的指令和元数据。请参阅智能体技能概述了解更多信息。技能通过两种方式提供给您的智能体：通过智能体的 skills 数组附加，或从挂载到会话的 GitHub 仓库加载。附加的技能分为两种类型。所有技能的工作方式相同：当技能与任务相关时，您的智能体会自动调用它们。

**OMA 预构建技能：**常见的文档任务，如 PowerPoint、Excel、Word 和 PDF 处理（pptx、xlsx、docx、pdf）。
**自定义技能：**您编写并上传到工作区的技能。

要了解如何编写自定义技能，请参阅智能体技能和技能编写最佳实践。要将自定义技能上传到您的工作区，请参阅创建自定义技能。

托管智能体 API 请求需要 managed-agents-2026-04-01 Beta 请求头，但记忆存储端点除外，它们使用 agent-memory-2026-07-22。SDK 会自动设置正确的 Beta 请求头。请参阅Beta 请求头。

创建自定义技能

自定义技能是一个包含 SKILL.md 文件及任何支持文件的目录，以 zip 压缩包或单个文件的形式上传到您的工作区。创建技能后会返回 skill_* ID，您在将其附加到智能体时需要引用该 ID。OMA 预构建技能已在每个工作区中可用，无需执行此步骤。如果只使用预构建技能，请跳至将技能附加到智能体。当您使用 cURL 直接调用技能 API 时，请显式传递 anthropic-beta: skills-2025-10-02 请求头。CLI 和 SDK 会自动发送该请求头。这些示例省略了可选的 display_title 字段，因此技能的标题将从 SKILL.md 中派生。显式传递的 display_title 在您工作区的自定义技能中必须是唯一的。

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}"

要列出、检索、删除自定义技能及管理其版本，请参阅管理自定义技能。有关完整的请求和响应架构，请参阅创建技能 API 参考。技能包直接上传到技能 API，而不是通过文件 API。

将技能附加到智能体

在创建智能体时附加技能。每个会话最多支持 500 个技能，按会话中所有智能体去重后的集合计数（请参阅多智能体编排）。

挂载更多技能会增加会话沙箱的启动时间。请仅附加每个智能体完成其任务所需的技能。

skills 数组中的每个条目使用以下字段：

字段	描述
`type`	预构建技能使用 `anthropic`，工作区编写的技能使用 `custom`。
`skill_id`	技能标识符。对于 OMA 技能，使用短名称（例如 `xlsx`）。对于自定义技能，使用创建时返回的 `skill_*` ID（请参阅创建自定义技能）。
`version`	固定到特定版本或使用 `latest`。可选。省略时默认为 `latest`。适用于 OMA 技能和自定义技能。

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: "claude-opus-5",
    },
    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"}
  ]
)

从 GitHub 仓库加载技能

技能也可以存放在您的代码库中。当会话通过 github_repository 资源挂载仓库时，会在会话启动时扫描仓库根目录下的 .claude/skills 目录，在那里找到的每个技能都会对智能体可用。无需上传，也无需在智能体的 skills 数组中添加条目。智能体可以看到每个已发现技能的名称、描述及其在沙箱中的路径，并在任务匹配时读取该技能的 SKILL.md，包括该技能附带的任何脚本和资源。技能发现依赖于智能体工具集中的 read 工具，该工具默认启用；禁用了 read 的智能体不会加载仓库技能。

仓库技能是智能体指令，因此挂载的仓库属于您智能体信任边界的一部分。任何可以向仓库提交代码的人（已合并的外部拉取请求、被入侵的依赖项、贡献者）都可以添加或更改技能，平台会在会话启动时加载它而无需审核步骤，并且 bash 和 web_fetch 等会话工具会赋予这些指令实际的影响范围。请仅挂载您信任的仓库，并在挂载接受外部贡献的仓库之前审查 .claude/skills。

仓库技能发现在云沙箱中运行。自托管沙箱不支持 GitHub 仓库资源。

技能发现会在仓库根目录下精确匹配 .claude/skills/<skill-name>/SKILL.md 路径（即一级子目录深度）来查找技能：

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

不符合此布局的位置在会话启动时不会被发现：

.claude/skills/SKILL.md：没有技能目录包裹的 SKILL.md
.claude/skills/tools/code-review/SKILL.md：嵌套深度超过一级目录
skills/code-review/SKILL.md：位于 .claude 之外的 skills 目录

位于仓库其他位置的 .claude/skills 目录（例如在某个包的子目录内）不会在会话启动时被公告；当智能体读取该子树下的文件时，这些技能仍可能被发现。仓库技能使用与您上传的自定义技能相同的 SKILL.md 格式。有关格式和编写指南，请参阅智能体技能和技能编写最佳实践。要从仓库加载技能，请创建一个挂载该仓库的会话。这与访问 GitHub 中展示的请求相同；mount_path 是可选的，默认为 /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"
    }
  ]
)

对于私有仓库，资源的 authorization_token 必须具有访问该仓库的权限。这与任何仓库挂载所使用的个人访问令牌流程相同；请参阅访问 GitHub。已发现的技能遵循仓库的检出状态：如果资源设置了 checkout 分支或提交，则使用该分支或提交，否则使用仓库的默认分支。扫描仅在会话启动时运行一次。会话期间推送的提交不会被获取；要加载更新后的技能，请启动新会话。仓库技能与通过智能体 skills 数组附加的技能协同工作。如果仓库技能与已附加的技能或来自另一个已挂载仓库的技能同名，两者都可用；每个技能都会以其各自的路径进行公告。

后续步骤

云环境设置

为您的会话自定义云沙箱。

通过 API 使用智能体技能

了解如何通过 API 使用智能体技能来扩展智能体能力。

文件 API

一次上传文件，即可在多个 API 请求中引用。

在 API 中开始使用智能体技能

了解如何在 10 分钟内使用智能体技能通过 OMA API 创建文档。

第一步

定义智能体

配置智能体环境

将工作委派给智能体

管理智能体上下文

高级编排

参考

技能

创建自定义技能

将技能附加到智能体

从 GitHub 仓库加载技能

后续步骤

云环境设置

通过 API 使用智能体技能

文件 API

在 API 中开始使用智能体技能

​创建自定义技能

​将技能附加到智能体

​从 GitHub 仓库加载技能

​后续步骤

云环境设置

通过 API 使用智能体技能

文件 API

在 API 中开始使用智能体技能

创建自定义技能

将技能附加到智能体

从 GitHub 仓库加载技能

后续步骤