API로 Agent Skills 사용하기

API를 통해 Agent Skills를 사용하여 Claude의 기능을 확장하는 방법을 알아보세요.

Agent Skills는 지침, 스크립트, 리소스로 구성된 폴더를 통해 Claude의 기능을 확장합니다. 이 가이드에서는 Claude API로 사전 구축된 Skill과 커스텀 Skill을 모두 사용하는 방법을 설명합니다.

빠른 링크

API에서 Agent Skills 시작하기

10분 이내에 Claude API로 Agent Skills를 사용하여 문서를 생성하는 방법을 알아보세요.

Skill 작성 모범 사례

Claude가 발견하고 성공적으로 사용할 수 있는 효과적인 Skill을 작성하는 방법을 알아보세요.

개요

Skill은 코드 실행 도구를 통해 Messages API와 통합됩니다. Anthropic이 관리하는 사전 구축된 Skill을 사용하든 직접 업로드한 커스텀 Skill을 사용하든 통합 형태는 동일합니다. 둘 다 코드 실행이 필요하며 동일한 container 구조를 사용합니다.

Skill 사용하기

Skill은 출처와 관계없이 Messages API에서 동일하게 통합됩니다. container 매개변수에 skill_id, type, 그리고 선택적으로 version을 지정하면 Skill이 코드 실행 환경에서 실행됩니다.

두 가지 출처의 Skill을 사용할 수 있습니다:

항목	Anthropic Skill	커스텀 Skill
Type 값	`anthropic`	`custom`
Skill ID	짧은 이름: `pptx`, `xlsx`, `docx`, `pdf`	생성됨: `skill_01AbCdEfGhIjKlMnOpQrStUv`
버전 형식	날짜 기반: `20251013` 또는 `latest`	버전 ID: `skver_01AbCdEfGhIjKlMnOpQrStUv` 또는 `latest`
관리	Anthropic이 사전 구축 및 유지 관리	Skills API를 통해 업로드 및 관리
가용성	모든 사용자가 사용 가능	워크스페이스에 비공개

두 Skill 출처 모두 List Skills 엔드포인트에서 반환됩니다(source 매개변수를 사용하여 필터링). 통합 형태와 실행 환경은 동일합니다. 유일한 차이점은 Skill의 출처와 관리 방식입니다.

사전 요구 사항

Skill을 사용하려면 다음이 필요합니다:

Claude Console에서 발급받은 Claude API 키
요청에서 활성화된 코드 실행 도구

Skill은 Claude API에서 정식 출시(GA)되었으며, Skills API나 Messages 요청의 container.skills 모두 anthropic-beta 헤더가 필요하지 않습니다. 이 가이드의 예제는 여전히 skills-2025-10-02 베타 헤더(Messages 요청에서는 code-execution-2025-08-25도 함께)를 전송하고 SDK의 beta 네임스페이스를 사용합니다. 두 헤더 모두 유효한 옵트인으로 유지되므로 예제는 작성된 대로 작동하며, 직접 작성하는 요청에서는 생략할 수 있습니다.

Skill은 코드 실행 도구가 필요하므로 해당 도구의 모델 호환성 목록에 있는 모델을 사용하세요.

Messages에서 Skill 사용하기

Container 매개변수

Skill은 Messages API의 container 매개변수를 사용하여 지정합니다. 각 요청당 최대 20개의 Skill을 포함할 수 있습니다.

구조는 Anthropic Skill과 커스텀 Skill 모두 동일합니다. 필수 항목인 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"}],
)

생성된 파일 다운로드하기

Skill이 문서(Excel, PowerPoint, PDF, Word)를 생성하면 응답에 file_id 속성이 반환됩니다. 이러한 파일을 다운로드하려면 Files API를 사용해야 합니다.

작동 방식:

Skill이 코드 실행 중에 파일을 생성합니다.
응답에는 코드 실행 도구 결과 블록 내에 생성된 각 파일의 file_id가 포함됩니다(응답 형식 참조).
Files API를 사용하여 실제 파일 콘텐츠를 다운로드합니다.
로컬에 저장하거나 필요에 따라 처리합니다.

