Claude 가이드 #20: Agent Skills — Claude에게 전문 능력을 모듈처럼 끼워주기

이 글은 Claude API 공식 문서의 Agent Skills (Overview) 페이지를 정리한 글입니다. 원문: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview 마지막 확인: 2026-05-30

1. 한 줄 요약
#

Claude에게 “PowerPoint 만드는 법”, “Excel 정리하는 법” 같은 능력을 한 번 끼워두면 알아서 꺼내 쓰는 모듈 — 그게 Agent Skills입니다.

2. 무엇이고 왜 좋을까
#

서랍에 라벨이 붙은 매뉴얼함을 두는 것과 같습니다. Claude가 필요할 때만 해당 서랍을 열어 읽고, 안 쓰는 매뉴얼은 그대로 둡니다.

기존에는 “PPT를 만들어줘"라고 부탁할 때마다 “슬라이드 구성은 이렇게 하고, 표는 저렇게 넣어줘"를 매번 설명해야 했습니다. Agent Skills는 그 설명을 한 번 폴더에 정리해두면, Claude가 비슷한 부탁을 받았을 때 스스로 꺼내 읽고 적용합니다.

핵심 수치: 평소 메모리에는 Skill 이름과 설명만 약 100토큰(AI가 글자를 세는 단위)만 차지하고, 실제 본문은 필요할 때만 불러옵니다. 그래서 매뉴얼함을 수십 개 둬도 부담이 거의 없습니다.

미리 만들어진 능력으로 PowerPoint(pptx), Excel(xlsx), Word(docx), PDF 네 가지가 제공돼서, 별도 설정 없이 바로 쓸 수 있다는 점도 큰 장점입니다.

3. 이런 상황에서 써요
#

상황 1: 학생 — 강의자료를 PPT로 정리하고 싶을 때
#

기말 발표를 앞두고 강의 노트 30장을 PowerPoint로 옮겨야 하는 학생이 있다고 해보세요. 매번 “표지는 어떻게 만들고, 본문 슬라이드는 어떤 식으로 정리해줘"를 설명하다 보면 지칩니다.

PowerPoint Skill을 켜둔 상태에서 “강의 노트 내용을 발표 슬라이드로 만들어줘"라고만 부탁하면, Claude가 알아서 표지·목차·본문·요약 슬라이드를 갖춘 파일을 만들어 줍니다. “슬라이드 구성 규칙"이라는 매뉴얼함을 Claude가 미리 읽어둔 셈이죠.

상황 2: 직장인 — 사내 보고용 Excel 보고서를 만들 때
#

영업 담당자가 한 달 매출 데이터를 정리해 매월 같은 형식의 Excel 보고서를 만들고 있다고 해보세요. 매번 “A열은 날짜, B열은 매출, 표 아래엔 합계와 그래프"를 설명하는 것이 번거롭습니다.

Excel Skill이 켜져 있으면, 데이터를 붙여 넣고 “지난달 형식대로 보고서 만들어줘"만 해도 일관된 결과가 나옵니다. 회사 표준에 맞춘 나만의 보고서 양식을 직접 만들어 등록해두는 것도 가능합니다.

상황 3: 일반인 — 책 한 권을 정리해 PDF로 남기고 싶을 때
#

독서 모임에서 두꺼운 책을 읽고, 챕터별 요약과 인용문을 깔끔한 PDF로 정리해 친구들에게 나눠주고 싶은 분이 있다고 해보세요.

PDF Skill을 켜두면 “이 책 내용을 챕터별로 정리해서 PDF로 만들어줘. 인용문은 회색 박스로"라고만 부탁해도 글씨 크기와 여백이 정돈된 문서가 만들어집니다. 매번 형식을 다시 설명하지 않아도 되는 게 큰 차이입니다.

4. 가볍게 시작하기
#

💻 개발 경험 있으신가요? 아래 코드는 Python으로 PDF 만드는 Skill을 켜는 가장 짧은 예시입니다. 비개발자라면 “이렇게 부르는구나” 정도로 보고 넘어가셔도 좋습니다. claude.ai 사이트에서는 코드 없이 설정만 켜면 바로 쓸 수 있습니다.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    # 아래 세 줄이 핵심 — Skills를 켜기 위한 베타 헤더입니다
    extra_headers={
        "anthropic-beta": "code-execution-2025-08-25,skills-2025-10-02,files-api-2025-04-14"
    },
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    # 이 한 줄로 미리 만들어진 PDF Skill을 끼웁니다
    container={"skills": [{"type": "anthropic", "skill_id": "pdf"}]},
    messages=[{
        "role": "user",
        "content": "독후감 한 편을 PDF로 만들어줘. 제목, 본문, 마무리 인용으로."
    }]
)
print(response.content)

핵심은 container 안의 skill_id입니다. “pdf"라고 적어두면 Claude가 PDF 만드는 매뉴얼을 알아서 꺼내 읽습니다. pptx, xlsx, docx로 바꾸면 각각 PowerPoint, Excel, Word가 켜집니다. 코드 실행 도구(code_execution)도 같이 켜줘야 결과 파일이 만들어진다는 점만 기억해두세요.

