스킬
스킬 (Skills)
스킬은 에이전트에게 도메인 특화 전문성을 주는 재사용 가능한 파일시스템 기반 리소스예요. 워크플로, 컨텍스트, 베스트 프랙티스가 담겨 있어 범용 에이전트를 전문가로 바꿔줘요. 추가하는 각 스킬은 세션 컨텍스트 창에 약간의 비용을 더하며, 모델이 스킬을 쓰도록 돕는 지침과 메타데이터를 추가해요. 자세한 내용은 Agent Skills 개요에서 확인할 수 있어요.
출처: 문서
본문
스킬은 에이전트에게 도메인 특화 전문성을 주는 재사용 가능한 파일시스템 기반 리소스예요: 워크플로, 컨텍스트, 베스트 프랙티스가 범용 에이전트를 전문가로 바꿔줘요. 추가하는 각 스킬은 세션 컨텍스트 창에 약간의 비용을 더하고, 모델이 스킬을 쓰도록 돕는 지침과 메타데이터를 추가해요. Agent Skills 개요에서 더 자세히 알아보세요.
스킬은 두 가지 방법으로 에이전트에 도달해요: 에이전트의 skills 배열로 붙이거나, 세션에 마운트된 GitHub 저장소에서 불러오는 방법이에요. 붙이는 스킬은 두 가지 유형이 있어요. 모든 스킬은 같은 방식으로 작동해요: 작업과 관련될 때 에이전트가 자동으로 호출하죠.
- Pre-built Anthropic 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.
사용자 정의 스킬을 작성하는 방법은 Agent Skills와 Skill authoring best practices를 참고하세요. 워크스페이스에 사용자 정의 스킬을 업로드하려면 Create a custom skill을 참고하세요.
Create a custom skill
사용자 정의 스킬은 SKILL.md 파일과 보조 파일을 담은 디렉터리로, zip 아카이브나 개별 파일로 워크스페이스에 업로드해요. 스킬을 만들면 에이전트에 붙일 때 참조하는 skill_* ID가 반환돼요. Anthropic 미리 빌드 스킬은 모든 워크스페이스에 이미 있고 이 단계가 필요 없어요. 미리 빌드 스킬만 쓰려면 Attach skills to an agent로 건너뛰세요.
이 예시들은 선택적 display_name 필드를 생략하므로 스킬의 표시 이름은 SKILL.md의 name 필드에서 파생돼요. 명시적 display_name은 최대 255자이며 워크스페이스 내에서 고유할 필요가 없어요.
<File filename="skills/pr-summary/SKILL.md">
```markdown
---
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.
```
</File>
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}")
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}`);
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}");
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.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)
}
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());
}
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";
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}"
사용자 정의 스킬을 나열·조회·삭제·버전 관리하려면 Managing custom skills을 참고하세요. 전체 요청·응답 스키마는 Create Skill API reference를 참고하세요. 스킬 번들은 Files API가 아니라 Skills API에 직접 업로드돼요.
Attach skills to an agent
에이전트를 만들 때 스킬을 붙이세요. 각 세션은 최대 500개 스킬을 지원하며, 세션의 모든 에이전트에 걸쳐 중복 제거된 집합으로 셉니다(Multiagent orchestration 참고).
skills 배열의 각 항목은 다음 필드를 사용해요:
| Field | Description |
|---|---|
type |
Either anthropic for pre-built skills or custom for workspace-authored skills. |
skill_id |
The skill identifier. For Anthropic 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 Anthropic and custom skills. |
<File filename="agent.md">
```markdown
---
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.
```
</File>
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",
},
],
)
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"
}
]
});
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 { 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_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_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-5',
system: 'You are a financial analysis agent.',
skills: [
['type' => 'anthropic', 'skillID' => 'xlsx'],
['type' => 'custom', 'skillID' => 'skill_01AbCdEfGhIjKlMnOpQrStUv', 'version' => 'latest'],
],
);
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"}
]
)
Load skills from a GitHub repository
스킬은 코드베이스에 있을 수도 있어요. 세션이 github_repository 리소스를 통해 저장소를 마운트하면, 세션 시작 시 저장소 루트의 .claude/skills 디렉터리가 스캔되고 거기 발견된 각 스킬이 에이전트에게 제공돼요. 업로드도, 에이전트의 skills 배열 항목도 필요 없어요. 에이전트는 각 발견된 스킬의 이름·설명·경로를 샌드박스에서 보고, 작업이 일치하면 스킬이 딸려오는 스크립트와 리소스를 포함해 SKILL.md를 읽어요. 발견은 에이전트 도구세트의 read 도구에 의존하며, 이는 기본 활성화돼요. read가 비활성화된 에이전트는 저장소 스킬을 불러오지 않아요.
발견은 정확히 .claude/skills/<skill-name>/SKILL.md, 저장소 루트에서 한 디렉터리 깊이에서 찾아요:
-
your-repo/-
.claude/-
skills/-
code-review/SKILL.md
-
release-process/SKILL.mdscripts/run_checks.sh
-
-
-
src/
-
이 레이아웃과 일치하지 않는 위치는 세션 시작 시 발견되지 않아요:
.claude/skills/SKILL.md: aSKILL.mdwith no skill directory around it.claude/skills/tools/code-review/SKILL.md: nested more than one directory level deepskills/code-review/SKILL.md: askillsdirectory outside.claude
패키지 하위 디렉터리 안처럼 저장소의 다른 곳에 있는 .claude/skills 디렉터리는 세션 시작 시 알려지지 않지만, 에이전트가 그 하위 트리의 파일을 읽으면 표면화될 수 있어요.
저장소 스킬은 업로드하는 사용자 정의 스킬과 같은 SKILL.md 형식을 사용해요. 형식과 작성 지침은 Agent Skills와 Skill authoring best practices를 참고하세요.
저장소에서 스킬을 불러오려면 그것을 마운트하는 세션을 만드세요. 이것은 Accessing GitHub에 표시된 것과 같은 요청이며, mount_path는 선택 사항이고 기본은 /workspace/<repo-name>이에요:
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이 저장소에 대한 접근 권한이 있어야 해요. 이것은 어떤 저장소 마운트든 같은 개인 접근 토큰 흐름이에요. Accessing GitHub을 참고하세요.
발견된 스킬은 저장소의 체크아웃된 상태를 따릅니다: 리소스가 설정하면 checkout 브랜치·커밋을, 아니면 저장소의 기본 브랜치를 사용해요. 스캔은 세션 시작 시 한 번 실행돼요. 세션 중에 푸시된 커밋은 반영되지 않아요. 업데이트된 스킬을 불러오려면 새 세션을 시작하세요.
저장소 스킬은 에이전트의 skills 배열로 붙인 스킬과 함께 작동해요. 저장소 스킬이 붙인 스킬이나 다른 마운트된 저장소의 스킬과 이름을 공유하면 둘 다 제공되며, 각각 자체 경로로 알려져요.
Next steps
더 알아보기 (Learn more)
- Define your agent — 에이전트에 스킬 붙이기
- Accessing GitHub — 저장소 마운트하고 스킬 불러오기
- Agent Skills — 스킬 작성과 사용법