Agent Skills는 조직화된 지침, 스크립트 및 리소스 폴더를 통해 Claude의 기능을 확장합니다. 이 가이드는 Claude API와 함께 사전 구축된 Skills과 사용자 정의 Skills을 모두 사용하는 방법을 보여줍니다.
요청/응답 스키마 및 모든 매개변수를 포함한 완전한 API 참조는 다음을 참조하세요:
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 | Epoch 타임스탬프: 1759178010641129 또는 latest |
| 관리 | Anthropic에서 사전 구축 및 유지 관리 |
두 가지 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 모두에 대해 동일합니다. 필수 type 및 skill_id를 지정하고 선택적으로 version을 포함하여 특정 버전으로 고정합니다:
Skills이 문서(Excel, PowerPoint, PDF, Word)를 만들 때 응답에서 file_id 속성을 반환합니다. Files API를 사용하여 이러한 파일을 다운로드해야 합니다.
작동 방식:
file_id 포함예: Excel 파일 만들기 및 다운로드하기
추가 Files API 작업:
Files API에 대한 완전한 세부 정보는 Files API 문서를 참조하세요.
컨테이너 ID를 지정하여 여러 메시지에서 동일한 컨테이너를 재사용합니다:
Skills은 여러 턴이 필요한 작업을 수행할 수 있습니다. pause_turn 중지 이유를 처리합니다:
응답에 pause_turn 중지 이유가 포함될 수 있으며, 이는 API가 장기 실행 Skill 작업을 일시 중지했음을 나타냅니다. 응답을 그대로 후속 요청에 제공하여 Claude가 턴을 계속하도록 할 수 있으며, 또는 대화를 중단하고 추가 지침을 제공하려면 콘텐츠를 수정할 수 있습니다.
복잡한 워크플로우를 처리하기 위해 단일 요청에서 여러 Skills을 결합합니다:
사용자 정의 Skill을 업로드하여 워크스페이스에서 사용 가능하게 합니다. 디렉터리 경로 또는 개별 파일 객체를 사용하여 업로드할 수 있습니다.
요구 사항:
name: 최대 64자, 소문자/숫자/하이픈만 가능, XML 태그 없음, 예약어 없음 ("anthropic", "claude")description: 최대 1024자, 비어있지 않음, XML 태그 없음완전한 요청/응답 스키마는 Create Skill API 참조를 참조하세요.
워크스페이스에서 사용 가능한 모든 Skills을 검색합니다. 여기에는 Anthropic 사전 구축 Skills과 사용자 정의 Skills이 포함됩니다. source 매개변수를 사용하여 Skill 유형별로 필터링합니다:
페이지 매김 및 필터링 옵션은 List Skills API 참조를 참조하세요.
특정 Skill에 대한 세부 정보를 가져옵니다:
Skill을 삭제하려면 먼저 모든 버전을 삭제해야 합니다:
기존 버전이 있는 Skill을 삭제하려고 하면 400 오류가 반환됩니다.
Skills은 업데이트를 안전하게 관리하기 위해 버전 관리를 지원합니다:
Anthropic 관리 Skills:
20251013사용자 정의 Skills:
1759178010641129"latest"를 사용하여 항상 최신 버전 가져오기완전한 세부 정보는 Create Skill Version API 참조를 참조하세요.
컨테이너에서 Skills을 지정할 때:
/skills/{directory}/의 컨테이너에 복사됩니다점진적 공개 아키텍처는 효율적인 컨텍스트 사용을 보장합니다. Claude는 필요할 때만 전체 Skill 지침을 로드합니다.
브랜드 및 커뮤니케이션
프로젝트 관리
비즈니스 운영
콘텐츠 생성
데이터 분석
개발 및 자동화
Excel 및 사용자 정의 DCF 분석 Skills을 결합합니다:
name: 최대 64자, 소문자/숫자/하이픈만 가능, XML 태그 없음, 예약어 없음description: 최대 1024자, 비어있지 않음, XML 태그 없음Skills은 다음 제한 사항이 있는 코드 실행 컨테이너에서 실행됩니다:
사용 가능한 패키지는 코드 실행 도구 문서를 참조하세요.
작업에 여러 문서 유형 또는 도메인이 포함될 때 Skills을 결합합니다:
좋은 사용 사례:
피해야 할 사항:
프로덕션의 경우:
# 안정성을 위해 특정 버전으로 고정
container={
"skills": [{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "1759178010641129" # 특정 버전
}]
}개발의 경우:
# 활성 개발을 위해 최신 사용
container={
"skills": [{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest" # 항상 최신 획득
}]
}프롬프트 캐싱을 사용할 때 컨테이너의 Skills 목록을 변경하면 캐시가 손상됩니다:
최적의 캐싱 성능을 위해 요청 전체에서 Skills 목록을 일관되게 유지합니다.
Skill 관련 오류를 적절하게 처리합니다:
| Skills API를 통해 업로드 및 관리 |
| 가용성 | 모든 사용자가 사용 가능 | 워크스페이스에 비공개 |
import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
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"
}]
)import anthropic
client = anthropic.Anthropic()
# Step 1: Skill을 사용하여 파일 만들기
response = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
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"}]
)
# Step 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':
for file in content_item.content:
if hasattr(file, 'file_id'):
file_ids.append(file.file_id)
return file_ids
# Step 3: Files API를 사용하여 파일 다운로드
for file_id in extract_file_ids(response):
file_metadata = client.beta.files.retrieve_metadata(
file_id=file_id,
betas=["files-api-2025-04-14"]
)
file_content = client.beta.files.download(
file_id=file_id,
betas=["files-api-2025-04-14"]
)
# Step 4: 디스크에 저장
file_content.write_to_file(file_metadata.filename)
print(f"Downloaded: {file_metadata.filename}")# 파일 메타데이터 가져오기
file_info = client.beta.files.retrieve_metadata(
file_id=file_id,
betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")
# 모든 파일 나열
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
print(f"{file.filename} - {file.created_at}")
# 파일 삭제
client.beta.files.delete(
file_id=file_id,
betas=["files-api-2025-04-14"]
)# 첫 번째 요청이 컨테이너 생성
response1 = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
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 this sales data"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)
# 동일한 컨테이너로 대화 계속
messages = [
{"role": "user", "content": "Analyze this sales data"},
{"role": "assistant", "content": response1.content},
{"role": "user", "content": "What was the total revenue?"}
]
response2 = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"id": response1.container.id, # 컨테이너 재사용
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
]
},
messages=messages,
tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10
response = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
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 i 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-sonnet-4-5-20250929",
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"}]
)response = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
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"
}]
)import anthropic
client = anthropic.Anthropic()
# Option 1: files_from_dir 헬퍼 사용 (Python만 해당, 권장)
from anthropic.lib import files_from_dir
skill = client.beta.skills.create(
display_title="Financial Analysis",
files=files_from_dir("/path/to/financial_analysis_skill"),
betas=["skills-2025-10-02"]
)
# Option 2: zip 파일 사용
skill = client.beta.skills.create(
display_title="Financial Analysis",
files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
betas=["skills-2025-10-02"]
)
# Option 3: 파일 튜플 사용 (filename, file_content, mime_type)
skill = client.beta.skills.create(
display_title="Financial Analysis",
files=[
("financial_skill/SKILL.md", open("financial_skill/SKILL.md", "rb"), "text/markdown"),
("financial_skill/analyze.py", open("financial_skill/analyze.py", "rb"), "text/x-python"),
],
betas=["skills-2025-10-02"]
)
print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")# 모든 Skills 나열
skills = client.beta.skills.list(
betas=["skills-2025-10-02"]
)
for skill in skills.data:
print(f"{skill.id}: {skill.display_title} (source: {skill.source})")
# 사용자 정의 Skills만 나열
custom_skills = client.beta.skills.list(
source="custom",
betas=["skills-2025-10-02"]
)skill = client.beta.skills.retrieve(
skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
betas=["skills-2025-10-02"]
)
print(f"Skill: {skill.display_title}")
print(f"Latest version: {skill.latest_version}")
print(f"Created: {skill.created_at}")# Step 1: 모든 버전 삭제
versions = client.beta.skills.versions.list(
skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
betas=["skills-2025-10-02"]
)
for version in versions.data:
client.beta.skills.versions.delete(
skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
version=version.version,
betas=["skills-2025-10-02"]
)
# Step 2: Skill 삭제
client.beta.skills.delete(
skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
betas=["skills-2025-10-02"]
)# 새 버전 만들기
from anthropic.lib import files_from_dir
new_version = client.beta.skills.versions.create(
skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
files=files_from_dir("/path/to/updated_skill"),
betas=["skills-2025-10-02"]
)
# 특정 버전 사용
response = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": new_version.version
}]
},
messages=[{"role": "user", "content": "Use updated Skill"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)
# 최신 버전 사용
response = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
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": "Use latest Skill version"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)# 사용자 정의 DCF 분석 Skill 만들기
from anthropic.lib import files_from_dir
dcf_skill = client.beta.skills.create(
display_title="DCF Analysis",
files=files_from_dir("/path/to/dcf_skill"),
betas=["skills-2025-10-02"]
)
# Excel과 함께 사용하여 재무 모델 생성
response = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
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 with the attached financials"
}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)# 첫 번째 요청이 캐시 생성
response1 = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
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-sonnet-4-5-20250929",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "anthropic", "skill_id": "pptx", "version": "latest"} # 캐시 미스
]
},
messages=[{"role": "user", "content": "Create a presentation"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)try:
response = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
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}")
# Skill 관련 오류 처리
else:
raise효과적인 Skills 작성을 위한 모범 사례