Claude Agent Skills - Skill 이해와 사용법

들어가며

Claude API를 처음 사용할 때 대부분의 개발자는 시스템 프롬프트에 배경지식을 쭉 적어 넣습니다. "너는 PDF 전처리 전문가야. 이 라이브러리를 쓰고, 이런 순서로 처리해야 해…" 같은 식으로요. 이 방법은 처음엔 잘 동작하지만, 결국 한계가 옵니다.

지식이 많아질수록 프롬프트는 길어지고, 길어진 프롬프트는 컨텍스트 윈도우를 잠식합니다. 게다가 여러 프로젝트에서 같은 내용을 복붙하다 보면 관리도 엉망이 되죠.

Agent Skills는 이 문제를 해결하기 위해 Anthropic이 설계한 구조입니다. 한 번 만들어두면 Claude가 필요할 때 알아서 꺼내 씁니다.

Agent Skills가 뭔가요?

Agent Skills는 Claude에게 도메인 특화 지식을 제공하는 파일 시스템 기반 모듈입니다. 쉽게 말하면, "이 작업을 할 때는 이 가이드북을 참고해"라고 Claude에게 알려주는 구조예요.

핵심 아이디어: 프롬프트는 그때그때 주어지는 일회성 지시입니다. 반면 Skills는 상시 대기 중인 전문 지식이에요. Claude가 관련 요청을 받으면 그때 꺼내 씁니다.

공식 문서에서는 Skills를 이렇게 설명합니다. "새로 입사한 팀원에게 작성해주는 온보딩 가이드처럼" 구성한다고요. 역할, 절차, 예시, 도구 사용법이 담긴 폴더를 하나 만들어두면 Claude가 그걸 읽고 전문가처럼 동작합니다.

기존 방식과 무엇이 다른가요?

가장 큰 차이는 지식이 로드되는 시점입니다.

기존 방식 — 시스템 프롬프트

모든 지식을 대화 시작부터 컨텍스트에 올립니다. 쓰지 않을 정보도 항상 자리를 차지하죠.

Agent Skills

필요한 순간에만 해당 Skill을 읽어옵니다. 안 쓰는 지식은 컨텍스트를 소비하지 않아요.

이 구조를 공식 문서에서는 Progressive Disclosure(점진적 공개)라고 부릅니다. 3단계로 나눠서 설명할 수 있어요.

Progressive Disclosure — 3단계 구조

L1메타

항상 로드됨 — Skill 이름 + 설명 (~100 토큰)

Claude는 어떤 Skills가 있는지만 미리 알고 있습니다. 내용은 아직 로드하지 않아요.

L2지시

요청이 매칭될 때 로드됨 — SKILL.md 본문 (5,000 토큰 이하)

관련 요청이 들어오면 SKILL.md 파일을 읽어 실제 지식을 컨텍스트에 올립니다.

L3리소스

필요할 때만 로드됨 — 추가 문서 + 스크립트 (사실상 무제한)

추가 마크다운 파일이나 스크립트는 Claude가 직접 필요하다고 판단할 때만 읽습니다.

실제로 어떻게 동작하나요?

Claude가 "이 PDF에서 텍스트 추출해줘"라는 요청을 받았을 때 내부적으로 어떤 일이 일어나는지 따라가봅시다.

Step 1 · 시작 시 시스템 프롬프트에 Skills 목록 로드 (이름 + 설명만, L1)

↓

Step 2 · 요청 수신 "이 PDF에서 텍스트 추출해줘"

↓

Step 3 · Skill 트리거 PDF 관련 Skill 감지 → bash로 SKILL.md 읽기 (L2)

↓

Step 4 · 선택적 로드 폼 작성은 불필요 → FORMS.md는 읽지 않음 (L3 스킵)

↓

Step 5 · 실행 SKILL.md 지시에 따라 작업 완료

중요한 점은, Claude가 가상 머신의 파일 시스템에 접근해서 bash 명령으로 파일을 직접 읽는다는 겁니다. Skills는 단순한 텍스트 설정이 아니라, 실행 가능한 스크립트까지 포함할 수 있는 실제 디렉토리입니다.

SKILL.md 파일은 어떻게 생겼나요?

모든 Skill은 SKILL.md 파일 하나에서 시작합니다. 구조는 생각보다 단순합니다.

SKILL.md Markdown + YAML Frontmatter

---
name: pdf-processing
description: Extract text and tables from PDF files,
  fill forms, merge documents.
  Use when working with PDF files or when the user
  mentions PDFs, forms, or document extraction.