5. 흔한 오해와 함정
#

⚠️ 함정 1: “Skill만 켜면 알아서 다 잘 하지 않나요?”
#

Claude가 Skill을 꺼내 쓰려면 “언제 써야 하는지"를 알려주는 설명이 잘 적혀 있어야 합니다. 미리 제공되는 PPT·Excel·Word·PDF는 설명이 잘 준비되어 있지만, 직접 만든 Skill은 설명이 부실하면 Claude가 “지금 이걸 써야 하나?“를 판단하지 못해 그냥 지나가 버립니다.

❌ “문서 처리” ✅ “회사 월간 매출 보고서를 만들 때 사용. 사용자가 매출, 보고서, 월간 정리를 언급하면 적용”

⚠️ 함정 2: “한 곳에 만들어두면 다른 곳에서도 쓸 수 있죠?”
#

아쉽지만 그렇지 않습니다. claude.ai에 올린 Skill은 API에서 따로 보이지 않고, API에 올린 Skill은 claude.ai에서 안 보입니다. Claude Code도 별도입니다. 같은 Skill을 여러 곳에서 쓰고 싶다면 각각 따로 등록해야 합니다.

처음엔 한 곳(예: claude.ai)에서만 써보고, 익숙해지면 다른 곳으로 옮기는 식이 편합니다.

⚠️ 함정 3: “출처를 모르는 Skill, 그냥 받아 써도 괜찮을까요?”
#

Skill은 Claude에게 새로운 능력과 실행 권한을 주는 도구입니다. 그래서 출처가 불분명한 Skill을 그대로 받아 쓰면, 의도치 않은 동작(예: 파일을 외부로 보내거나, 엉뚱한 명령을 실행)이 일어날 수 있습니다.

소프트웨어를 설치하는 것과 같다고 생각하시면 됩니다. 본인이 만든 것 또는 Anthropic이 제공한 공식 Skill부터 시작하세요. 외부에서 받은 것은 폴더 안 파일을 꼭 한 번 열어 보고 쓰시는 것이 안전합니다.

6. 한 단계 더 (관심 있는 분만)
#

🎯 여기까지 오신 분 환영합니다. 이 섹션은 더 깊이 알고 싶으신 분을 위한 보너스입니다. 본문만 읽으셔도 충분합니다.

Skill의 구조를 한 번만 들여다보면, 직접 만드는 것도 의외로 어렵지 않습니다. Skill은 하나의 폴더 + SKILL.md 파일이 전부입니다.

예를 들어 “독후감 정리"라는 나만의 Skill을 만든다면 이런 구조가 됩니다.

my-bookreport-skill/
├── SKILL.md          ← 이 파일이 핵심 (아래처럼 적습니다)
├── TEMPLATES.md      ← 양식 모음 (필요할 때만 읽힘)
└── examples/         ← 참고용 예시 폴더

SKILL.md의 앞부분은 이렇게 생겼습니다.

---
name: bookreport-helper
description: 책 한 권을 읽고 독후감을 만들 때 사용. 사용자가 "독후감", "책 정리", "감상문"을 언급하면 적용
---

# 독후감 도우미

## 작성 순서
1. 책 제목과 저자 확인
2. 핵심 메시지 3가지 추출
3. 인상 깊은 인용문 2개 선정
4. 감상은 솔직하고 짧게

자세한 양식은 TEMPLATES.md를 참고하세요.

핵심은 위쪽 --- 사이의 이름(name) 과 설명(description) 입니다. Claude는 평소엔 이 설명만 기억하고 있다가, 사용자의 요청이 설명과 맞을 때 본문을 읽어옵니다. 이게 단계별 펼치기(progressive disclosure) — 필요할 때만 자료를 펼친다는 개념입니다. 매뉴얼함이 수십 개여도 부담이 없는 이유가 여기 있습니다.

처음 만들 때는 한 가지 작업만 정확히 처리하는 작은 Skill부터 시작하시는 것을 추천드립니다.

7. 한 마디
#

처음에는 “Skill? 매뉴얼함? 너무 어려워 보이는데"라고 느끼실 수 있습니다. 하지만 실제로 해보시면 폴더 하나에 메모 한 장 적어두는 일과 크게 다르지 않습니다. 미리 만들어진 PPT·Excel·Word·PDF 네 가지만 켜서 써보셔도 일상 작업이 많이 가벼워집니다.

만약 Claude가 Skill을 잘 안 꺼내 쓰는 것 같다면, 함정 1번(설명이 모호하지 않은가)부터 점검해 보세요. 같은 폴더가 다른 곳에서 안 보인다면 함정 2번(곳마다 따로 등록)을 떠올리시면 됩니다.

다음 글에서는 #21 — Skills API, 직접 만든 Skill을 업로드하고 관리하는 방법을 더 부드럽게 풀어보겠습니다. 한 번 만들어두면 평생 쓰는 든든한 친구가 생기는 셈이에요.

Claude API 공식 문서를 한국어로 풀어쓴 시리즈입니다. 원문 정확성이 가장 우선, 의역과 친근함은 그 위에서.