API에서 Agent Skills 시작하기

이 튜토리얼에서는 Agent Skills를 사용하여 PowerPoint 프레젠테이션을 만드는 방법을 보여줍니다. Skills를 활성화하고, 간단한 요청을 보내고, 생성된 파일에 접근하는 방법을 배우게 됩니다.

사전 요구 사항

Claude API 키
Python 3.7+ 또는 curl 설치
API 요청에 대한 기본적인 이해

Agent Skills 개요

사전 구축된 Agent Skills는 문서 생성, 데이터 분석, 파일 처리와 같은 작업을 위한 전문 지식으로 Claude의 기능을 확장합니다. Anthropic은 API에서 다음과 같은 사전 구축된 Agent Skills를 제공합니다:

PowerPoint (pptx): 프레젠테이션 생성 및 편집
Excel (xlsx): 스프레드시트 생성 및 분석
Word (docx): 문서 생성 및 편집
PDF (pdf): PDF 문서 생성

커스텀 Skills를 만들고 싶으신가요? 도메인별 전문 지식을 갖춘 자체 Skills를 구축하는 예제는 Agent Skills Cookbook을 참조하세요.

1단계: 사용 가능한 Skills 목록 조회

먼저 어떤 Skills를 사용할 수 있는지 확인하세요. Skills API를 사용하여 Anthropic에서 관리하는 모든 Skills를 나열합니다:

다음 Skills가 표시됩니다: pptx, xlsx, docx, pdf.

이 API는 각 Skill의 메타데이터(이름과 설명)를 반환합니다. Claude는 시작 시 이 메타데이터를 로드하여 어떤 Skills를 사용할 수 있는지 파악합니다. 이것이 **"progressive disclosure"(점진적 공개)**의 첫 번째 단계로, Claude가 전체 지침을 아직 로드하지 않고도 Skills를 발견하는 방식입니다.

2단계: 프레젠테이션 생성

이제 PowerPoint Skill을 사용하여 재생 에너지에 관한 프레젠테이션을 만들어 보세요. Messages API의 container 매개변수를 사용하여 Skills를 지정합니다:

각 부분이 수행하는 작업을 살펴보겠습니다:

container.skills: Claude가 사용할 수 있는 Skills를 지정합니다
type: "anthropic": Anthropic에서 관리하는 Skill임을 나타냅니다
skill_id: "pptx": PowerPoint Skill 식별자입니다
version: "latest": 가장 최근에 게시된 Skill 버전으로 설정됩니다
tools: 코드 실행을 활성화합니다(Skills에 필수)
베타 헤더: code-execution-2025-08-25 및 skills-2025-10-02

여기 예제에서는 code_execution_20250825 도구 버전과 이에 대응하는 code-execution-2025-08-25 베타 헤더를 사용합니다. Skills는 더 최신 코드 실행 도구 리비전(code_execution_20260120 이상)에서도 작동하며, 모든 코드 실행 도구 버전이 Skills 요구 사항을 충족합니다. 어떤 버전을 사용하든 해당 도구의 type과 베타 헤더를 코드 실행 도구 페이지와 일관되게 유지하고, 항상 skills-2025-10-02를 포함하세요.

이 요청을 보내면 Claude는 자동으로 작업을 관련 Skill과 매칭합니다. 프레젠테이션을 요청했으므로 Claude는 PowerPoint Skill이 관련 있다고 판단하고 전체 지침을 로드합니다. 이것이 점진적 공개의 두 번째 단계입니다. 그런 다음 Claude는 Skill의 코드를 실행하여 프레젠테이션을 생성합니다.

3단계: 생성된 파일 다운로드

프레젠테이션은 코드 실행 컨테이너에서 생성되어 파일로 저장되었습니다. 응답에는 파일 ID가 포함된 파일 참조가 있습니다. 파일 ID를 추출하고 Files API를 사용하여 다운로드하세요:

생성된 파일 작업에 대한 자세한 내용은 코드 실행 도구 문서를 참조하세요.

더 많은 예제 시도하기

Skills로 첫 번째 문서를 생성했으니 이제 다음 변형을 시도해 보세요:

스프레드시트 생성

Word 문서 생성

PDF 생성

다음 단계

사전 구축된 Agent Skills를 사용해 보았으니 이제 다음을 수행할 수 있습니다:

API 가이드

Claude API로 Skills 사용하기

커스텀 Skills 생성

특수 작업을 위한 자체 Skills 업로드하기

작성 가이드

효과적인 Skills 작성을 위한 모범 사례 알아보기

Claude Code에서 Skills 사용

# PowerPoint Skill로 메시지 생성
response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    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 with 5 slides",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(f"stop_reason={response.stop_reason}, blocks={len(response.content)}")

# 코드 실행 도구 결과에서 파일 ID를 추출합니다. Skill은 Python 또는
# bash 코드 실행 도구 중 하나로 작업을 실행할 수 있으므로
# 두 결과 유형을 모두 확인합니다.
file_id = None
for block in response.content:
    if block.type == "code_execution_tool_result":
        if block.content.type == "code_execution_result":
            for output in block.content.content:
                file_id = output.file_id
    elif block.type == "bash_code_execution_tool_result":
        if block.content.type == "bash_code_execution_result":
            for output in block.content.content:
                file_id = output.file_id

if file_id:
    # 파일을 다운로드하고 저장
    output_path = Path(tempfile.gettempdir()) / "renewable_energy.pptx"
    file_content = client.beta.files.download(file_id=file_id)
    file_content.write_to_file(output_path)
    print(f"Presentation saved to {output_path}")

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    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 quarterly sales tracking spreadsheet with sample data",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "docx", "version": "latest"}]
    },
    messages=[
        {
            "role": "user",
            "content": "Write a 2-page report on the benefits of renewable energy",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "pdf", "version": "latest"}]
    },
    messages=[
        {
            "role": "user",
            "content": "Generate a PDF invoice template",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

사전 요구 사항

Agent Skills 개요

1단계: 사용 가능한 Skills 목록 조회

2단계: 프레젠테이션 생성

3단계: 생성된 파일 다운로드

더 많은 예제 시도하기

스프레드시트 생성

Word 문서 생성

PDF 생성

다음 단계

사전 요구 사항

Agent Skills 개요

1단계: 사용 가능한 Skills 목록 조회

2단계: 프레젠테이션 생성

3단계: 생성된 파일 다운로드

더 많은 예제 시도하기

스프레드시트 생성

Word 문서 생성

PDF 생성

다음 단계