Tutorials

Claude Agent Skills API 가이드: Claude API에서 Skills 사용하기

Claude Agent Skills API 가이드 — Agent Skills를 Claude API와 함께 사용하는 방법을 알아보세요. Python, TypeScript, cURL 코드 예제가 포함된 완벽한 Claude Agent Skills API 가이드입니다.

AnthropicOctober 16, 202518 min read
#agent-skills#claude-api#python#typescript#code-examples
Claude Agent Skills API

이 글은 Anthropic의 공식 문서 Using Agent Skills with the API를 기반으로 작성되었습니다.

Claude Agent Skills API는 체계적으로 구성된 지침, 스크립트, 리소스 폴더를 통해 Claude의 기능을 확장합니다. 이 Claude Agent Skills API 가이드에서는 미리 만들어진 Agent Skills와 커스텀 Agent Skills를 Claude API와 함께 사용하는 방법을 보여드립니다.

Claude Agent Skills API 개요

Claude Agent Skills API는 코드 실행 도구를 통해 Messages API와 통합됩니다. Anthropic에서 관리하는 미리 만들어진 Agent Skills를 사용하든, 직접 업로드한 커스텀 Agent Skills를 사용하든, Claude Agent Skills API 통합 방식은 동일합니다 — 둘 다 코드 실행이 필요하며 동일한 container 구조를 사용합니다.

Claude Agent Skills API 아키텍처 및 통합 흐름
Claude Agent Skills API 아키텍처 및 통합 흐름

Claude Agent Skills API: Anthropic Skills vs 커스텀 Skills

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

Claude Agent Skills API 사전 요구 사항

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

  1. Anthropic API 키 (Console에서 발급)
  2. Beta 헤더:
    • code-execution-2025-08-25 - 코드 실행 활성화 (Skills에 필수)
    • skills-2025-10-02 - Skills API 활성화
    • files-api-2025-04-14 - 컨테이너에서 파일 업로드/다운로드
  3. 코드 실행 도구가 요청에 활성화되어 있어야 함

Claude API에서 Agent Skills 사용하기

Container 파라미터

Claude Agent Skills API에서 Agent Skills는 Messages API의 container 파라미터를 사용하여 지정됩니다. 요청당 최대 8개의 Agent Skills를 포함할 수 있습니다.

import anthropic

client = anthropic.Anthropic()

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

TypeScript 동일 코드:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

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

생성된 파일 다운로드

Skills가 문서를 생성하면 응답에 file_id 속성이 반환됩니다. Files API를 사용하여 이 파일을 다운로드하세요:

  1. Skills가 코드 실행 중 파일을 생성합니다
  2. 응답에 생성된 각 파일의 file_id가 포함됩니다
  3. Files API를 사용하여 실제 파일 내용을 다운로드합니다
# 1단계: Skill을 사용하여 파일 생성
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create an Excel file with a 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":
                for file in content_item.content:
                    if hasattr(file, "file_id"):
                        file_ids.append(file.file_id)
    return file_ids

# 3단계: 각 파일 다운로드
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(
        file_id=file_id, betas=["files-api-2025-04-14"]
    )
    file_content = client.beta.files.download(
        file_id=file_id, betas=["files-api-2025-04-14"]
    )
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

멀티턴 대화

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

# 첫 번째 요청이 컨테이너를 생성합니다
response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze this sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 동일한 컨테이너로 대화 계속
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # 컨테이너 재사용
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}],
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

장시간 실행 작업

Skills는 여러 턴이 필요한 작업을 수행할 수 있습니다. pause_turn stop reason을 처리하세요:

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

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "custom", "skill_id": "skill_01...", "version": "latest"}]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

for i in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.beta.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [{"type": "custom", "skill_id": "skill_01...", "version": "latest"}],
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )

여러 Skills 사용

단일 요청에서 여러 Skills를 결합하세요 (최대 8개):

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
            {"type": "custom", "skill_id": "skill_01...", "version": "latest"},
        ]
    },
    messages=[
        {"role": "user", "content": "Analyze sales data and create a presentation"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Claude API를 통한 커스텀 Agent Skills 관리

Agent Skill 생성

from anthropic.lib import files_from_dir

skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=files_from_dir("/path/to/financial_analysis_skill"),
    betas=["skills-2025-10-02"],
)

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")

zip 파일이나 개별 파일 튜플을 사용하여 업로드할 수도 있습니다:

# 옵션 2: zip 파일 사용
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
    betas=["skills-2025-10-02"],
)

# 옵션 3: 파일 튜플 사용
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[
        ("financial_skill/SKILL.md", open("financial_skill/SKILL.md", "rb"), "text/markdown"),
        ("financial_skill/analyze.py", open("financial_skill/analyze.py", "rb"), "text/x-python"),
    ],
    betas=["skills-2025-10-02"],
)

요구 사항:

  • 최상위 레벨에 SKILL.md 파일이 포함되어야 합니다
  • 모든 파일은 공통 루트 디렉토리를 지정해야 합니다
  • 총 업로드 크기는 8MB 미만이어야 합니다
  • name: 최대 64자, 소문자/숫자/하이픈만 가능
  • description: 최대 1024자, 비어있지 않아야 함

Skills 목록 조회

