Agent Skills



Skills를 사용하는 이유

Skills는 재사용 가능한 파일 시스템 기반 리소스로, Claude에게 도메인별 전문 지식을 제공합니다. 즉, 범용 에이전트를 전문가로 변환하는 워크플로, 컨텍스트 및 모범 사례를 제공합니다. 일회성 작업을 위한 대화 수준 지침인 프롬프트와 달리, Skills는 필요할 때 로드되며 여러 대화에서 동일한 지침을 반복적으로 제공할 필요가 없습니다.

주요 이점:

• Claude 전문화: 도메인별 작업에 맞게 기능을 맞춤화
• 반복 감소: 한 번 생성하여 자동으로 사용
• 기능 조합: Skills를 결합하여 복잡한 워크플로 구축



Skills 사용하기

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

사전 구축된 Agent Skills는 claude.ai, Claude API, Claude Platform on AWS 및 Microsoft Foundry에서 사용할 수 있습니다. 전체 목록은 사용 가능한 Skills를 참조하세요.

커스텀 Skills를 사용하면 도메인 전문 지식과 조직 지식을 패키징할 수 있습니다. 이는 Claude의 제품 전반에서 사용할 수 있습니다. Claude Code에서 생성하거나, Claude API를 통해 업로드하거나, claude.ai 설정에서 추가할 수 있습니다. Claude Platform on AWS 및 Microsoft Foundry에서는 Skills API를 통해 커스텀 Skills를 업로드하세요.



Skills 작동 방식

Skills는 Claude의 VM 환경을 활용하여 프롬프트만으로는 불가능한 기능을 제공합니다. Claude는 파일 시스템 접근 권한이 있는 가상 머신에서 작동하므로, Skills는 지침, 실행 가능한 코드 및 참조 자료를 포함하는 디렉터리로 존재할 수 있으며, 이는 새로운 팀원을 위해 만드는 온보딩 가이드처럼 구성됩니다.

이 파일 시스템 기반 아키텍처는 **"progressive disclosure"(점진적 공개)**를 가능하게 합니다. 즉, 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)

코드: Claude가 bash를 통해 실행하는 실행 가능한 스크립트(fill_form.py, validate.py). 스크립트는 컨텍스트를 소비하지 않고 결정론적 작업을 제공합니다

리소스: 데이터베이스 스키마, API 문서, 템플릿 또는 예제와 같은 참조 자료

Claude는 참조될 때만 이러한 파일에 접근합니다. 파일 시스템 모델은 각 콘텐츠 유형이 서로 다른 강점을 가진다는 것을 의미합니다. 지침은 유연한 안내를 위해, 코드는 신뢰성을 위해, 리소스는 사실 조회를 위해 사용됩니다.

점진적 공개는 주어진 시점에 관련 콘텐츠만 컨텍스트 윈도우를 차지하도록 보장합니다.



Skills 아키텍처

Skills는 Claude가 파일 시스템 접근, bash 명령 및 코드 실행 기능을 가진 코드 실행 환경에서 실행됩니다. 이렇게 생각해 보세요. Skills는 가상 머신의 디렉터리로 존재하며, Claude는 컴퓨터에서 파일을 탐색할 때 사용하는 것과 동일한 bash 명령을 사용하여 이들과 상호작용합니다.

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

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

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

온디맨드 파일 접근: Claude는 각 특정 작업에 필요한 파일만 읽습니다. Skill에 수십 개의 참조 파일이 포함될 수 있지만, 작업에 영업 스키마만 필요한 경우 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를 사용하려면 세 개의 베타 헤더가 필요합니다.

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

