스킬

API를 통한 Agent Skills 사용

API를 통해 Agent Skills를 사용하여 Claude의 기능을 확장하는 방법을 알아봅니다.

Agent Skills는 조직화된 지침, 스크립트 및 리소스 폴더를 통해 Claude의 기능을 확장합니다. 이 가이드는 Claude API와 함께 사전 구축된 Skills와 사용자 정의 Skills를 모두 사용하는 방법을 보여줍니다.

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

Skill Management API Reference - Skills의 CRUD 작업
Skill Versions API Reference - 버전 관리

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

빠른 링크

Agent Skills 시작하기

첫 번째 Skill 만들기

사용자 정의 Skills 만들기

Skills 작성을 위한 모범 사례

개요

Agent Skills의 아키텍처 및 실제 응용 프로그램에 대한 심층 분석은 엔지니어링 블로그 게시물을 읽으세요: Equipping agents for the real world with Agent 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`	Epoch 타임스탬프: `1759178010641129` 또는 `latest`
관리	Anthropic에서 사전 구축 및 유지 관리	Skills API를 통해 업로드 및 관리
가용성	모든 사용자가 사용 가능	워크스페이스에 비공개

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

전제 조건

Skills를 사용하려면 다음이 필요합니다:

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

Messages에서 Skills 사용

Container 매개변수

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

구조는 Anthropic과 사용자 정의 Skills 모두에 대해 동일합니다. 필수 type 및 skill_id를 지정하고, 선택적으로 version을 포함하여 특정 버전으로 고정합니다:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a presentation about renewable energy"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

생성된 파일 다운로드

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

작동 방식:

Skills는 코드 실행 중에 파일을 생성합니다
응답에는 생성된 각 파일에 대한 file_id가 포함됩니다
Files API를 사용하여 실제 파일 콘텐츠를 다운로드합니다
로컬에 저장하거나 필요에 따라 처리합니다

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

추가 Files API 작업:

client = anthropic.Anthropic()
file_id = "file_abc123"
# 파일 메타데이터 가져오기
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"])

Files API에 대한 전체 세부 정보는 Files API 문서를 참조하세요.

다중 턴 대화

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

# 첫 번째 요청이 컨테이너를 생성합니다
response1 = client.beta.messages.create(
    model="claude-opus-4-7",
    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-7",
    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"}],
)

장기 실행 작업

스킬은 여러 턴이 필요한 작업을 수행할 수 있습니다. pause_turn 중지 이유를 처리합니다:

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

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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-7",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ],
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )

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

여러 Skills 사용

단일 요청에서 여러 Skills을 결합하여 복잡한 워크플로우를 처리합니다:

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

커스텀 Skills 관리

Skill 생성

커스텀 Skill을 업로드하여 워크스페이스에서 사용 가능하게 만듭니다. 디렉토리 경로 또는 개별 파일 객체를 사용하여 업로드할 수 있습니다.

# Option 1: Upload individual files (one --file flag per file)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Option 2: Upload a zip archive
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 태그 없음

전체 요청/응답 스키마는 Skill 생성 API 참조를 참조하세요.

Skills 나열

워크스페이스에서 사용 가능한 모든 Skills를 검색합니다. 여기에는 Anthropic 사전 구축 Skills과 커스텀 Skills이 포함됩니다. source 매개변수를 사용하여 Skill 유형으로 필터링합니다:

# List all Skills
ant beta:skills list

# List only custom Skills
ant beta:skills list --source custom

페이지 매김 및 필터링 옵션은 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 --format yaml \
  | tr -d '"' \
  | 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 오류가 반환됩니다.

버전 관리

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

Anthropic 관리 Skills:

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

사용자 정의 Skills:

자동 생성된 epoch 타임스탬프: 1759178010641129
"latest"를 사용하여 항상 최신 버전을 가져옵니다
Skill 파일을 업데이트할 때 새 버전을 생성합니다

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

# 특정 버전 사용
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-7
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-7
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

전체 세부 사항은 Skill 버전 생성 API 참조를 참조하세요.

Skills가 로드되는 방식

컨테이너에서 Skills를 지정할 때:

메타데이터 검색: Claude는 시스템 프롬프트에서 각 Skill의 메타데이터(이름, 설명)를 봅니다
파일 로드: Skill 파일이 /skills/{directory}/의 컨테이너에 복사됩니다
자동 사용: Claude는 요청과 관련이 있을 때 자동으로 Skills를 로드하고 사용합니다
구성: 여러 Skills가 복잡한 워크플로우를 위해 함께 구성됩니다

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

사용 사례

조직 Skills

브랜드 및 커뮤니케이션

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

프로젝트 관리

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

비즈니스 운영

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

개인 Skills

콘텐츠 생성

사용자 정의 문서 템플릿
특화된 형식 및 스타일
도메인별 콘텐츠 생성

데이터 분석

사용자 정의 데이터 처리 파이프라인
특화된 시각화 템플릿
업계별 분석 방법

개발 및 자동화

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

예제: 재무 모델링

Excel과 맞춤형 DCF 분석 Skills 결합:

# Create custom DCF analysis 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"],
)

# Use with Excel to create financial model
response = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
)

제한 사항 및 제약

요청 제한

요청당 최대 Skills 수: 8
최대 Skill 업로드 크기: 30 MB (모든 파일 합계)
YAML 프론트매터 요구사항:
- name: 최대 64자, 소문자/숫자/하이픈만 사용, XML 태그 없음, 예약어 없음
- description: 최대 1024자, 비어있지 않음, XML 태그 없음

환경 제약

Skills는 코드 실행 컨테이너에서 다음 제한사항과 함께 실행됩니다:

네트워크 액세스 없음 - 외부 API 호출 불가
런타임 패키지 설치 없음 - 사전 설치된 패키지만 사용 가능
격리된 환경 - 각 요청은 새로운 컨테이너를 받음

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

모범 사례

여러 Skills를 사용하는 경우

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

좋은 사용 사례:

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

피해야 할 사항:

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

버전 관리 전략

프로덕션의 경우:

# Pin to specific versions for stability
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",  # Specific version
        }
    ]
}

개발의 경우:

# Use latest for active development
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # Always get newest
        }
    ]
}

프롬프트 캐싱 고려사항

프롬프트 캐싱을 사용할 때, 컨테이너의 Skills 목록을 변경하면 캐시가 깨집니다:

# First request creates cache
response1 = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
)

# Adding/removing Skills breaks cache
response2 = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
)

최적의 캐싱 성능을 위해 요청 전체에서 Skills 목록을 일관되게 유지하세요.

오류 처리

Skill 관련 오류를 우아하게 처리합니다:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        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}")
        # Handle skill-specific errors
    else:
        raise

데이터 보관

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

모든 기능에 걸친 ZDR 적격성을 위해 API 및 데이터 보관을 참조하세요.

다음 단계

API 참조

모든 엔드포인트가 포함된 완전한 API 참조

작성 가이드

효과적인 Skills 작성을 위한 모범 사례

코드 실행 도구

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

Was this page helpful?

스킬

API를 통한 Agent Skills 사용

API를 통해 Agent Skills를 사용하여 Claude의 기능을 확장하는 방법을 알아봅니다.

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

Skill Management API Reference - Skills의 CRUD 작업
Skill Versions API Reference - 버전 관리

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

빠른 링크

Agent Skills 시작하기

첫 번째 Skill 만들기

사용자 정의 Skills 만들기

Skills 작성을 위한 모범 사례

개요

Agent Skills의 아키텍처 및 실제 응용 프로그램에 대한 심층 분석은 엔지니어링 블로그 게시물을 읽으세요: Equipping agents for the real world with Agent Skills.

Skills 사용

두 가지 소스에서 Skills를 사용할 수 있습니다:

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

전제 조건

Skills를 사용하려면 다음이 필요합니다:

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

Messages에서 Skills 사용

Container 매개변수

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a presentation about renewable energy"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

생성된 파일 다운로드

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

작동 방식:

Skills는 코드 실행 중에 파일을 생성합니다
응답에는 생성된 각 파일에 대한 file_id가 포함됩니다
Files API를 사용하여 실제 파일 콘텐츠를 다운로드합니다
로컬에 저장하거나 필요에 따라 처리합니다

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

추가 Files API 작업:

client = anthropic.Anthropic()
file_id = "file_abc123"
# 파일 메타데이터 가져오기
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"])

Files API에 대한 전체 세부 정보는 Files API 문서를 참조하세요.

다중 턴 대화

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

# 첫 번째 요청이 컨테이너를 생성합니다
response1 = client.beta.messages.create(
    model="claude-opus-4-7",
    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-7",
    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"}],
)

장기 실행 작업

스킬은 여러 턴이 필요한 작업을 수행할 수 있습니다. pause_turn 중지 이유를 처리합니다:

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

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

여러 Skills 사용

단일 요청에서 여러 Skills을 결합하여 복잡한 워크플로우를 처리합니다:

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

커스텀 Skills 관리

Skill 생성

커스텀 Skill을 업로드하여 워크스페이스에서 사용 가능하게 만듭니다. 디렉토리 경로 또는 개별 파일 객체를 사용하여 업로드할 수 있습니다.

# Option 1: Upload individual files (one --file flag per file)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Option 2: Upload a zip archive
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 태그 없음

전체 요청/응답 스키마는 Skill 생성 API 참조를 참조하세요.

Skills 나열

# List all Skills
ant beta:skills list

# List only custom Skills
ant beta:skills list --source custom

페이지 매김 및 필터링 옵션은 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 --format yaml \
  | tr -d '"' \
  | 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 오류가 반환됩니다.

버전 관리

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

Anthropic 관리 Skills:

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

사용자 정의 Skills:

자동 생성된 epoch 타임스탬프: 1759178010641129
"latest"를 사용하여 항상 최신 버전을 가져옵니다
Skill 파일을 업데이트할 때 새 버전을 생성합니다

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

# 특정 버전 사용
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-7
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-7
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

전체 세부 사항은 Skill 버전 생성 API 참조를 참조하세요.

Skills가 로드되는 방식

컨테이너에서 Skills를 지정할 때:

메타데이터 검색: Claude는 시스템 프롬프트에서 각 Skill의 메타데이터(이름, 설명)를 봅니다
파일 로드: Skill 파일이 /skills/{directory}/의 컨테이너에 복사됩니다
자동 사용: Claude는 요청과 관련이 있을 때 자동으로 Skills를 로드하고 사용합니다
구성: 여러 Skills가 복잡한 워크플로우를 위해 함께 구성됩니다

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

사용 사례

조직 Skills

브랜드 및 커뮤니케이션

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

프로젝트 관리

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

비즈니스 운영

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

개인 Skills

콘텐츠 생성

사용자 정의 문서 템플릿
특화된 형식 및 스타일
도메인별 콘텐츠 생성

데이터 분석

사용자 정의 데이터 처리 파이프라인
특화된 시각화 템플릿
업계별 분석 방법

개발 및 자동화

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

예제: 재무 모델링

Excel과 맞춤형 DCF 분석 Skills 결합:

# Create custom DCF analysis 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"],
)

# Use with Excel to create financial model
response = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
)

제한 사항 및 제약

요청 제한

요청당 최대 Skills 수: 8
최대 Skill 업로드 크기: 30 MB (모든 파일 합계)
YAML 프론트매터 요구사항:
- name: 최대 64자, 소문자/숫자/하이픈만 사용, XML 태그 없음, 예약어 없음
- description: 최대 1024자, 비어있지 않음, XML 태그 없음

환경 제약

Skills는 코드 실행 컨테이너에서 다음 제한사항과 함께 실행됩니다:

네트워크 액세스 없음 - 외부 API 호출 불가
런타임 패키지 설치 없음 - 사전 설치된 패키지만 사용 가능
격리된 환경 - 각 요청은 새로운 컨테이너를 받음

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

모범 사례

여러 Skills를 사용하는 경우

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

좋은 사용 사례:

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

피해야 할 사항:

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

버전 관리 전략

프로덕션의 경우:

# Pin to specific versions for stability
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",  # Specific version
        }
    ]
}

개발의 경우:

# Use latest for active development
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # Always get newest
        }
    ]
}

프롬프트 캐싱 고려사항

프롬프트 캐싱을 사용할 때, 컨테이너의 Skills 목록을 변경하면 캐시가 깨집니다:

# First request creates cache
response1 = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
)

# Adding/removing Skills breaks cache
response2 = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
)

최적의 캐싱 성능을 위해 요청 전체에서 Skills 목록을 일관되게 유지하세요.

오류 처리

Skill 관련 오류를 우아하게 처리합니다:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        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}")
        # Handle skill-specific errors
    else:
        raise

데이터 보관

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

모든 기능에 걸친 ZDR 적격성을 위해 API 및 데이터 보관을 참조하세요.

다음 단계

API 참조

모든 엔드포인트가 포함된 완전한 API 참조

작성 가이드

효과적인 Skills 작성을 위한 모범 사례

코드 실행 도구

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

Was this page helpful?