# 모든 Skills 목록 조회
skills = client.beta.skills.list(betas=["skills-2025-10-02"])
for skill in skills.data:
    print(f"{skill.id}: {skill.display_title} (source: {skill.source})")

# 커스텀 Skills만 목록 조회
custom_skills = client.beta.skills.list(source="custom", betas=["skills-2025-10-02"])

Skill 조회

skill = client.beta.skills.retrieve(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)
print(f"Skill: {skill.display_title}")
print(f"Latest version: {skill.latest_version}")

Skill 삭제

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

# 1단계: 모든 버전 삭제
versions = client.beta.skills.versions.list(
    skill_id="skill_01...", betas=["skills-2025-10-02"]
)
for version in versions.data:
    client.beta.skills.versions.delete(
        skill_id="skill_01...",
        version=version.version,
        betas=["skills-2025-10-02"],
    )

# 2단계: Skill 삭제
client.beta.skills.delete(
    skill_id="skill_01...", betas=["skills-2025-10-02"]
)

버전 관리

Skills는 안전한 업데이트를 위한 버전 관리를 지원합니다:

# 새 버전 생성
new_version = client.beta.skills.versions.create(
    skill_id="skill_01...",
    files=files_from_dir("/path/to/updated_skill"),
    betas=["skills-2025-10-02"],
)

# 프로덕션 안정성을 위해 특정 버전 사용
container = {
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01...",
        "version": "1759178010641129",  # 고정 버전
    }]
}

# 개발 중에는 latest 사용
container = {
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01...",
        "version": "latest",
    }]
}

Claude Agent Skills API의 Skills 로딩 방식

Claude Agent Skills API를 통해 컨테이너에 Agent Skills를 지정하면:

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

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

사용 사례

조직용 Skills

  • 브랜드 및 커뮤니케이션: 회사 고유의 서식 적용, 템플릿에 따른 커뮤니케이션 생성
  • 프로젝트 관리: 회사 고유의 형식으로 노트 구성, 표준화된 회의 요약 작성
  • 비즈니스 운영: 회사 표준 보고서 작성, 분석 절차 실행

개인용 Skills

  • 콘텐츠 생성: 커스텀 문서 템플릿, 전문 서식
  • 데이터 분석: 커스텀 데이터 처리 파이프라인, 전문 시각화
  • 개발: 코드 생성 템플릿, 테스트 프레임워크, 배포 워크플로

예시: 금융 모델링

Excel과 커스텀 DCF 분석 Skills를 결합하세요:

dcf_skill = client.beta.skills.create(
    display_title="DCF Analysis",
    files=files_from_dir("/path/to/dcf_skill"),
    betas=["skills-2025-10-02"],
)

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "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"}],
)

모범 사례

프롬프트 캐싱

컨테이너의 Skills 목록을 변경하면 프롬프트 캐시가 무효화됩니다. 최적의 캐싱 성능을 위해 요청 간에 Skills 목록을 일관되게 유지하세요.

버전 관리

  • 프로덕션: 안정성을 위해 특정 버전을 고정하세요
  • 개발: 활발한 반복 작업에는 "latest"를 사용하세요

오류 처리

try:
    response = client.beta.messages.create(...)
except anthropic.BadRequestError as e:
    if "skill" in str(e):
        print(f"Skill error: {e}")
    else:
        raise

Claude Agent Skills API 제한 사항 및 제약 조건

  • 요청당 최대 Agent Skills 수: 8개
  • 최대 Agent Skill 업로드 크기: 8MB (모든 파일 합산)
  • 실행 컨테이너에서 네트워크 접근 불가
  • 런타임 패키지 설치 불가 — 사전 설치된 패키지만 사용 가능
  • 격리된 환경 — 각 Claude Agent Skills API 요청은 새로운 컨테이너를 생성합니다

Skills in This Post

PDF ProcessorComprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documentsWord Document ProcessorComprehensive document creation, editing, and analysis with support for tracked changes and commentsPowerPoint ProcessorPresentation creation, editing, and analysis with support for layouts and speaker notesExcel Spreadsheet ProcessorComprehensive spreadsheet creation, editing, and analysis with support for formulas and data visualization

Related Posts

Agent Skills Best Practices: Complete Guide to Writing Effective Claude Skills
Tutorials

Agent Skills Best Practices: Complete Guide to Writing Effective Claude Skills

Agent skills best practices for writing effective Claude Skills. Learn agent skills best practices from core principles like conciseness and progressive disclosure to advanced patterns with executable code.

Anthropic
Oct 16, 202520 min read
agent-skillsbest-practicesskill-creation
AI Agent Memory and Tool Integration: Building Smarter Claude Skills Workflows
Tutorials

AI Agent Memory and Tool Integration: Building Smarter Claude Skills Workflows

Learn how to build AI agent workflows with persistent memory and tool integration using Claude Skills. Step-by-step guide to agent memory systems, tool coordination, and production-ready agent architectures.

Claude Skills Team
Mar 10, 20268 min read
agent-memorytool-integrationai-agents
Automate Code Quality: Write, Fix, and Review Tests with Claude Skills
Tutorials

Automate Code Quality: Write, Fix, and Review Tests with Claude Skills

Learn how to automate test writing, test fixing, and code review using Claude Skills. Practical guide with examples for teams using Claude Code in 2025.

Claude Skills Team
Mar 10, 202610 min read
testingcode-reviewautomation