Skill이 작업할 입력 파일을 제공하려면 Files API로 업로드하고 컨테이너 업로드 블록으로 요청에서 참조하세요.

예제: 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)

멀티턴 대화

응답의 container 객체에는 컨테이너의 id와 expires_at 타임스탬프가 포함됩니다(수명 관련 자세한 내용은 컨테이너 재사용 참조). 컨테이너 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"}],
)

장시간 실행 작업

Skill은 여러 턴이 필요한 작업을 수행할 수 있습니다. 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"}],
    )

여러 Skill 사용하기

복잡한 워크플로를 처리하기 위해 단일 요청에서 여러 Skill을 결합하세요:

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 관리하기

커스텀 Skill은 최종 사용자, 대화 또는 세션 단위가 아니라 전체 워크스페이스에서 접근할 수 있습니다. 동일한 워크스페이스의 모든 API 키는 해당 워크스페이스에 업로드된 모든 커스텀 Skill을 읽고, 호출하고, 삭제할 수 있으며, 별도의 워크스페이스에 할당하지 않은 경우 모든 키는 조직의 Default Workspace를 공유합니다.

Skills API를 기반으로 멀티테넌트 플랫폼을 구축하는 경우, 각 테넌트마다 별도의 워크스페이스를 생성하세요. 워크스페이스는 커스텀 Skill의 격리 경계이므로, 테넌트별 워크스페이스를 사용하면 각 테넌트의 Skill이 다른 모든 테넌트로부터 완전히 격리됩니다. 각 조직은 기본적으로 최대 100개의 워크스페이스를 가질 수 있습니다(워크스페이스 작동 방식 참조). 테넌트 격리를 위해 더 많은 워크스페이스가 필요한 경우 계정 담당 팀에 문의하세요.

Skill 생성하기

Skill 번들은 최상위에 name 및 description YAML frontmatter가 포함된 SKILL.md 파일과 지원 스크립트 또는 리소스를 포함하는 디렉터리입니다. 작성 방법은 API에서 Agent Skills 시작하기를 참조하고, 전체 제약 조건은 예제 다음의 요구 사항 목록을 참조하세요.

커스텀 Skill을 업로드하여 워크스페이스에서 사용할 수 있도록 하세요. zip 아카이브 또는 개별 파일 객체를 업로드할 수 있습니다. Python SDK는 디렉터리 경로를 받는 files_from_dir 헬퍼도 제공합니다.

파일은 첨부한 파일 이름으로 식별됩니다(cURL 예제의 ;filename= 접미사 및 SDK 예제의 파일 이름 인수). 이 가이드의 Skill을 위해서는 zip -r financial_skill.zip financial_skill/로 zip을 생성하고 zip 업로드 옵션의 example_skill.zip 플레이스홀더를 이것으로 대체하세요.

zip -r financial_skill.zip financial_skill/
ant beta:skills create \
  --file financial_skill.zip \
  --beta skills-2025-10-02

financial_skill/SKILL.md

---
name: financial-skill
description: Docs example skill.
---

financial_skill/analyze.py

print("financial analysis helper")

요구 사항:

업로드 루트(또는 단일 상위 폴더의 최상위)에 SKILL.md 파일이 포함되어야 함
display_name은 선택 사항: 생략하면 SKILL.md의 name에서 파생됨. 명시적 값은 최대 255자이며 워크스페이스 내에서 고유할 필요 없음
총 업로드 크기는 30 MB 미만이어야 함(압축 해제 기준)
YAML frontmatter 요구 사항:
- name: 최대 64자, 소문자/숫자/하이픈만 허용, XML 태그 불가, 예약어("anthropic", "claude") 불가
- description: 최대 1024자, 비어 있지 않아야 함, XML 태그 불가

전체 요청/응답 스키마는 Create Skill API 레퍼런스를 참조하세요.