skill_id(예: pptx, xlsx)를 참조하여 사전 구축된 Agent Skills를 사용하거나, Skills API(/v1/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: 설정 > 기능을 통해 자신만의 Skills를 zip 파일로 업로드하세요. 코드 실행이 활성화된 Pro, Max, Team 및 Enterprise 플랜에서 사용할 수 있습니다. 커스텀 Skills는 각 사용자에게 개별적이며, 조직 전체에서 공유되지 않고 관리자가 중앙에서 관리할 수 없습니다.

claude.ai에서 Skills 사용에 대한 자세한 내용은 Claude 도움말 센터의 다음 리소스를 참조하세요.

• Skills란 무엇인가요?
• Claude에서 Skills 사용하기
• 커스텀 Skills를 만드는 방법
• Skills를 사용하여 Claude에게 작업 방식 가르치기



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

필드 요구 사항:

name:

• 최대 64자
• 소문자, 숫자 및 하이픈만 포함해야 함
• XML 태그를 포함할 수 없음
• 예약어를 포함할 수 없음: "anthropic", "claude"

description:

• 비어 있지 않아야 함
• 최대 1024자
• XML 태그를 포함할 수 없음

description에는 Skill이 수행하는 작업과 Claude가 이를 사용해야 하는 시점이 모두 포함되어야 합니다. 전체 작성 지침은 모범 사례 가이드를 참조하세요.



보안 고려 사항

신뢰할 수 있는 출처의 Skills만 사용하세요. 즉, 직접 만들었거나 Anthropic에서 얻은 것만 사용하세요. Skills는 지침과 코드를 통해 Claude에게 새로운 기능을 제공하며, 이것이 Skills를 강력하게 만들지만, 악의적인 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 Platform on AWS, Microsoft Foundry 및 claude.ai에서 사용할 수 있습니다. API에서 사용을 시작하려면 빠른 시작 튜토리얼을 참조하세요.



오픈 소스 Skills

Anthropic은 또한 skills 리포지토리에 오픈 소스 Skills를 게시합니다.

• Claude API: Claude에게 8개 프로그래밍 언어에 대한 최신 API 참조 자료, SDK 문서 및 모범 사례를 제공합니다. Claude Code에 번들로 제공되며 skills 리포지토리에서 설치할 수도 있습니다.



커스텀 Skills 예제

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



데이터 보존

Agent Skills는 ZDR 계약의 적용을 받지 않습니다. Skill 정의 및 실행 데이터는 Anthropic의 표준 데이터 보존 정책에 따라 보존됩니다.

모든 기능에 대한 ZDR 적격성은 API 및 데이터 보존을 참조하세요.



제한 사항 및 제약 조건

이러한 제한 사항을 이해하면 Skills 배포를 효과적으로 계획하는 데 도움이 됩니다. Claude Platform on AWS 및 Microsoft Foundry는 다음 하위 섹션에서 Claude API와 동일한 제한 사항을 따릅니다.



크로스 서피스 가용성

커스텀 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 Code Plugins를 통해 공유할 수도 있습니다

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



런타임 환경 제약 조건

Skill에서 사용할 수 있는 정확한 런타임 환경은 사용하는 제품 서피스에 따라 다릅니다.

• claude.ai:
  • 다양한 네트워크 접근: 사용자/관리자 설정에 따라 Skills는 전체, 부분 또는 네트워크 접근 없음을 가질 수 있습니다. 자세한 내용은 Claude로 파일 생성 및 편집 지원 문서를 참조하세요.
• Claude API:
  • 네트워크 접근 없음: Skills는 외부 API 호출을 하거나 인터넷에 접근할 수 없습니다
  • 런타임 패키지 설치 없음: 사전 설치된 패키지만 사용할 수 있습니다. 실행 중에 새 패키지를 설치할 수 없습니다.
  • 사전 구성된 종속성만: 사용 가능한 패키지 목록은 코드 실행 도구 문서를 확인하세요
• Claude Code:
  • 전체 네트워크 접근: Skills는 사용자 컴퓨터의 다른 프로그램과 동일한 네트워크 접근 권한을 가집니다
  • 전역 패키지 설치 권장하지 않음: Skills는 사용자 컴퓨터에 영향을 주지 않도록 패키지를 로컬에만 설치해야 합니다

이러한 제약 조건 내에서 작동하도록 Skills를 계획하세요.



다음 단계