“Skills”（技能）是可复用的、基于文件系统的资源，可为您的智能体提供特定领域的专业知识：工作流、上下文和最佳实践，将通用智能体转变为专家。您添加的每个技能都会对会话的 “context window”（上下文窗口）产生少量开销，添加有助于模型使用该技能的指令和元数据。请在 Agent Skills 概述中了解更多信息。

技能可以通过两种方式提供给您的智能体：通过智能体的 skills (csharp, go: Skills) 数组附加，或者从挂载到会话上的 GitHub 仓库加载。附加的技能分为两种类型。所有技能的工作方式相同：当技能与任务相关时，您的智能体会自动使用它们。

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

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

创建自定义技能

自定义技能是一个包含 SKILL.md 文件以及任何支持文件的目录，以 zip 压缩包或单独文件的形式上传到您的工作区。创建技能会返回 skill_* ID，您在将其附加到智能体时会引用该 ID。Anthropic 预构建技能已在每个工作区中可用，无需执行此步骤。如果只使用预构建技能，请跳至将技能附加到智能体。

这些示例省略了可选的 display_name (java, php: displayName; csharp, go: DisplayName) 字段，因此技能的显示名称派生自 SKILL.md 中的 name 字段。显式指定的 display_name (java, php: displayName; csharp, go: DisplayName) 最多可包含 255 个字符，且无需在工作区内唯一。

cURL

curl -X POST "https://api.anthropic.com/v1/skills" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "files[]=@example_skill.zip"

CLI

ant apply skills/pr-summary

skills/pr-summary/SKILL.md

---
name: pr-summary
description: Summarize a pull request's changes and risks in the team's review format.
---

# PR summary

List what changed, why, and anything a reviewer should look at closely, in three short sections.

ant apply 会上传 skills/pr-summary 目录，打印新技能的 ID，并将其记录在 claude-lock.json 中。请提交 claude-lock.json，这样下一次运行 ant apply 时会将您的修改作为新版本上传，而不是创建第二个技能。

Python

import anthropic
from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

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

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

TypeScript

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.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_id}`);

C#

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

AnthropicClient client = new();

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

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

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

Go

package main

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

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

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

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

	skill, err := client.Skills.New(context.TODO(), anthropic.SkillNewParams{
		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.LatestVersionID)
}

Java

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.MultipartField;
import com.anthropic.models.skills.Skill;
import com.anthropic.models.skills.SkillCreateParams;
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();

    Skill skill = client.skills().create(params);

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

PHP

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

$client = new Client();

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

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

Ruby

require "anthropic"

client = Anthropic::Client.new

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

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

要列出、检索、删除自定义技能以及管理其版本，请参阅管理自定义技能。有关完整的请求和响应模式，请参阅 Create Skill API 参考。技能包直接上传到 Skills API，而不是通过 Files API 上传。

将技能附加到智能体

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

注意

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

skills (csharp, go: Skills) 数组中的每个条目使用以下字段：

字段 描述
type (csharp, go: Type) 预构建技能使用 anthropic，工作区编写的技能使用 custom。
skill_id (java: skillId; php: skillID; csharp, go: SkillID) 技能标识符。对于 Anthropic 技能，使用短名称（例如 xlsx）。对于自定义技能，使用创建时返回的 skill_* ID（请参阅创建自定义技能）。
version (csharp, go: Version) 固定到特定版本或使用 latest。可选。省略时默认为 latest。适用于 Anthropic 技能和自定义技能。

cURL

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

CLI

ant apply agent.md

agent.md

---
name: Financial Analyst
model: claude-opus-5-5
skills:
  - type: anthropic
    skill_id: xlsx
  - type: custom
    skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
    version: latest
---

You are a financial analysis agent.

Python

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

TypeScript

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

C#

using Anthropic.Models.Beta.Agents;

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

Go

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

Java

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

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

PHP

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

Ruby

agent = client.beta.agents.create(
  name: "Financial Analyst",
  model: "claude-opus-5-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 (csharp, go: 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 格式。有关格式和编写指南，请参阅 Agent Skills 和技能编写最佳实践。

要从仓库加载技能，请创建一个挂载该仓库的会话。这与访问 GitHub 中展示的请求相同；mount_path (java, php: mountPath; csharp, go: MountPath) 是可选的，默认为 /workspace/<repo-name>：

cURL

curl -fsS https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<JSON
{
  "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

CLI

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

Python

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",
        },
    ],
)

TypeScript

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"
    }
  ]
});

C#

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

Go

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{
				URL:                "https://github.com/org/repo",
				MountPath:          anthropic.String("/workspace/repo"),
				AuthorizationToken: "ghp_your_github_token",
			},
		},
	},
})
if err != nil {
	panic(err)
}

Java

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

PHP

$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',
        ],
    ],
);

Ruby

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 (java, php: authorizationToken; csharp, go: AuthorizationToken) 必须具有该仓库的访问权限。这与任何仓库挂载所使用的个人访问令牌流程相同；请参阅访问 GitHub。

已发现的技能遵循仓库的检出状态：如果资源设置了 checkout (csharp, go: Checkout) 分支或提交，则使用该分支或提交，否则使用仓库的默认分支。扫描仅在会话启动时运行一次。会话期间推送的提交不会被获取；要加载更新后的技能，请启动新会话。

仓库技能可与通过智能体的 skills (csharp, go: Skills) 数组附加的技能一起使用。如果某个仓库技能与已附加的技能或来自另一个已挂载仓库的技能同名，两者都可用；每个技能都会以其各自的路径公布。

后续步骤