Skill 목록 조회하기

Anthropic 사전 구축 Skill과 커스텀 Skill을 모두 포함하여 워크스페이스에서 사용 가능한 모든 Skill을 조회합니다. source 매개변수를 사용하여 Skill 유형별로 필터링하세요:

# 모든 Skill 나열
ant beta:skills list

# 커스텀 Skill만 나열
ant beta:skills list --source custom

페이지네이션 및 필터링 옵션은 List Skills API 레퍼런스를 참조하세요.

Skill 조회하기

특정 Skill에 대한 세부 정보를 가져옵니다:

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Skill 삭제하기

Skill을 삭제하면 해당 Skill의 모든 버전도 함께 제거됩니다. 이 연쇄 삭제는 GA 전용 동작이므로, 이 가이드의 다른 예제와 달리 여기서는 beta 네임스페이스가 아닌 GA 인터페이스를 직접 호출합니다.

ant skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

버전 관리

Skill은 업데이트를 안전하게 관리하기 위해 버전 관리를 지원합니다:

Anthropic Skill:

버전은 날짜 형식 사용: 20251013
업데이트가 있을 때 새 버전 출시
안정성을 위해 정확한 버전 지정

커스텀 Skill:

자동 생성된 버전 ID: skver_01AbCdEfGhIjKlMnOpQrStUv
항상 최신 버전을 가져오려면 "latest" 사용
Skill 파일을 업데이트할 때 새 버전 생성

새 버전은 델타가 아닌 완전한 스냅샷입니다. 매번 Skill의 전체 파일 세트를 업로드하세요. 생략한 파일은 이전 버전에서 이월되지 않으며, 새 버전의 SKILL.md에 있는 name은 Skill의 기존 이름과 일치해야 합니다. 다음 예제는 Skill 생성하기의 전체 financial_skill/ 번들을 다시 업로드합니다.

# 새 버전 생성
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_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 레퍼런스를 참조하세요.

Skill이 로드되는 방식

컨테이너에 Skill을 지정하면:

메타데이터 검색: Claude는 시스템 프롬프트에서 각 Skill의 메타데이터(이름, 설명)를 확인합니다.
파일 로딩: Skill 파일이 컨테이너의 /skills/{skill-name}/에 복사됩니다. 디렉터리는 skill_01... ID가 아니라 Skill의 이름(Anthropic Skill의 경우 pptx, 커스텀 Skill의 경우 SKILL.md의 name)입니다.
자동 사용: Claude는 요청과 관련이 있을 때 자동으로 Skill을 로드하고 사용합니다.
조합: 여러 Skill이 복잡한 워크플로를 위해 함께 조합됩니다.

Claude는 필요할 때만 전체 Skill 지침을 로드합니다.

사용 사례

Skill은 조직 업무와 개인 업무 모두에 적합합니다. 조직은 문서에 브랜드 서식을 적용하고, 회사 템플릿을 중심으로 노트와 보고서를 구성하며, 회사별 분석 절차를 실행하는 데 사용합니다. 개인은 커스텀 문서 템플릿, 특수 데이터 파이프라인, 코드 생성 또는 배포 규칙에 사용합니다.

예제: 재무 모델링

Excel과 커스텀 DCF 분석 Skill을 결합합니다:

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)

제한 및 제약 조건

요청 제한

요청당 최대 Skill 수: 20
최대 Skill 업로드 크기: 30 MB(모든 파일 합계, 압축 해제 기준)
YAML frontmatter 요구 사항:
- name: 최대 64자, 소문자/숫자/하이픈만 허용, XML 태그 불가, 예약어("anthropic", "claude") 불가
- description: 최대 1024자, 비어 있지 않아야 함, XML 태그 불가

환경 제약 조건

Skill은 다음과 같은 제한이 있는 코드 실행 컨테이너에서 실행됩니다:

네트워크 접근 불가: 외부 API 호출 불가
런타임 패키지 설치 불가: 사전 설치된 패키지만 사용 가능
격리된 환경: 기존 컨테이너 ID를 지정하지 않으면 새 컨테이너가 생성됨

