Messages스킬

API에서 Agent Skills 사용하기

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

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

요청/응답 스키마 및 모든 매개변수를 포함한 전체 API 레퍼런스는 다음을 참조하세요:

Skill 관리 API 레퍼런스 - Skill에 대한 CRUD 작업
Skill 버전 API 레퍼런스 - 버전 관리

이 기능은 Zero Data Retention (ZDR) 대상이 아닙니다. 데이터는 해당 기능의 표준 보존 정책에 따라 보존됩니다.

빠른 링크

Agent Skills 시작하기

첫 번째 Skill 만들기

커스텀 Skill 만들기

Skill 작성을 위한 모범 사례

개요

Agent Skills의 아키텍처와 실제 적용 사례에 대해 자세히 알아보려면 엔지니어링 블로그 게시물 Equipping agents for the real world with Agent Skills를 읽어보세요.

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`	에포크 타임스탬프: `1759178010641129` 또는 `latest`
관리	Anthropic이 사전 구축 및 유지 관리	Skills API를 통해 업로드 및 관리
가용성	모든 사용자가 사용 가능	워크스페이스 내에서만 비공개로 사용 가능

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

사전 요구 사항

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

Console에서 발급받은 Claude API 키
베타 헤더:
- code-execution-2025-08-25 - 코드 실행 활성화(Skill에 필수)
- skills-2025-10-02 - Skills API 활성화
- files-api-2025-04-14 - 컨테이너에 파일 업로드/다운로드용
요청에서 코드 실행 도구 활성화

Messages에서 Skill 사용하기

Container 매개변수

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

구조는 Anthropic Skill과 커스텀 Skill 모두 동일합니다. 필수 항목인 type과 skill_id를 지정하고, 특정 버전으로 고정하려면 선택적으로 version을 포함하세요:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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를 사용하여 실제 파일 콘텐츠를 다운로드합니다
로컬에 저장하거나 필요에 따라 처리합니다

예시: Excel 파일 생성 및 다운로드

client = anthropic.Anthropic()

# 1단계: Skill을 사용하여 파일 생성
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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":
                # 구체적 타입 리스트: List[BashCodeExecutionOutputBlock]
                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_abc123"
# 파일 메타데이터 가져오기
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# 모든 파일 나열
files = client.beta.files.list()
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# 파일 삭제
client.beta.files.delete(file_id=file_id)

Files API에 대한 자세한 내용은 Files API 문서를 참조하세요.

멀티턴 대화

컨테이너 ID를 지정하여 여러 메시지에서 동일한 컨테이너를 재사용하세요:

# 첫 번째 요청이 컨테이너를 생성합니다
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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-opus-4-8",
    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 중지 이유를 처리하세요:

messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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-opus-4-8",
        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"}],
    )

응답에 pause_turn 중지 이유가 포함될 수 있으며, 이는 API가 장기 실행 Skill 작업을 일시 중지했음을 나타냅니다. 후속 요청에서 응답을 그대로 다시 제공하여 Claude가 턴을 계속하도록 하거나, 대화를 중단하고 추가 지침을 제공하려는 경우 콘텐츠를 수정할 수 있습니다.

여러 Skill 사용하기

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

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 생성하기

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

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

# 옵션 1: 개별 파일 업로드 (파일당 하나의 --file 플래그)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# 옵션 2: zip 아카이브 업로드
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

요구 사항:

최상위 레벨에 SKILL.md 파일이 포함되어야 합니다
모든 파일은 경로에 공통 루트 디렉터리를 지정해야 합니다
총 업로드 크기는 30 MB 미만이어야 합니다
YAML 프런트매터 요구 사항:
- 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을 삭제하려면 먼저 모든 버전을 삭제해야 합니다:

# 1단계: 모든 버전 삭제
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

# 2단계: Skill 삭제
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

기존 버전이 있는 Skill을 삭제하려고 하면 400 오류가 반환됩니다.

버전 관리

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

Anthropic Skill:

버전은 날짜 형식 사용: 20251013
업데이트가 이루어질 때 새 버전이 릴리스됨
안정성을 위해 정확한 버전 지정

커스텀 Skill:

자동 생성된 에포크 타임스탬프: 1759178010641129
항상 최신 버전을 가져오려면 "latest" 사용
Skill 파일을 업데이트할 때 새 버전 생성

# 새 버전 생성
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --raw-output)

# 특정 버전 사용
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-8
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 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-8
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/{directory}/에 복사됩니다
자동 사용: Claude는 요청과 관련이 있을 때 자동으로 Skill을 로드하고 사용합니다
조합: 복잡한 워크플로를 위해 여러 Skill이 함께 조합됩니다

점진적 공개(progressive disclosure) 아키텍처는 효율적인 컨텍스트 사용을 보장합니다. Claude는 필요할 때만 전체 Skill 지침을 로드합니다.

사용 사례

조직용 Skill

브랜드 및 커뮤니케이션

문서에 회사별 서식(색상, 글꼴, 레이아웃) 적용
조직 템플릿을 따르는 커뮤니케이션 생성
모든 출력물에서 일관된 브랜드 가이드라인 보장

프로젝트 관리

회사별 형식(OKR, 의사결정 로그)으로 노트 구조화
팀 규칙을 따르는 작업 생성
표준화된 회의 요약 및 상태 업데이트 작성

비즈니스 운영

회사 표준 보고서, 제안서 및 분석 작성
회사별 분석 절차 실행
조직 템플릿을 따르는 재무 모델 생성

개인용 Skill

콘텐츠 제작

커스텀 문서 템플릿
특수 서식 및 스타일링
도메인별 콘텐츠 생성

데이터 분석

커스텀 데이터 처리 파이프라인
특수 시각화 템플릿
산업별 분석 방법

개발 및 자동화

코드 생성 템플릿
테스트 프레임워크
배포 워크플로

예시: 재무 모델링

Excel과 커스텀 DCF 분석 Skill을 결합하세요:

# 사용자 정의 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"),
)

# Excel과 함께 사용하여 재무 모델 생성
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)
print(response)

제한 및 제약 조건

요청 제한

요청당 최대 Skill 수: 8개
최대 Skill 업로드 크기: 30 MB(모든 파일 합산)
YAML 프런트매터 요구 사항:
- name: 최대 64자, 소문자/숫자/하이픈만 허용, XML 태그 불가, 예약어("anthropic", "claude") 불가
- description: 최대 1024자, 비어 있지 않아야 함, XML 태그 불가

환경 제약 조건

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

네트워크 액세스 없음: 외부 API 호출 불가
런타임 패키지 설치 불가: 사전 설치된 패키지만 사용 가능
격리된 환경: 컨테이너는 격리되어 있으며, 기존 컨테이너 ID를 지정하지 않으면 새 컨테이너가 생성됩니다

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

모범 사례

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

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

적합한 사용 사례:

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

피해야 할 사항:

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

버전 관리 전략

프로덕션용:

# 안정성을 위해 특정 버전으로 고정
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
        }
    ]
}

프롬프트 캐싱 고려 사항

프롬프트 캐싱을 사용할 때, 컨테이너의 Skill 목록을 변경하면 캐시가 무효화된다는 점에 유의하세요:

# 첫 번째 요청이 캐시를 생성합니다
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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-opus-4-8",
    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",
            },  # Cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

최상의 캐싱 성능을 위해 요청 간에 Skill 목록을 일관되게 유지하세요.

오류 처리

Skill 관련 오류를 적절하게 처리하세요:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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 작성을 위한 모범 사례

코드 실행 도구

코드 실행 환경에 대해 알아보기

Was this page helpful?

Messages스킬

API에서 Agent Skills 사용하기

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

요청/응답 스키마 및 모든 매개변수를 포함한 전체 API 레퍼런스는 다음을 참조하세요:

Skill 관리 API 레퍼런스 - Skill에 대한 CRUD 작업
Skill 버전 API 레퍼런스 - 버전 관리

이 기능은 Zero Data Retention (ZDR) 대상이 아닙니다. 데이터는 해당 기능의 표준 보존 정책에 따라 보존됩니다.

빠른 링크

Agent Skills 시작하기

첫 번째 Skill 만들기

커스텀 Skill 만들기

Skill 작성을 위한 모범 사례

개요

Agent Skills의 아키텍처와 실제 적용 사례에 대해 자세히 알아보려면 엔지니어링 블로그 게시물 Equipping agents for the real world with Agent Skills를 읽어보세요.

Skill 사용하기

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

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

사전 요구 사항

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

Console에서 발급받은 Claude API 키
베타 헤더:
- code-execution-2025-08-25 - 코드 실행 활성화(Skill에 필수)
- skills-2025-10-02 - Skills API 활성화
- files-api-2025-04-14 - 컨테이너에 파일 업로드/다운로드용
요청에서 코드 실행 도구 활성화

Messages에서 Skill 사용하기

Container 매개변수

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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를 사용하여 실제 파일 콘텐츠를 다운로드합니다
로컬에 저장하거나 필요에 따라 처리합니다

예시: Excel 파일 생성 및 다운로드

client = anthropic.Anthropic()

# 1단계: Skill을 사용하여 파일 생성
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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":
                # 구체적 타입 리스트: List[BashCodeExecutionOutputBlock]
                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_abc123"
# 파일 메타데이터 가져오기
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# 모든 파일 나열
files = client.beta.files.list()
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# 파일 삭제
client.beta.files.delete(file_id=file_id)

Files API에 대한 자세한 내용은 Files API 문서를 참조하세요.

멀티턴 대화

컨테이너 ID를 지정하여 여러 메시지에서 동일한 컨테이너를 재사용하세요:

# 첫 번째 요청이 컨테이너를 생성합니다
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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-opus-4-8",
    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 중지 이유를 처리하세요:

messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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-opus-4-8",
        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을 결합하세요:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 생성하기

# 옵션 1: 개별 파일 업로드 (파일당 하나의 --file 플래그)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# 옵션 2: zip 아카이브 업로드
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

요구 사항:

최상위 레벨에 SKILL.md 파일이 포함되어야 합니다
모든 파일은 경로에 공통 루트 디렉터리를 지정해야 합니다
총 업로드 크기는 30 MB 미만이어야 합니다
YAML 프런트매터 요구 사항:
- 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 삭제하기

Skill을 삭제하려면 먼저 모든 버전을 삭제해야 합니다:

# 1단계: 모든 버전 삭제
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

# 2단계: Skill 삭제
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

기존 버전이 있는 Skill을 삭제하려고 하면 400 오류가 반환됩니다.

버전 관리

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

Anthropic Skill:

버전은 날짜 형식 사용: 20251013
업데이트가 이루어질 때 새 버전이 릴리스됨
안정성을 위해 정확한 버전 지정

커스텀 Skill:

자동 생성된 에포크 타임스탬프: 1759178010641129
항상 최신 버전을 가져오려면 "latest" 사용
Skill 파일을 업데이트할 때 새 버전 생성

# 새 버전 생성
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --raw-output)

# 특정 버전 사용
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-8
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 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-8
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/{directory}/에 복사됩니다
자동 사용: Claude는 요청과 관련이 있을 때 자동으로 Skill을 로드하고 사용합니다
조합: 복잡한 워크플로를 위해 여러 Skill이 함께 조합됩니다

점진적 공개(progressive disclosure) 아키텍처는 효율적인 컨텍스트 사용을 보장합니다. Claude는 필요할 때만 전체 Skill 지침을 로드합니다.

사용 사례

조직용 Skill

브랜드 및 커뮤니케이션

문서에 회사별 서식(색상, 글꼴, 레이아웃) 적용
조직 템플릿을 따르는 커뮤니케이션 생성
모든 출력물에서 일관된 브랜드 가이드라인 보장

프로젝트 관리

회사별 형식(OKR, 의사결정 로그)으로 노트 구조화
팀 규칙을 따르는 작업 생성
표준화된 회의 요약 및 상태 업데이트 작성

비즈니스 운영

회사 표준 보고서, 제안서 및 분석 작성
회사별 분석 절차 실행
조직 템플릿을 따르는 재무 모델 생성

개인용 Skill

콘텐츠 제작

커스텀 문서 템플릿
특수 서식 및 스타일링
도메인별 콘텐츠 생성

데이터 분석

커스텀 데이터 처리 파이프라인
특수 시각화 템플릿
산업별 분석 방법

개발 및 자동화

코드 생성 템플릿
테스트 프레임워크
배포 워크플로

예시: 재무 모델링

Excel과 커스텀 DCF 분석 Skill을 결합하세요:

# 사용자 정의 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"),
)

# Excel과 함께 사용하여 재무 모델 생성
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)
print(response)

제한 및 제약 조건

요청 제한

요청당 최대 Skill 수: 8개
최대 Skill 업로드 크기: 30 MB(모든 파일 합산)
YAML 프런트매터 요구 사항:
- name: 최대 64자, 소문자/숫자/하이픈만 허용, XML 태그 불가, 예약어("anthropic", "claude") 불가
- description: 최대 1024자, 비어 있지 않아야 함, XML 태그 불가

환경 제약 조건

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

네트워크 액세스 없음: 외부 API 호출 불가
런타임 패키지 설치 불가: 사전 설치된 패키지만 사용 가능
격리된 환경: 컨테이너는 격리되어 있으며, 기존 컨테이너 ID를 지정하지 않으면 새 컨테이너가 생성됩니다

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

모범 사례

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

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

적합한 사용 사례:

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

피해야 할 사항:

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

버전 관리 전략

프로덕션용:

# 안정성을 위해 특정 버전으로 고정
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
        }
    ]
}

프롬프트 캐싱 고려 사항

프롬프트 캐싱을 사용할 때, 컨테이너의 Skill 목록을 변경하면 캐시가 무효화된다는 점에 유의하세요:

# 첫 번째 요청이 캐시를 생성합니다
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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-opus-4-8",
    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",
            },  # Cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

최상의 캐싱 성능을 위해 요청 간에 Skill 목록을 일관되게 유지하세요.

오류 처리

Skill 관련 오류를 적절하게 처리하세요:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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 작성을 위한 모범 사례

코드 실행 도구

코드 실행 환경에 대해 알아보기

Was this page helpful?

빠른 링크

개요

Skill 사용하기

사전 요구 사항

Messages에서 Skill 사용하기

Container 매개변수

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

멀티턴 대화

장기 실행 작업

여러 Skill 사용하기

커스텀 Skill 관리하기

Skill 생성하기

Skill 목록 조회하기

Skill 조회하기

Skill 삭제하기

버전 관리

Skill이 로드되는 방식

사용 사례

조직용 Skill

개인용 Skill

예시: 재무 모델링

제한 및 제약 조건

요청 제한

환경 제약 조건

모범 사례

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

버전 관리 전략

프롬프트 캐싱 고려 사항

오류 처리

데이터 보존

다음 단계

빠른 링크

개요

Skill 사용하기

사전 요구 사항

Messages에서 Skill 사용하기

Container 매개변수

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

멀티턴 대화

장기 실행 작업

여러 Skill 사용하기

커스텀 Skill 관리하기

Skill 생성하기

Skill 목록 조회하기

Skill 조회하기

Skill 삭제하기

버전 관리

Skill이 로드되는 방식

사용 사례

조직용 Skill

개인용 Skill

예시: 재무 모델링

제한 및 제약 조건

요청 제한

환경 제약 조건

모범 사례

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

버전 관리 전략

프롬프트 캐싱 고려 사항

오류 처리

데이터 보존

다음 단계

빠른 링크

개요

Skill 사용하기

사전 요구 사항

Messages에서 Skill 사용하기

Container 매개변수

생성된 파일 다운로드하기

멀티턴 대화

장기 실행 작업

여러 Skill 사용하기

커스텀 Skill 관리하기

Skill 생성하기

Skill 목록 조회하기

Skill 조회하기

Skill 삭제하기

버전 관리

Skill이 로드되는 방식

사용 사례

조직용 Skill

개인용 Skill

예시: 재무 모델링

제한 및 제약 조건

요청 제한

환경 제약 조건

모범 사례

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

버전 관리 전략

프롬프트 캐싱 고려 사항

오류 처리

데이터 보존

다음 단계

빠른 링크

개요

Skill 사용하기

사전 요구 사항

Messages에서 Skill 사용하기

Container 매개변수

생성된 파일 다운로드하기

멀티턴 대화

장기 실행 작업

여러 Skill 사용하기

커스텀 Skill 관리하기

Skill 생성하기

Skill 목록 조회하기

Skill 조회하기

Skill 삭제하기

버전 관리

Skill이 로드되는 방식

사용 사례

조직용 Skill

개인용 Skill

예시: 재무 모델링

제한 및 제약 조건

요청 제한

환경 제약 조건

모범 사례

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

버전 관리 전략

프롬프트 캐싱 고려 사항

오류 처리

데이터 보존

다음 단계