Agent Skills는 지침, 스크립트 및 리소스로 구성된 폴더를 통해 Claude의 기능을 확장합니다. 이 가이드는 Claude API에서 사전 구축된 Skills와 커스텀 Skills를 모두 사용하는 방법을 보여줍니다.
요청/응답 스키마와 모든 매개변수를 포함한 전체 API 레퍼런스는 다음을 참조하세요:
제로 데이터 보존(ZDR)이 이 기능에 적용되는 방식은 API 및 데이터 보존을 참조하세요.
첫 번째 Skill 만들기
Skills 작성을 위한 모범 사례
Agent Skills의 아키텍처와 실제 적용 사례에 대한 자세한 내용은 엔지니어링 블로그 게시물 Equipping agents for the real world with Agent Skills를 읽어보세요.
Skills는 코드 실행 도구를 통해 Messages API와 통합됩니다. Anthropic이 관리하는 사전 구축된 Skills를 사용하든 직접 업로드한 커스텀 Skills를 사용하든, 통합 형태는 동일합니다. 둘 다 코드 실행이 필요하며 동일한 container 구조를 사용합니다.
Skills는 출처에 관계없이 Messages API에서 동일하게 통합됩니다. container 매개변수에 skill_id, type 및 선택적 version으로 Skills를 지정하면 코드 실행 환경에서 실행됩니다.
두 가지 출처의 Skills를 사용할 수 있습니다:
| 항목 | Anthropic Skills | 커스텀 Skills |
|---|---|---|
| Type 값 | anthropic | custom |
| Skill ID | 짧은 이름: pptx, xlsx, docx, pdf | 생성된 값: skill_01AbCdEfGhIjKlMnOpQrStUv |
| 버전 형식 | 날짜 기반: 20251013 또는 latest | 에포크 타임스탬프: 1759178010641129 또는 latest |
| 관리 | Anthropic이 사전 구축하고 유지 관리 | Skills API를 통해 업로드 및 관리 |
| 가용성 | 모든 사용자가 사용 가능 | 워크스페이스 전용 |
두 가지 Skill 출처 모두 List Skills 엔드포인트에서 반환됩니다(source 매개변수를 사용하여 필터링). 통합 형태와 실행 환경은 동일합니다. 유일한 차이점은 Skills의 출처와 관리 방식입니다.
Skills를 사용하려면 다음이 필요합니다:
code-execution-2025-08-25 - 코드 실행 활성화(Skills에 필수)skills-2025-10-02 - Skills API 활성화files-api-2025-04-14 - 컨테이너로/컨테이너에서 파일 업로드/다운로드용Skills는 Messages API의 container 매개변수를 사용하여 지정합니다. 각 요청에 최대 8개의 Skills를 포함할 수 있습니다.
구조는 Anthropic Skills와 커스텀 Skills 모두 동일합니다. 필수 항목인 type과 skill_id를 지정하고, 특정 버전에 고정하려면 선택적으로 version을 포함하세요:
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
},
messages=[
{"role": "user", "content": "Create a presentation about renewable energy"}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)Skills가 문서(Excel, PowerPoint, PDF, Word)를 생성하면 응답에 file_id 속성이 반환됩니다. 이러한 파일을 다운로드하려면 Files API를 사용해야 합니다.
작동 방식:
file_id가 포함됩니다.예시: Excel 파일 생성 및 다운로드
client = anthropic.Anthropic()
# 1단계: Skill을 사용하여 파일 생성
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Create an Excel file with a simple budget spreadsheet",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# 2단계: 응답에서 파일 ID 추출
def extract_file_ids(response):
file_ids = []
for item in response.content:
if item.type == "bash_code_execution_tool_result":
content_item = item.content
if content_item.type == "bash_code_execution_result":
# 각 콘텐츠 항목은 file_id를 포함하는 bash_code_execution_output 블록입니다
for file in content_item.content:
file_ids.append(file.file_id)
return file_ids
# 3단계: Files API를 사용하여 파일 다운로드
for file_id in extract_file_ids(response):
file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
file_content = client.beta.files.download(file_id=file_id)
# 4단계: 디스크에 저장
file_content.write_to_file(file_metadata.filename)
print(f"Downloaded: {file_metadata.filename}")추가 Files API 작업:
client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# 파일 메타데이터 가져오기
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")
# 모든 파일 나열
for file in client.beta.files.list():
print(f"{file.filename} - {file.created_at}")
# 파일 삭제
client.beta.files.delete(file_id=file_id)Files API에 대한 자세한 내용은 Files API 문서를 참조하세요.
컨테이너 ID를 지정하여 여러 메시지에서 동일한 컨테이너를 재사용할 수 있습니다:
client = anthropic.Anthropic()
# 첫 번째 요청이 컨테이너를 생성합니다
response1 = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[
{"role": "user", "content": "Create a sample sales dataset and analyze it"}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# 동일한 컨테이너로 대화를 계속합니다
messages = [
{"role": "user", "content": "Create a sample sales dataset and analyze it"},
{
# 어시스턴트의 텍스트를 이어서 전달합니다. container.id가 실행 상태를 유지합니다
"role": "assistant",
"content": "\n".join(
block.text for block in response1.content if block.type == "text"
),
},
{"role": "user", "content": "What was the total revenue?"},
]
response2 = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"id": response1.container.id, # Reuse container
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}],
},
messages=messages,
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)Skills는 여러 턴이 필요한 작업을 수행할 수 있습니다. pause_turn 중지 이유를 처리하세요:
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
}
]
},
messages=messages,
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# 긴 작업에 대한 pause_turn 처리
for _ in range(max_retries):
if response.stop_reason != "pause_turn":
break
messages.append({"role": "assistant", "content": response.content})
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"id": response.container.id,
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
}
],
},
messages=messages,
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)응답에는 API가 장시간 실행되는 Skill 작업을 일시 중지했음을 나타내는 pause_turn 중지 이유가 포함될 수 있습니다. 후속 요청에서 응답을 그대로 다시 제공하여 Claude가 턴을 계속하도록 하거나, 대화를 중단하고 추가 지침을 제공하려는 경우 콘텐츠를 수정할 수 있습니다.
복잡한 워크플로를 처리하기 위해 단일 요청에서 여러 Skills를 결합할 수 있습니다:
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "anthropic", "skill_id": "pptx", "version": "latest"},
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
},
]
},
messages=[
{"role": "user", "content": "Analyze sales data and create a presentation"}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)Skill 번들은 name과 description YAML 프런트매터가 포함된 SKILL.md 파일을 최상위에 두고, 지원 스크립트나 리소스를 함께 담은 디렉터리입니다. 작성 방법은 API에서 Agent Skills 시작하기를 참조하고, 전체 제약 조건은 예시 다음에 나오는 요구 사항 목록을 확인하세요.
커스텀 Skill을 업로드하여 워크스페이스에서 사용할 수 있도록 하세요. zip 아카이브 또는 개별 파일 객체를 업로드할 수 있으며, Python SDK는 추가로 디렉터리 경로를 받는 files_from_dir 헬퍼를 제공합니다.
파일은 첨부한 파일 이름으로 식별됩니다. 파일별 업로드는 경로에 공통 최상위 디렉터리를 유지해야 하며(cURL 예시의 ;filename= 접미사와 SDK 예시의 파일 이름 인수), zip 아카이브는 skill 디렉터리를 단일 최상위 항목으로 포함해야 합니다.
ant beta:skills create \
--file example_skill.zip \
--beta skills-2025-10-02
# 파일별 업로드에는 경로가 포함된 파일 이름이 필요하지만, 현재 CLI에서는
# 이를 설정할 수 없습니다. 대신 zip 아카이브를 업로드하세요.요구 사항:
name과 일치해야 합니다(대소문자 및 밑줄 구분 없음: Financial_Skill은 financial-skill과 일치)display_title은 선택 사항입니다. 생략하면 SKILL.md의 name에서 파생되며, 명시적으로 지정한 값은 워크스페이스의 커스텀 skills 중에서 고유해야 합니다name: 최대 64자, 소문자/숫자/하이픈만 허용, XML 태그 불가, 예약어("anthropic", "claude") 불가description: 최대 1024자, 비어 있지 않아야 함, XML 태그 불가전체 요청/응답 스키마는 Create Skill API 레퍼런스를 참조하세요.
Anthropic 사전 구축 Skills와 커스텀 Skills를 포함하여 워크스페이스에서 사용 가능한 모든 Skills를 조회합니다. source 매개변수를 사용하여 skill 유형별로 필터링하세요:
# 모든 Skills 나열
ant beta:skills list
# 커스텀 Skills만 나열
ant beta:skills list --source custom페이지네이션 및 필터링 옵션은 List Skills API 레퍼런스를 참조하세요.
특정 Skill에 대한 세부 정보를 가져옵니다:
ant beta:skills retrieve \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUvSkill을 삭제하려면 먼저 모든 버전을 삭제해야 합니다:
# 1단계: 버전을 나열한 다음 각 버전을 삭제합니다
ant beta:skills:versions list \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--transform version --raw-output
# 목록에서 반환된 각 버전 ID에 대해 반복합니다
ant beta:skills:versions delete \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--version 1759178010641129 >/dev/null
# 2단계: Skill을 삭제합니다
ant beta:skills delete \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null기존 버전이 있는 Skill을 삭제하려고 하면 400 오류가 반환됩니다.
Skills는 업데이트를 안전하게 관리하기 위한 버전 관리를 지원합니다:
Anthropic Skills:
20251013커스텀 Skills:
1759178010641129"latest"를 사용하세요# 새 버전 생성
VERSION_NUMBER=$(ant beta:skills:versions create \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--file updated_skill.zip \
--transform version --raw-output)
# 특정 버전 사용
ant beta:messages create \
--beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
skills:
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: $VERSION_NUMBER
messages:
- role: user
content: Use updated Skill
tools:
- type: code_execution_20250825
name: code_execution
YAML
# 최신 버전 사용
ant beta:messages create \
--beta code-execution-2025-08-25,skills-2025-10-02 <<'YAML'
model: claude-opus-5
max_tokens: 4096
container:
skills:
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
- role: user
content: Use latest Skill version
tools:
- type: code_execution_20250825
name: code_execution
YAML자세한 내용은 Create Skill Version API 레퍼런스를 참조하세요.
컨테이너에 Skills를 지정하면:
/skills/{directory}/에 복사됩니다.점진적 공개(progressive disclosure) 아키텍처는 효율적인 컨텍스트 사용을 보장합니다. Claude는 필요할 때만 전체 Skill 지침을 로드합니다.
브랜드 및 커뮤니케이션
프로젝트 관리
비즈니스 운영
콘텐츠 제작
데이터 분석
개발 및 자동화
Excel과 커스텀 DCF 분석 Skills를 결합합니다:
from anthropic.lib import files_from_dir
client = anthropic.Anthropic()
# 커스텀 DCF 분석 Skill 생성
dcf_skill = client.beta.skills.create(
files=files_from_dir("/path/to/dcf_skill"),
)
# Excel과 함께 사용하여 재무 모델 생성
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "custom", "skill_id": dcf_skill.id, "version": "latest"},
]
},
messages=[
{
"role": "user",
"content": "Build a DCF valuation model for a SaaS company",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)name: 최대 64자, 소문자/숫자/하이픈만 허용, XML 태그 불가, 예약어("anthropic", "claude") 불가description: 최대 1024자, 비어 있지 않아야 함, XML 태그 불가Skills는 다음과 같은 제한이 있는 코드 실행 컨테이너에서 실행됩니다:
사용 가능한 패키지는 코드 실행 도구를 참조하세요.
작업에 여러 문서 유형이나 도메인이 포함될 때 Skills를 결합하세요:
좋은 사용 사례:
피해야 할 사항:
프로덕션 환경:
# 안정성을 위해 특정 버전으로 고정
container = {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "1759178010641129", # Specific version
}
]
}개발 환경:
# 활발한 개발에는 latest를 사용하세요
container = {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest", # Always get newest
}
]
}프롬프트 캐싱을 사용할 때, 컨테이너의 Skills 목록을 변경하면 캐시가 무효화된다는 점에 유의하세요:
client = anthropic.Anthropic()
# 첫 번째 요청이 캐시를 생성합니다
response1 = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=[
"code-execution-2025-08-25",
"skills-2025-10-02",
],
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[{"role": "user", "content": "Analyze sales data"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Skills 추가/제거는 캐시를 무효화합니다
response2 = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=[
"code-execution-2025-08-25",
"skills-2025-10-02",
],
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{
"type": "anthropic",
"skill_id": "pptx",
"version": "latest",
}, # Cache miss
]
},
messages=[{"role": "user", "content": "Create a presentation"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)최상의 캐싱 성능을 위해 요청 간에 Skills 목록을 일관되게 유지하세요.
Skill 관련 오류를 적절하게 처리하세요:
client = anthropic.Anthropic()
try:
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
}
]
},
messages=[{"role": "user", "content": "Process data"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
except anthropic.BadRequestError as e:
if "skill" in str(e):
print(f"Skill error: {e}")
# 스킬별 오류 처리
else:
raiseAgent Skills는 ZDR 계약의 적용을 받지 않습니다. Skill 정의 및 실행 데이터는 Anthropic의 표준 데이터 보존 정책에 따라 보존됩니다.
모든 기능에 대한 ZDR 적용 여부는 API 및 데이터 보존을 참조하세요.
모든 엔드포인트가 포함된 전체 API 레퍼런스
Claude가 성공적으로 발견하고 사용할 수 있는 효과적인 Skills를 작성하는 방법 알아보기
샌드박스 컨테이너에서 Python 및 bash 코드를 실행하여 데이터를 분석하고, 파일을 생성하고, 솔루션을 반복적으로 개선하세요
Was this page helpful?