사용 가능한 패키지는 코드 실행 도구를 참조하세요.

모범 사례

여러 Skill을 사용해야 하는 경우

작업이 여러 문서 유형이나 도메인을 포함할 때 Skill을 결합하세요:

적합한 사용 사례:

데이터 분석(Excel) + 프레젠테이션 생성(PowerPoint)
보고서 생성(Word) + PDF로 내보내기
커스텀 도메인 로직 + 문서 생성

피해야 할 사항:

사용하지 않는 Skill 포함(성능에 영향)

버전 관리 전략

이 섹션의 SDK 탭은 Messages 요청에 포함할 container 값을 보여줍니다. cURL 및 CLI 탭은 전체 요청을 보여줍니다.

프로덕션의 경우: 특정 버전을 고정하여 Skill 업데이트가 배포된 동작을 변경하지 않도록 하세요. version을 생략하거나 "latest"로 설정하면 요청이 Skill의 최신 버전을 사용하므로, 워크스페이스의 누군가가 업로드한 버전이 프로덕션 에이전트가 실행하는 내용을 즉시 변경합니다. 버전 ID는 버전 관리의 버전 생성 응답 또는 List Skill Versions API에서 가져옵니다. ID는 항상 문자열입니다. JSON 또는 YAML에서 epoch 타임스탬프 ID를 따옴표로 묶으세요.

# 안정성을 위해 특정 버전으로 고정
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",
        }
    ]
}

개발의 경우: 반복 작업 중 최신 버전을 자동으로 가져오려면 latest를 사용하세요.

# 활발한 개발에는 latest 사용
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",
        }
    ]
}

프롬프트 캐싱 고려 사항

프롬프트 캐싱을 사용하는 경우, 컨테이너의 Skill 목록을 변경하면 캐시가 무효화됩니다. Skill은 고정된 순서로 시스템 프롬프트에 렌더링되므로 동일한 목록은 동일한 캐시 가능 접두사를 생성합니다:

client = anthropic.Anthropic()

# Skill은 고정된 캐시 친화적 순서로 시스템 프롬프트에 렌더링됩니다
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"}],
)

# Skill 목록을 변경하면([xlsx] vs [xlsx, pptx]) 접두사가 달라져 캐시 미스가 발생하고, 동일한 목록은 캐시 히트가 됩니다
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",
            },  # prefix change: cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

최상의 캐싱 성능을 위해 요청 간에 Skill 목록(순서 포함)을 일관되게 유지하세요. 커스텀 Skill 버전을 고정하는 것도 도움이 됩니다. "latest"를 사용하면 새 버전을 게시할 때 Skill의 설명이 변경되는 경우 캐시된 접두사가 무효화될 수 있습니다.

오류 처리

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:
        raise

데이터 보존

Agent Skills는 ZDR 계약의 적용을 받지 않습니다. Skill 정의 및 실행 데이터는 Anthropic의 표준 데이터 보존 정책에 따라 보존됩니다.

모든 기능에 대한 ZDR 적용 여부는 API 및 데이터 보존을 참조하세요.

감사 로깅

조직에서 Compliance API를 활성화한 경우, 해당 Activity Feed는 Claude API 키 또는 Claude Console에서 수행된 Skill 및 Skill 버전의 생성과 삭제를 기록합니다. Compliance API가 꺼져 있는 동안 발생한 작업은 기록되지 않으며 나중에 복구할 수 없으므로, 이 감사 추적에 의존하기 전에 Compliance API를 설정하세요.

다음 단계

API 레퍼런스

모든 엔드포인트가 포함된 전체 API 레퍼런스

Skill 작성 모범 사례

Claude가 발견하고 성공적으로 사용할 수 있는 효과적인 Skill을 작성하는 방법을 알아보세요.

코드 실행 도구

