개요

Skills를 사용하는 이유

Skills는 파일 시스템 기반의 재사용 가능한 리소스입니다. 워크플로, 맥락, 모범 사례 같은 도메인별 전문 지식을 Claude에 제공하여 범용 에이전트가 전문가처럼 일할 수 있게 합니다. 프롬프트가 한 번의 대화에서 쓰는 일회성 지침인 것과 달리, Skills는 필요할 때 로드되므로 여러 대화에서 같은 설명을 반복할 필요가 없습니다.

주요 장점:

• Claude 전문화: 특정 도메인 작업에 맞게 능력을 조정합니다
• 반복 감소: 한 번 만들면 자동으로 다시 사용할 수 있습니다
• 능력 조합: 여러 Skills를 결합해 복잡한 워크플로를 만들 수 있습니다

Skills 사용하기

Anthropic은 PowerPoint, Excel, Word, PDF 같은 일반적인 문서 작업을 위한 사전 구축 Agent Skills를 제공합니다. 또한 직접 커스텀 Skills를 만들 수도 있습니다. 두 종류 모두 같은 방식으로 동작합니다. Claude는 요청과 관련이 있다고 판단하면 자동으로 사용합니다.

사전 구축 Agent Skills는 claude.ai와 Claude API의 모든 사용자가 이용할 수 있습니다. 전체 목록은 아래 사용 가능한 Skills 섹션을 참조하세요.

커스텀 Skills를 사용하면 도메인 전문 지식과 조직 내부 지식을 패키징할 수 있습니다. Claude Code에서 만들거나, API를 통해 업로드하거나, claude.ai 설정에서 추가할 수 있습니다.

Skills의 작동 방식

Skills는 Claude의 VM 환경을 활용하여 프롬프트만으로는 제공하기 어려운 능력을 제공합니다. Claude는 파일 시스템에 접근할 수 있는 가상 머신에서 동작하므로, Skills는 지침, 실행 가능한 코드, 참고 자료를 담은 디렉터리로 존재할 수 있습니다. 새 팀원에게 줄 온보딩 가이드처럼 구성할 수 있습니다.

이 파일 시스템 기반 아키텍처는 점진적 공개를 가능하게 합니다. Claude는 모든 정보를 처음부터 컨텍스트에 넣지 않고, 필요할 때 단계적으로 로드합니다.

세 가지 Skill 콘텐츠와 세 단계 로딩

Skills에는 세 종류의 콘텐츠가 포함될 수 있으며, 각 콘텐츠는 서로 다른 시점에 로드됩니다.

레벨 1: 메타데이터(항상 로드됨)

콘텐츠 유형: 지침. Skill의 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.
---

Claude는 시작 시 이 메타데이터를 로드하고 시스템 프롬프트에 포함합니다. 이 가벼운 방식 덕분에 많은 Skills를 설치해도 컨텍스트 부담이 크지 않습니다. Claude가 아는 것은 각 Skill이 존재한다는 것과 언제 사용해야 하는지뿐입니다.

레벨 2: 지침(트리거될 때 로드됨)

콘텐츠 유형: 지침. SKILL.md 본문에는 워크플로, 모범 사례, 가이드 같은 절차적 지식이 들어갑니다.

# PDF Processing

## Quick start

