API에서 Agent Skills 사용하기
API를 통해 Agent Skills를 사용하여 Claude의 기능을 확장하는 방법을 알아보세요.
Agent Skills는 지침, 스크립트, 리소스로 구성된 체계적인 폴더를 통해 Claude의 기능을 확장합니다. 이 가이드에서는 Claude API에서 사전 구축된 Skills와 커스텀 Skills를 모두 사용하는 방법을 보여줍니다.
빠른 링크
10분 이내에 Claude API로 Agent Skills를 사용하여 문서를 생성하는 방법을 알아보세요.
Claude가 발견하고 성공적으로 사용할 수 있는 효과적인 Skills를 작성하는 방법을 알아보세요.
개요
Skills는 코드 실행 도구를 통해 Messages API와 통합됩니다. Anthropic이 관리하는 사전 구축된 Skills를 사용하든 직접 업로드한 커스텀 Skills를 사용하든 통합 형태는 동일합니다. 둘 다 코드 실행이 필요하며 동일한 container 구조를 사용합니다.
Skills 사용하기
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 | 버전 ID: skver_01AbCdEfGhIjKlMnOpQrStUv 또는 latest |
| 관리 | Anthropic이 사전 구축 및 유지 관리 | Skills API를 통해 업로드 및 관리 |
| 가용성 | 모든 사용자가 사용 가능 | 워크스페이스 전용 |
두 skill 출처 모두 List Skills 엔드포인트에서 반환됩니다(source 파라미터를 사용하여 필터링). 통합 형태와 실행 환경은 동일합니다. 유일한 차이점은 Skills의 출처와 관리 방식입니다.
사전 요구 사항
Skills를 사용하려면 다음이 필요합니다:
- Claude Console에서 발급받은 Claude API 키
- 요청에서 활성화된 코드 실행 도구
Skills는 코드 실행 도구가 필요하므로, 해당 도구의 모델 호환성 목록에 있는 모델을 사용하세요.
Messages에서 Skills 사용하기
Container 파라미터
Skills는 Messages API의 container 파라미터를 사용하여 지정합니다. 각 요청에 최대 20개의 Skills를 포함할 수 있습니다.
구조는 Anthropic Skills와 커스텀 Skills 모두 동일합니다. 필수 항목인 type과 skill_id를 지정하고, 특정 버전에 고정하려면 선택적으로 version을 포함하세요:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
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를 사용해야 합니다.
작동 방식:
- Skills가 코드 실행 중에 파일을 생성합니다.
- 응답에는 생성된 각 파일에 대한
file_id가 코드 실행 도구 결과 블록 내에 포함됩니다(응답 형식 참조). - Files API를 사용하여 실제 파일 콘텐츠를 다운로드합니다.
- 로컬에 저장하거나 필요에 따라 처리합니다.
Skills가 작업할 입력 파일을 제공하려면 Files API로 업로드하고 요청에서 container upload 블록으로 참조하세요.
예시: Excel 파일 생성 및 다운로드
client = anthropic.Anthropic()
# 1단계: Skill을 사용하여 파일을 생성합니다
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
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":
# 각 content 항목은 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.files.retrieve_metadata(file_id=file_id)
file_content = client.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.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")
# 모든 파일 나열
for file in client.files.list():
print(f"{file.filename} - {file.created_at}")
# 파일 삭제
client.files.delete(file_id=file_id)멀티턴 대화
응답의 container 객체에는 컨테이너의 id와 expires_at 타임스탬프가 포함됩니다(수명에 대한 자세한 내용은 컨테이너 재사용 참조). 컨테이너 ID를 지정하여 여러 메시지에 걸쳐 동일한 컨테이너를 재사용하세요:
client = anthropic.Anthropic()
# 첫 번째 요청에서 컨테이너를 생성합니다
response1 = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
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.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
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.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
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.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"id": response.container.id,
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
}
],
},
messages=messages,
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)여러 Skills 사용하기
복잡한 워크플로를 처리하기 위해 단일 요청에서 여러 Skills를 결합하세요:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
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"}],
)커스텀 Skills 관리하기
Skill 생성하기
Skill 번들은 최상위에 name과 description YAML 프론트매터가 있는 SKILL.md 파일과 지원 스크립트 또는 리소스를 포함하는 디렉터리입니다. 작성 방법은 API에서 Agent Skills 시작하기를 참조하고, 전체 제약 조건은 예시 다음에 나오는 요구 사항 목록을 참조하세요.
사용자 정의 Skill을 업로드하여 워크스페이스에서 사용할 수 있도록 하세요. zip 아카이브 또는 개별 파일 객체를 업로드할 수 있습니다. Python SDK는 디렉터리 경로를 받는 files_from_dir 헬퍼도 제공하며, CLI의 ant apply는 디렉터리 자체를 업로드합니다.
파일은 첨부한 파일명으로 식별됩니다(cURL 예시의 ;filename= 접미사 및 SDK 예시의 filename 인수). 워크스루의 skill의 경우, zip -r financial_skill.zip financial_skill/로 zip을 생성하고 zip 업로드 옵션의 example_skill.zip 플레이스홀더를 이것으로 대체하세요.
ant apply financial_skill---
name: financial-skill
description: Docs example skill.
---print("financial analysis helper")요구 사항:
- 업로드 루트(또는 단일 상위 폴더의 최상위)에
SKILL.md파일을 포함해야 합니다 display_name은 선택 사항입니다. 생략하면SKILL.md의name에서 파생되며, 명시적 값은 최대 255자까지 가능하고 워크스페이스 내에서 고유할 필요는 없습니다- 총 업로드 크기는 30 MB(비압축) 미만이어야 합니다
- YAML 프론트매터 요구 사항:
name: 최대 64자, 소문자/숫자/하이픈만 허용, XML 태그 불가, 예약어("anthropic", "claude") 불가description: 최대 1024자, 비어 있지 않아야 함, XML 태그 불가
전체 요청/응답 스키마는 Create Skill API 레퍼런스를 참조하세요.
Skills 목록 조회하기
Anthropic 사전 구축 Skills와 커스텀 Skills를 모두 포함하여 워크스페이스에서 사용 가능한 모든 Skills를 조회합니다. source 파라미터를 사용하여 skill 유형별로 필터링하세요:
client = anthropic.Anthropic()
# 모든 Skills 나열
for skill in client.skills.list():
print(f"{skill.id}: {skill.display_name} (source: {skill.source.type})")
# 사용자 정의 Skills만 나열
custom_skills = client.skills.list(source="custom")페이지네이션 및 필터링 옵션은 List Skills API 레퍼런스를 참조하세요.
Skill 조회하기
특정 Skill에 대한 세부 정보를 가져옵니다:
client = anthropic.Anthropic()
skill = client.skills.retrieve(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")
print(f"Skill: {skill.display_name}")
print(f"Latest version: {skill.latest_version_id}")
print(f"Created: {skill.created_at}")Skill 삭제하기
Skill을 삭제하면 해당 Skill의 모든 버전도 함께 제거됩니다.
client = anthropic.Anthropic()
client.skills.delete(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")버전 관리
Skills는 업데이트를 안전하게 관리하기 위해 버전 관리를 지원합니다:
Anthropic Skills:
- 버전은 날짜 형식을 사용합니다:
20251013 - 업데이트가 이루어질 때마다 새 버전이 릴리스됩니다
- 안정성을 위해 정확한 버전을 지정하세요
커스텀 Skills:
- 자동 생성된 버전 ID:
skver_01AbCdEfGhIjKlMnOpQrStUv - 항상 최신 버전을 가져오려면
"latest"를 사용하세요 - Skill 파일을 업데이트할 때 새 버전을 생성하세요
새 버전은 델타가 아닌 완전한 스냅샷입니다. 매번 Skill의 전체 파일 세트를 업로드하세요. 생략한 파일은 이전되지 않으며, 새 버전의 SKILL.md에 있는 name은 Skill의 기존 이름과 일치해야 합니다. 다음 예시는 Skill 생성하기의 전체 financial_skill/ 번들을 다시 업로드합니다.
from anthropic.lib import files_from_dir
client = anthropic.Anthropic()
# 새 버전을 생성합니다
new_version = client.skills.versions.create(
skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
files=files_from_dir("financial_skill"),
)
# 특정 버전을 사용합니다
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": new_version.id,
}
]
},
messages=[{"role": "user", "content": "Use updated Skill"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# 최신 버전을 사용합니다
response = client.messages.create(
model="claude-opus-5-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"}],
)전체 세부 사항은 Create Skill Version API 레퍼런스를 참조하세요.
Skills가 로드되는 방식
컨테이너에 Skills를 지정하면:
- 메타데이터 발견: Claude는 시스템 프롬프트에서 각 Skill의 메타데이터(이름, 설명)를 확인합니다.
- 파일 로딩: Skill 파일은 컨테이너의
/skills/{skill-name}/에 복사됩니다. 디렉터리는skill_01...ID가 아니라 Skill의 이름(Anthropic Skill의 경우pptx, 커스텀 Skill의 경우SKILL.md의name)입니다. - 자동 사용: Claude는 요청과 관련이 있을 때 Skills를 자동으로 로드하고 사용합니다.
- 조합: 여러 Skills가 복잡한 워크플로를 위해 함께 조합됩니다.
Claude는 필요할 때만 전체 Skill 지침을 로드합니다.
사용 사례
Skills는 조직 업무와 개인 업무 모두에 적합합니다. 조직은 문서에 브랜드 서식을 적용하고, 회사 템플릿에 맞춰 노트와 보고서를 구성하며, 회사 고유의 분석 절차를 실행하는 데 사용합니다. 개인은 커스텀 문서 템플릿, 전문 데이터 파이프라인, 코드 생성 또는 배포 규칙에 사용합니다.
예시: 재무 모델링
Excel Skill과 사용자 정의 DCF 분석 Skill을 결합합니다. 먼저 사용자 정의 DCF 분석 Skill을 생성하세요:
ant apply dcf_skill그런 다음 Excel Skill과 함께 사용하여 재무 모델을 생성하세요. 생성한 Skill의 ID를 사용자 정의 Skill의 skill_id로 전달하세요:
client = anthropic.Anthropic()
# 사용자 지정 DCF 분석 Skill(ID는 Skills API 생성 응답에서 가져옴)
dcf_skill_id = "skill_01AbCdEfGhIjKlMnOpQrStUv"
# Excel과 함께 사용하여 재무 모델을 생성합니다
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
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)제한 및 제약 사항
요청 제한
- 요청당 최대 Skills 수: 20
- 최대 Skill 업로드 크기: 30 MB(모든 파일 합산, 비압축)
- YAML 프론트매터 요구 사항:
name: 최대 64자, 소문자/숫자/하이픈만 허용, XML 태그 불가, 예약어("anthropic", "claude") 불가description: 최대 1024자, 비어 있지 않아야 함, XML 태그 불가
환경 제약 사항
Skills는 다음과 같은 제한이 있는 코드 실행 컨테이너에서 실행됩니다:
- 네트워크 접근 불가: 외부 API 호출을 할 수 없습니다
- 런타임 패키지 설치 불가: 사전 설치된 패키지만 사용 가능합니다
- 격리된 환경: 기존 컨테이너 ID를 지정하지 않으면 새 컨테이너가 생성됩니다
사용 가능한 패키지는 코드 실행 도구를 참조하세요.
모범 사례
여러 Skills를 사용해야 하는 경우
작업이 여러 문서 유형이나 도메인을 포함할 때 Skills를 결합하세요:
좋은 사용 사례:
- 데이터 분석(Excel) + 프레젠테이션 생성(PowerPoint)
- 보고서 생성(Word) + PDF로 내보내기
- 커스텀 도메인 로직 + 문서 생성
피해야 할 것:
- 사용하지 않는 Skills 포함(성능에 영향)
버전 관리 전략
이 섹션의 SDK 탭은 Messages 요청에 포함할 container 값을 보여줍니다. cURL 및 CLI 탭은 전체 요청을 보여줍니다.
프로덕션의 경우: 특정 버전을 고정하여 Skill 업데이트가 배포된 동작을 절대 변경하지 않도록 하세요. version을 생략하거나 "latest"로 설정하면 요청은 Skill의 최신 버전을 사용하므로, 워크스페이스의 누구든 업로드한 버전이 프로덕션 에이전트가 실행하는 내용을 즉시 변경합니다. 버전 ID는 버전 관리의 create-version 응답 또는 List Skill Versions API에서 가져옵니다. ID는 항상 문자열이므로, 숫자처럼 보이더라도 JSON 또는 YAML에서 따옴표로 감싸세요.
# 안정성을 위해 특정 버전으로 고정하세요
container = {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "skver_01AbCdEfGhIjKlMnOpQrStUv",
}
]
}개발의 경우: 반복 작업 중에 최신 버전을 자동으로 가져오려면 latest를 사용하세요.
# 활발한 개발 중에는 latest를 사용하세요
container = {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
}
]
}프롬프트 캐싱 고려 사항
프롬프트 캐싱을 사용하는 경우, 컨테이너의 Skills 목록을 변경하면 캐시가 깨집니다. Skills는 고정된 순서로 시스템 프롬프트에 렌더링되므로, 동일한 목록은 동일한 캐시 가능 접두사를 생성합니다:
client = anthropic.Anthropic()
# Skills는 캐시에 유리한 고정된 순서로 시스템 프롬프트에 렌더링됩니다
response1 = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
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 목록을 변경하면([xlsx] vs [xlsx, pptx]) 접두사가 바뀌어 캐시 미스가 발생하고, 동일한 목록이면 캐시 히트가 됩니다
response2 = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{
"type": "anthropic",
"skill_id": "pptx",
"version": "latest",
}, # prefix change: cache miss
]
},
messages=[{"role": "user", "content": "Create a presentation"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)최상의 캐싱 성능을 위해 순서를 포함한 Skills 목록을 요청 간에 일관되게 유지하세요. 커스텀 Skill 버전을 고정하는 것도 도움이 됩니다. "latest"를 사용하면 새 버전을 게시할 때 Skill의 설명이 변경되는 경우 캐시된 접두사가 무효화될 수 있습니다.
오류 처리
Skill 관련 오류를 적절하게 처리하세요:
client = anthropic.Anthropic()
try:
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
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:
raiseskills-2025-10-02에서 마이그레이션하기
Skills API는 베타를 종료했으며 베타 헤더가 필요하지 않습니다. skills-2025-10-02에서의 마이그레이션은 선택 사항입니다. 여전히 이 헤더를 보내는 요청은 계속 작동하며 베타 응답 형태를 계속 반환하므로, 기존 통합은 변경하기 전까지 계속 작동합니다. 헤더를 제거하면 해당 요청은 이 페이지에 문서화된 형태로 전환됩니다:
skills-2025-10-02 사용 시 | 헤더 없이 | |
|---|---|---|
| Skill 레이블 | display_title(최대 64자, 워크스페이스별 고유) | display_name(최대 255자, 고유하지 않음); 생략 시 SKILL.md의 name에서 파생 |
| 최신 버전 포인터 | latest_version, "1759178010641129"와 같은 에포크 마이크로초 문자열 | latest_version_id, "skver_01AbCdEfGhIjKlMnOpQrStUv"와 같은 버전 ID; GET /v1/skills/{skill_id}/versions/latest가 한 번의 호출로 이를 확인 |
| URL의 버전 식별자 | 에포크 마이크로초 문자열 | 버전 ID(skver_...). 베타에서 skill_version_ 접두사로 캡처된 ID는 입력으로 허용됩니다. |
| 버전 객체 | directory 포함(항상 Skill name과 동일) | directory 필드 없음 |
source | 문자열, "custom" 또는 "anthropic" | 객체, 예: {"type": "custom"}; 예시 카탈로그 값은 "anthropic_example" |
| 목록 응답 | { data, has_more, next_page } | { data, next_page }; limit은 1에서 1,000까지(기본값 20) |
| 버전 목록 순서 | 오래된 순 | 최신 순, 기본 limit 20. 한 형태의 페이지 커서는 다른 형태에서 유효하지 않습니다. |
| Skill 삭제 | 버전이 하나라도 존재하면 400 오류 반환 | Skill과 모든 버전을 삭제 |
| Skill의 유일한 버전 삭제 | 허용됨, 버전이 없는 Skill이 남음 | 400 오류 반환; 먼저 대체 버전을 업로드하거나 Skill을 삭제하세요 |
| 업로드 레이아웃 | 파일은 이름이 Skill name과 일치하는 최상위 디렉터리 안에 있어야 함 | SKILL.md가 업로드 루트에 있을 수 있음; 저장된 경로는 어느 쪽이든 동일 |
| 응답 타입 | CreateSkillResponse, GetSkillResponse, 그리고 작업당 하나의 타입 | Skill, SkillVersion, DeletedSkill, DeletedSkillVersion |
마이그레이션하려면:
- 베타 헤더를 제거하세요. 요청에서
anthropic-beta: skills-2025-10-02를 삭제하세요. SDK에서는client.beta.skills대신client.skills를 호출하세요.client.beta.skills를 유지하는 것은 더 이상 헤더를 보내지 않는 SDK 릴리스에서만 작동합니다. 이전 릴리스는betas인수가 없어도client.beta.skills에서 헤더를 보냅니다. - 코드에서 필드 이름을 변경하세요:
display_title을display_name으로,latest_version을latest_version_id로 변경하고,source를 문자열과 비교하는 대신source.type을 읽으세요. - 버전 ID를 사용하세요. 에포크 마이크로초 버전을 저장한 곳마다 대신 버전의
id를 저장하거나latest를 사용하세요. Messages 요청의 Skill 참조는 버전 ID,latest, 또는 (Anthropic Skills의 경우) 카탈로그 버전을 허용합니다. - 삭제 호출을 검토하세요.
DELETE /v1/skills/{skill_id}는 이제 Skill과 함께 모든 버전을 제거합니다. 베타의 거부 동작을 안전장치로 의존했다면 자체 검사를 추가하세요.
베타에서 모든 버전이 삭제된 Skill은 반환할 현재 버전이 없습니다. GET /v1/skills/{skill_id}는 400 오류를 반환하며, 버전을 업로드할 때까지 해당 Skill은 목록 응답에서 제외됩니다. 여전히 삭제할 수는 있습니다.
SDK 베타 네임스페이스
Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, Ruby SDK 1.67.0, C# SDK 12.44.0부터 client.beta.skills는 더 이상 skills-2025-10-02를 보내지 않으며 client.skills와 동일한 형태를 Beta 접두사가 붙은 타입 이름(BetaSkill, BetaSkillVersion, BetaDeletedSkill, BetaDeletedSkillVersion)으로 반환합니다. 아직 베타인 Skills 기능을 위해 betas 인수를 허용합니다. 베타 Messages 타입에서 컨테이너 Skill 참조 타입은 BetaSkill에서 BetaContainerSkill로 이름이 변경되었습니다(동일한 필드: type, skill_id, version). BetaSkill은 이제 비베타 타입의 Skill 및 ContainerSkill과 일치하도록 Skill 리소스를 지칭합니다. 이전 SDK 릴리스는 베타 형태로 타입이 지정되어 있습니다. 해당 타입에 의존한다면 마이그레이션할 때까지 이전 릴리스를 유지하세요.
데이터 보존
Agent Skills는 ZDR 계약의 적용 대상이 아닙니다. Skill 정의 및 실행 데이터는 Anthropic의 표준 데이터 보존 정책에 따라 보존됩니다.
모든 기능에 대한 ZDR 적격성은 API 및 데이터 보존을 참조하세요.
감사 로깅
조직에서 Compliance API를 활성화한 경우, 해당 Activity Feed는 Claude API 키로 또는 Claude Console에서 수행된 Skills 및 Skill 버전의 생성과 삭제를 기록합니다. Compliance API가 꺼져 있는 동안 발생한 작업은 기록되지 않으며 나중에 복구할 수 없으므로, 이 감사 추적에 의존하기 전에 Compliance API를 설정하세요.
다음 단계
모든 엔드포인트가 포함된 전체 API 레퍼런스
Claude가 발견하고 성공적으로 사용할 수 있는 효과적인 Skills를 작성하는 방법을 알아보세요.
샌드박스 컨테이너에서 Python 및 bash 코드를 실행하여 데이터를 분석하고, 파일을 생성하고, 솔루션을 반복 개선하세요.
Was this page helpful?