샌드박스 컨테이너에서 Python 및 bash 코드를 실행하여 데이터를 분석하고, 파일을 생성하고, 솔루션을 반복 개선하세요.

Was this page helpful?

Messages스킬

API로 Agent Skills 사용하기

API를 통해 Agent Skills를 사용하여 Claude의 기능을 확장하는 방법을 알아보세요.

빠른 링크

API에서 Agent Skills 시작하기

10분 이내에 Claude API로 Agent Skills를 사용하여 문서를 생성하는 방법을 알아보세요.

Skill 작성 모범 사례

Claude가 발견하고 성공적으로 사용할 수 있는 효과적인 Skill을 작성하는 방법을 알아보세요.

개요

Skill 사용하기

두 가지 출처의 Skill을 사용할 수 있습니다:

항목	Anthropic Skill	커스텀 Skill
Type 값	`anthropic`	`custom`
Skill ID	짧은 이름: `pptx`, `xlsx`, `docx`, `pdf`	생성됨: `skill_01AbCdEfGhIjKlMnOpQrStUv`
버전 형식	날짜 기반: `20251013` 또는 `latest`	버전 ID: `skver_01AbCdEfGhIjKlMnOpQrStUv` 또는 `latest`
관리	Anthropic이 사전 구축 및 유지 관리	Skills API를 통해 업로드 및 관리
가용성	모든 사용자가 사용 가능	워크스페이스에 비공개

사전 요구 사항

Skill을 사용하려면 다음이 필요합니다:

Claude Console에서 발급받은 Claude API 키
요청에서 활성화된 코드 실행 도구

Skill은 코드 실행 도구가 필요하므로 해당 도구의 모델 호환성 목록에 있는 모델을 사용하세요.

Messages에서 Skill 사용하기

Container 매개변수

Skill은 Messages API의 container 매개변수를 사용하여 지정합니다. 각 요청당 최대 20개의 Skill을 포함할 수 있습니다.

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

생성된 파일 다운로드하기

Skill이 문서(Excel, PowerPoint, PDF, Word)를 생성하면 응답에 file_id 속성이 반환됩니다. 이러한 파일을 다운로드하려면 Files API를 사용해야 합니다.

작동 방식:

Skill이 코드 실행 중에 파일을 생성합니다.
응답에는 코드 실행 도구 결과 블록 내에 생성된 각 파일의 file_id가 포함됩니다(응답 형식 참조).
Files API를 사용하여 실제 파일 콘텐츠를 다운로드합니다.
로컬에 저장하거나 필요에 따라 처리합니다.

Skill이 작업할 입력 파일을 제공하려면 Files API로 업로드하고 컨테이너 업로드 블록으로 요청에서 참조하세요.

예제: 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)

멀티턴 대화

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

장시간 실행 작업

Skill은 여러 턴이 필요한 작업을 수행할 수 있습니다. 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"}],
    )

여러 Skill 사용하기

복잡한 워크플로를 처리하기 위해 단일 요청에서 여러 Skill을 결합하세요:

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 관리하기

Skill 생성하기

zip -r financial_skill.zip financial_skill/
ant beta:skills create \
  --file financial_skill.zip \
  --beta skills-2025-10-02

financial_skill/SKILL.md

---
name: financial-skill
description: Docs example skill.
---

financial_skill/analyze.py

print("financial analysis helper")

요구 사항:

업로드 루트(또는 단일 상위 폴더의 최상위)에 SKILL.md 파일이 포함되어야 함
display_name은 선택 사항: 생략하면 SKILL.md의 name에서 파생됨. 명시적 값은 최대 255자이며 워크스페이스 내에서 고유할 필요 없음
총 업로드 크기는 30 MB 미만이어야 함(압축 해제 기준)
YAML frontmatter 요구 사항:
- name: 최대 64자, 소문자/숫자/하이픈만 허용, XML 태그 불가, 예약어("anthropic", "claude") 불가
- description: 최대 1024자, 비어 있지 않아야 함, XML 태그 불가

전체 요청/응답 스키마는 Create Skill API 레퍼런스를 참조하세요.