---

# PDF Processing Skill

## 빠른 시작

텍스트 추출에는 pdfplumber를 사용합니다:

```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## 폼 작성이 필요하다면

자세한 내용은 [FORMS.md](FORMS.md)를 참고하세요.
(복잡한 폼 작성 시에만 이 파일을 읽습니다)

YAML frontmatter의 description 필드가 핵심입니다. Claude는 이 설명을 보고 "이 Skill을 지금 써야 하는가?"를 판단합니다. 언제 써야 하는지를 명확히 적는 것이 가장 중요합니다.

name 필드 규칙

name 필드 규칙 YAML

# ✅ 올바른 예시
name: pdf-processing        # 소문자, 숫자, 하이픈만 허용
name: data-export-tool      # 최대 64자

# ❌ 잘못된 예시
name: PDF_Processing         # 대문자·언더스코어 불가
name: claude-pdf-tool        # 'claude' 예약어
name: anthropic-helper       # 'anthropic' 예약어

Skill 디렉토리 구조

단순한 작업이라면 SKILL.md 하나로 충분합니다. 하지만 복잡한 도메인이라면 파일을 나눠서 관리할 수 있어요.

Skill 폴더 구조 예시 Directory

pdf-skill/
├── SKILL.md          # 핵심 지시 (항상 먼저 읽힘)
├── FORMS.md          # 폼 작성 상세 가이드 (필요할 때만)
├── REFERENCE.md      # API 레퍼런스 (필요할 때만)
└── scripts/
    └── fill_form.py  # 실행 스크립트 (결과만 컨텍스트에 올라옴)

스크립트의 장점: Claude가 fill_form.py를 실행하면, 스크립트 코드 자체는 컨텍스트에 올라오지 않습니다. 실행 결과만 올라와요. 반복적이고 정형화된 로직을 스크립트로 빼면 컨텍스트를 크게 절약할 수 있습니다.

어디서 사용할 수 있나요?

Agent Skills는 Anthropic의 여러 제품에서 사용할 수 있습니다. 각 환경마다 특징이 조금씩 다릅니다.

환경	사용 방법	특이사항
Claude API	container 파라미터에 skill_id 지정	베타 헤더 3개 필요. 기본 제공 Skills(PDF·Excel·Word 등) 즉시 사용 가능. 커스텀 Skill은 /v1/skills로 업로드.
Claude.ai	설정 → Features에서 업로드	Pro·Max·Team·Enterprise 플랜 한정. 현재 개인 단위 공유만 지원.
Claude Code / Agent SDK	.claude/skills/ 폴더에 배치	파일 시스템 기반 자동 인식. 네트워크 접근 자유로움.

API 요청 예시

api_example.py Python

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[{"role": "user", "content": "이 PDF에서 텍스트를 추출해줘"}],
    container={"type": "auto", "skill_ids": ["pdf-processing"]},
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "files-api-2025-04-14",
    ],
)

알아두면 좋은 제약 사항

Cross-surface 동기화 없음: Claude.ai에 업로드한 Skill은 API에서 자동으로 사용할 수 없습니다. 환경마다 별도 관리가 필요해요.

API 환경에서 네트워크 접근 제한: 외부 API 호출이나 인터넷 접근이 막혀 있습니다. 미리 설치된 패키지만 사용할 수 있어요.

Claude.ai 커스텀 Skill은 개인 단위: 팀 전체에 동일한 Skill을 배포하려면 각자 업로드해야 합니다.

정리하며

Agent Skills는 단순한 편의 기능이 아닙니다. 프롬프트를 코드처럼 관리하고, AI의 전문 지식을 모듈화해서 재사용할 수 있는 구조입니다.

팀 단위로 Claude를 활용하거나, 특정 도메인에서 일관된 동작이 필요하다면 시스템 프롬프트 대신 Skills 도입을 진지하게 고려해볼 만 합니다.

핵심 정리

• Agent Skills = 재사용 가능한 지식 모듈. 한 번 만들면 여러 대화에서 자동으로 활용됩니다.
• Progressive Disclosure로 컨텍스트 절약. 필요한 순간에만 해당 정보를 로드합니다.
• SKILL.md의 description 필드가 핵심. Claude가 언제 이 Skill을 써야 하는지 판단하는 기준입니다.
• 스크립트까지 번들링 가능. 실행 결과만 컨텍스트에 올라와 토큰 효율이 높습니다.
• 환경마다 별도 관리 필요. API, Claude.ai, Claude Code 간 자동 동기화는 없습니다.