Use pdfplumber to extract text from PDFs:
```python
import pdfplumber

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

For advanced form filling, see [FORMS.md](FORMS.md).

요청이 Skill의 설명과 일치하면 Claude는 bash를 통해 파일 시스템에서 SKILL.md를 읽습니다. 이때에야 해당 내용이 컨텍스트 창에 들어갑니다.

레벨 3: 리소스와 코드(필요할 때 로드됨)

콘텐츠 유형: 지침, 코드, 리소스. Skills는 추가 자료를 함께 묶을 수 있습니다.

pdf-skill/
|-- SKILL.md (main instructions)
|-- FORMS.md (form-filling guide)
|-- REFERENCE.md (detailed API reference)
`-- scripts/
  `-- fill_form.py (utility script)

지침: FORMS.md, REFERENCE.md처럼 전문 가이드와 워크플로를 담은 추가 Markdown 파일입니다.

코드: fill_form.py, validate.py처럼 Claude가 bash로 실행하는 스크립트입니다. 스크립트는 컨텍스트를 소비하지 않으면서 결정적인 작업을 제공합니다.

리소스: 데이터베이스 스키마, API 문서, 템플릿, 예제 같은 참고 자료입니다.

Claude는 참조될 때만 이러한 파일에 접근합니다. 파일 시스템 모델에서는 콘텐츠 유형마다 강점이 다릅니다. 유연한 안내에는 지침, 신뢰성에는 코드, 사실 확인에는 리소스가 적합합니다.

점진적 공개는 특정 시점에 관련 있는 내용만 컨텍스트 창을 차지하게 합니다.

Skills 아키텍처

Skills는 Claude가 파일 시스템, bash 명령, 코드 실행 능력에 접근할 수 있는 코드 실행 환경에서 동작합니다. Skills가 가상 머신의 디렉터리로 존재하고, Claude가 사용자의 컴퓨터에서 파일을 탐색할 때와 같은 bash 명령으로 그 안을 다룬다고 생각하면 됩니다.

Claude가 Skill 콘텐츠에 접근하는 방법:

Skill이 트리거되면 Claude는 bash를 사용해 파일 시스템에서 SKILL.md를 읽고 그 지침을 컨텍스트 창으로 가져옵니다. 지침이 FORMS.md나 데이터베이스 스키마 같은 다른 파일을 참조하면, Claude는 추가 bash 명령으로 해당 파일도 읽습니다. 지침에 실행 가능한 스크립트가 언급되어 있으면 Claude는 이를 bash로 실행하고 출력만 받습니다. 스크립트 코드 자체는 컨텍스트에 들어가지 않습니다.

이 아키텍처가 가능하게 하는 것:

온디맨드 파일 접근: Claude는 각 작업에 필요한 파일만 읽습니다. Skill에 수십 개의 참고 파일이 들어 있어도 작업에 sales 스키마만 필요하다면 Claude는 그 파일 하나만 로드합니다. 나머지는 파일 시스템에 남아 토큰을 전혀 소비하지 않습니다.

효율적인 스크립트 실행: Claude가 validate_form.py를 실행할 때, 스크립트 코드는 컨텍스트 창에 로드되지 않습니다. "Validation passed" 같은 출력이나 구체적인 오류 메시지만 토큰을 소비합니다. 따라서 스크립트는 Claude가 같은 코드를 즉석에서 생성하는 것보다 훨씬 효율적입니다.

번들 콘텐츠에 실질적 한계가 없음: 파일은 접근되기 전까지 컨텍스트를 소비하지 않으므로 Skills에는 포괄적인 API 문서, 큰 데이터셋, 풍부한 예제, 필요한 어떤 참고 자료든 포함할 수 있습니다. 사용되지 않는 번들 콘텐츠에는 컨텍스트 비용이 없습니다.

이 파일 시스템 기반 모델이 점진적 공개를 작동하게 합니다. Claude는 온보딩 가이드의 특정 섹션을 참조하듯 Skill을 탐색하고, 각 작업에 필요한 내용만 접근합니다.

예시: PDF 처리 Skill 로딩

Claude가 PDF 처리 Skill을 로드하고 사용하는 과정은 다음과 같습니다.

1. 시작 시: 시스템 프롬프트에 PDF Processing - Extract text and tables from PDF files, fill forms, merge documents가 포함됩니다
2. 사용자 요청: "이 PDF에서 텍스트를 추출하고 요약해 줘"
3. Claude 호출: bash: read pdf-skill/SKILL.md -> 지침이 컨텍스트에 로드됩니다
4. Claude 판단: 양식 채우기는 필요 없으므로 FORMS.md는 읽지 않습니다
5. Claude 실행: SKILL.md의 지침을 사용해 작업을 완료합니다

이 다이어그램은 다음을 보여 줍니다.

1. 시스템 프롬프트와 Skill 메타데이터가 미리 로드된 기본 상태
2. Claude가 bash를 통해 SKILL.md를 읽어 Skill을 트리거함
3. 필요할 때 Claude가 FORMS.md 같은 추가 번들 파일을 선택적으로 읽음
4. Claude가 작업을 진행함

이 동적 로딩은 관련 있는 Skill 콘텐츠만 컨텍스트 창을 차지하게 합니다.

Skills가 작동하는 곳

Skills는 Claude의 에이전트 제품 전반에서 사용할 수 있습니다.

Claude API

Claude API는 사전 구축 Agent Skills와 커스텀 Skills를 모두 지원합니다. 둘은 동일하게 동작합니다. 코드 실행 도구와 함께 container 파라미터에 관련 skill_id를 지정하면 됩니다.

전제 조건: API에서 Skills를 사용하려면 세 가지 beta 헤더가 필요합니다.

• code-execution-2025-08-25 - Skills는 코드 실행 컨테이너에서 실행됩니다
• skills-2025-10-02 - Skills 기능을 활성화합니다
• files-api-2025-04-14 - 컨테이너와 파일을 업로드/다운로드할 때 필요합니다

사전 구축 Agent Skills는 skill_id(예: pptx, xlsx)로 참조해서 사용하거나, Skills API(/v1/skills 엔드포인트)를 통해 직접 만든 Skills를 업로드할 수 있습니다. 커스텀 Skills는 조직 전체에서 공유됩니다.

자세한 내용은 Claude API로 Skills 사용하기를 참조하세요.

Claude Code

Claude Code는 커스텀 Skills만 지원합니다.

커스텀 Skills: SKILL.md 파일이 있는 디렉터리로 Skills를 만듭니다. Claude가 자동으로 발견하고 사용합니다.

Claude Code의 커스텀 Skills는 파일 시스템 기반이며 API 업로드가 필요하지 않습니다.

자세한 내용은 Claude Code에서 Skills 사용하기를 참조하세요.

Claude.ai

Claude.ai는 사전 구축 Agent Skills와 커스텀 Skills를 모두 지원합니다.

사전 구축 Agent Skills: 문서를 만들 때 이러한 Skills가 이미 뒤에서 작동하고 있습니다. Claude는 별도 설정 없이 사용합니다.

커스텀 Skills: Settings > Features에서 zip 파일로 직접 Skills를 업로드합니다. 코드 실행이 활성화된 Pro, Max, Team, Enterprise 플랜에서 사용할 수 있습니다. 커스텀 Skills는 사용자별로 적용되며 조직 전체에 공유되지 않고 관리자가 중앙에서 관리할 수도 없습니다.

Claude.ai에서 Skills를 사용하는 방법은 Claude Help Center의 다음 자료를 참조하세요.

• What are Skills?
• Using Skills in Claude
• How to create custom Skills
• Tech Claude your way of working using Skills

Skill 구조

모든 Skill에는 YAML frontmatter가 포함된 SKILL.md 파일이 필요합니다.

---
name: Your Skill Name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
[Clear, step-by-step guidance for Claude to follow]

## Examples
[Concrete examples of using this Skill]

필수 필드: name과 description

YAML frontmatter에서 지원되는 필드는 이 두 가지뿐입니다.

Frontmatter 제한:

• name: 최대 64자
• description: 최대 1024자

description에는 Skill이 무엇을 하는지와 Claude가 언제 사용해야 하는지를 모두 포함해야 합니다. 전체 작성 가이드는 모범 사례 가이드를 참조하세요.

보안 고려 사항

Skills는 신뢰할 수 있는 출처, 즉 직접 만들었거나 Anthropic에서 받은 것만 사용하는 것을 강력히 권장합니다. Skills는 지침과 코드를 통해 Claude에 새로운 능력을 부여합니다. 이는 강력하지만, 악성 Skill이 Claude에게 Skill의 명시된 목적과 맞지 않는 방식으로 도구를 호출하거나 코드를 실행하도록 지시할 수 있다는 뜻이기도 합니다.

주요 보안 고려 사항:

• 철저히 감사하기: Skill에 포함된 모든 파일(SKILL.md, 스크립트, 이미지, 기타 리소스)을 검토하세요. 예상치 못한 네트워크 호출, 파일 접근 패턴, Skill의 명시된 목적과 맞지 않는 작업 같은 이상한 패턴을 찾으세요
• 외부 소스는 위험함: 외부 URL에서 데이터를 가져오는 Skills는 특히 위험합니다. 가져온 콘텐츠에 악성 지침이 포함될 수 있기 때문입니다. 신뢰할 수 있는 Skills도 시간이 지나며 외부 의존성이 바뀌면 손상될 수 있습니다
• 도구 오용: 악성 Skills는 도구(파일 작업, bash 명령, 코드 실행)를 해로운 방식으로 호출할 수 있습니다
• 데이터 노출: 민감한 데이터에 접근하는 Skills는 정보를 외부 시스템으로 유출하도록 설계될 수 있습니다
• 소프트웨어 설치처럼 취급하기: 신뢰할 수 있는 출처의 Skills만 사용하세요. 민감한 데이터나 중요 작업에 접근하는 프로덕션 시스템에 Skills를 통합할 때 특히 주의하세요

사용 가능한 Skills

사전 구축 Agent Skills

다음 사전 구축 Agent Skills를 즉시 사용할 수 있습니다.

• PowerPoint (pptx): 프레젠테이션 생성, 슬라이드 편집, 프레젠테이션 콘텐츠 분석
• Excel (xlsx): 스프레드시트 생성, 데이터 분석, 차트가 포함된 보고서 생성
• Word (docx): 문서 생성, 콘텐츠 편집, 텍스트 서식 지정
• PDF (pdf): 서식 있는 PDF 문서와 보고서 생성

이 Skills는 Claude API와 claude.ai에서 사용할 수 있습니다. API에서 사용을 시작하려면 퀵스타트 튜토리얼을 참조하세요.

커스텀 Skills 예제

커스텀 Skills의 전체 예시는 Skills cookbook을 참조하세요.

제한 사항과 제약

이 제한 사항을 이해하면 Skills 배포를 효과적으로 계획할 수 있습니다.

제품 간 가용성

커스텀 Skills는 제품 간에 동기화되지 않습니다. 한 곳에 업로드한 Skills가 다른 곳에서 자동으로 사용할 수 있게 되지는 않습니다.

• Claude.ai에 업로드한 Skills는 API에 별도로 업로드해야 합니다
• API를 통해 업로드한 Skills는 Claude.ai에서 사용할 수 없습니다
• Claude Code Skills는 파일 시스템 기반이며 Claude.ai와 API 모두와 별개입니다

사용하려는 각 제품에서 Skills를 별도로 관리하고 업로드해야 합니다.

공유 범위

Skills는 사용하는 위치에 따라 공유 모델이 다릅니다.

• Claude.ai: 개별 사용자 전용. 각 팀원이 별도로 업로드해야 합니다
• Claude API: 워크스페이스 전체. 모든 워크스페이스 멤버가 업로드된 Skills에 접근할 수 있습니다
• Claude Code: 개인(~/.claude/skills/) 또는 프로젝트 기반(.claude/skills/)

Claude.ai는 현재 커스텀 Skills의 중앙 집중식 관리자 관리나 조직 전체 배포를 지원하지 않습니다.

런타임 환경 제약

Skills는 다음 제한이 있는 코드 실행 컨테이너에서 실행됩니다.

• 네트워크 접근 없음: Skills는 외부 API를 호출하거나 인터넷에 접근할 수 없습니다
• 런타임 패키지 설치 없음: 사전 설치된 패키지만 사용할 수 있습니다. 실행 중 새 패키지를 설치할 수 없습니다
• 사전 구성된 의존성만 사용: 사용 가능한 패키지 목록은 코드 실행 도구 문서를 확인하세요

이 제약 안에서 동작하도록 Skills를 계획하세요.

다음 단계