Skill 목록 조회하기

# 모든 Skill 나열
ant beta:skills list

# 커스텀 Skill만 나열
ant beta:skills list --source custom

페이지네이션 및 필터링 옵션은 List Skills API 레퍼런스를 참조하세요.

Skill 조회하기

특정 Skill에 대한 세부 정보를 가져옵니다:

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Skill 삭제하기

ant skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

버전 관리

Skill은 업데이트를 안전하게 관리하기 위해 버전 관리를 지원합니다:

Anthropic Skill:

버전은 날짜 형식 사용: 20251013
업데이트가 있을 때 새 버전 출시
안정성을 위해 정확한 버전 지정

커스텀 Skill:

자동 생성된 버전 ID: skver_01AbCdEfGhIjKlMnOpQrStUv
항상 최신 버전을 가져오려면 "latest" 사용
Skill 파일을 업데이트할 때 새 버전 생성

# 새 버전 생성
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_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 레퍼런스를 참조하세요.

Skill이 로드되는 방식

컨테이너에 Skill을 지정하면:

메타데이터 검색: Claude는 시스템 프롬프트에서 각 Skill의 메타데이터(이름, 설명)를 확인합니다.
파일 로딩: Skill 파일이 컨테이너의 /skills/{skill-name}/에 복사됩니다. 디렉터리는 skill_01... ID가 아니라 Skill의 이름(Anthropic Skill의 경우 pptx, 커스텀 Skill의 경우 SKILL.md의 name)입니다.
자동 사용: Claude는 요청과 관련이 있을 때 자동으로 Skill을 로드하고 사용합니다.
조합: 여러 Skill이 복잡한 워크플로를 위해 함께 조합됩니다.

Claude는 필요할 때만 전체 Skill 지침을 로드합니다.

사용 사례

예제: 재무 모델링

Excel과 커스텀 DCF 분석 Skill을 결합합니다:

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)

제한 및 제약 조건

요청 제한

요청당 최대 Skill 수: 20
최대 Skill 업로드 크기: 30 MB(모든 파일 합계, 압축 해제 기준)
YAML frontmatter 요구 사항:
- name: 최대 64자, 소문자/숫자/하이픈만 허용, XML 태그 불가, 예약어("anthropic", "claude") 불가
- description: 최대 1024자, 비어 있지 않아야 함, XML 태그 불가

환경 제약 조건

Skill은 다음과 같은 제한이 있는 코드 실행 컨테이너에서 실행됩니다:

네트워크 접근 불가: 외부 API 호출 불가
런타임 패키지 설치 불가: 사전 설치된 패키지만 사용 가능
격리된 환경: 기존 컨테이너 ID를 지정하지 않으면 새 컨테이너가 생성됨

사용 가능한 패키지는 코드 실행 도구를 참조하세요.

모범 사례

여러 Skill을 사용해야 하는 경우

작업이 여러 문서 유형이나 도메인을 포함할 때 Skill을 결합하세요:

적합한 사용 사례:

데이터 분석(Excel) + 프레젠테이션 생성(PowerPoint)
보고서 생성(Word) + PDF로 내보내기
커스텀 도메인 로직 + 문서 생성

피해야 할 사항:

사용하지 않는 Skill 포함(성능에 영향)

버전 관리 전략

이 섹션의 SDK 탭은 Messages 요청에 포함할 container 값을 보여줍니다. cURL 및 CLI 탭은 전체 요청을 보여줍니다.

# 안정성을 위해 특정 버전으로 고정
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",
        }
    ]
}

개발의 경우: 반복 작업 중 최신 버전을 자동으로 가져오려면 latest를 사용하세요.

# 활발한 개발에는 latest 사용
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",
        }
    ]
}

프롬프트 캐싱 고려 사항

client = anthropic.Anthropic()

# Skill은 고정된 캐시 친화적 순서로 시스템 프롬프트에 렌더링됩니다
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"}],
)

# Skill 목록을 변경하면([xlsx] vs [xlsx, pptx]) 접두사가 달라져 캐시 미스가 발생하고, 동일한 목록은 캐시 히트가 됩니다
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",
            },  # prefix change: cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

오류 처리

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:
        raise

데이터 보존

Agent Skills는 ZDR 계약의 적용을 받지 않습니다. Skill 정의 및 실행 데이터는 Anthropic의 표준 데이터 보존 정책에 따라 보존됩니다.

모든 기능에 대한 ZDR 적용 여부는 API 및 데이터 보존을 참조하세요.

감사 로깅

다음 단계

API 레퍼런스

모든 엔드포인트가 포함된 전체 API 레퍼런스

Skill 작성 모범 사례

Claude가 발견하고 성공적으로 사용할 수 있는 효과적인 Skill을 작성하는 방법을 알아보세요.

코드 실행 도구

샌드박스 컨테이너에서 Python 및 bash 코드를 실행하여 데이터를 분석하고, 파일을 생성하고, 솔루션을 반복 개선하세요.

Was this page helpful?

빠른 링크

개요

Skill 사용하기

사전 요구 사항

Messages에서 Skill 사용하기

Container 매개변수

생성된 파일 다운로드하기

멀티턴 대화

장시간 실행 작업

여러 Skill 사용하기

커스텀 Skill 관리하기

Skill 생성하기

Skill 목록 조회하기

Skill 조회하기

Skill 삭제하기

버전 관리

Skill이 로드되는 방식

사용 사례

예제: 재무 모델링

제한 및 제약 조건

요청 제한

환경 제약 조건

모범 사례

여러 Skill을 사용해야 하는 경우

버전 관리 전략

프롬프트 캐싱 고려 사항

오류 처리

데이터 보존

감사 로깅

다음 단계

빠른 링크

개요

Skill 사용하기

사전 요구 사항

Messages에서 Skill 사용하기

Container 매개변수

생성된 파일 다운로드하기

멀티턴 대화

장시간 실행 작업

여러 Skill 사용하기

커스텀 Skill 관리하기

Skill 생성하기

Skill 목록 조회하기

Skill 조회하기

Skill 삭제하기

버전 관리

Skill이 로드되는 방식

사용 사례

예제: 재무 모델링

제한 및 제약 조건

요청 제한

환경 제약 조건

모범 사례

여러 Skill을 사용해야 하는 경우

버전 관리 전략

프롬프트 캐싱 고려 사항

오류 처리

데이터 보존

감사 로깅

다음 단계

빠른 링크

개요

Skill 사용하기

사전 요구 사항

Messages에서 Skill 사용하기

Container 매개변수

생성된 파일 다운로드하기

멀티턴 대화

장시간 실행 작업

여러 Skill 사용하기

커스텀 Skill 관리하기

Skill 생성하기

Skill 목록 조회하기

Skill 조회하기

Skill 삭제하기

버전 관리

Skill이 로드되는 방식

사용 사례

예제: 재무 모델링

제한 및 제약 조건

요청 제한

환경 제약 조건

모범 사례

여러 Skill을 사용해야 하는 경우

버전 관리 전략

프롬프트 캐싱 고려 사항

오류 처리

데이터 보존

감사 로깅

다음 단계

빠른 링크

개요

Skill 사용하기

사전 요구 사항

Messages에서 Skill 사용하기

Container 매개변수

생성된 파일 다운로드하기

멀티턴 대화

장시간 실행 작업

여러 Skill 사용하기

커스텀 Skill 관리하기

Skill 생성하기

Skill 목록 조회하기

Skill 조회하기

Skill 삭제하기

버전 관리

Skill이 로드되는 방식

사용 사례

예제: 재무 모델링

제한 및 제약 조건

요청 제한

환경 제약 조건

모범 사례

여러 Skill을 사용해야 하는 경우

버전 관리 전략

프롬프트 캐싱 고려 사항

오류 처리

데이터 보존

감사 로깅

다음 단계