Agent Skills



Skills를 사용하는 이유

Skills는 Claude에게 도메인별 전문 지식을 제공하는 재사용 가능한 파일시스템 기반 리소스입니다. 워크플로우, 컨텍스트, 모범 사례를 통해 범용 에이전트를 전문가로 만듭니다. 프롬프트(일회성 작업을 위한 대화 수준의 지침)와 달리 Skills는 필요할 때 로드되므로 대화마다 동일한 지침을 반복할 필요가 없습니다.

주요 이점:

• Claude 전문화: 도메인별 작업에 맞게 기능을 조정
• 반복 감소: 한 번 만들면 자동으로 사용
• 기능 조합: 복잡한 다단계 작업을 위해 Skills를 결합



Skills 사용하기

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

사전 구축된 Agent Skills는 claude.ai, Claude API, Claude Platform on AWS, Microsoft Foundry에서 사용할 수 있습니다. Microsoft Foundry에서 Agent Skills를 사용하려면 Hosted on Anthropic 배포가 필요합니다. 전체 목록은 사용 가능한 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는 컨텍스트를 미리 소비하는 대신 필요에 따라 단계적으로 정보를 로드합니다.

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는 시작 시 이 메타데이터를 로드하고 시스템 프롬프트에 포함합니다. description은 Claude가 Skill을 트리거할지 결정할 때 요청과 대조하는 항목이므로, Skill이 무엇을 하는지와 언제 사용해야 하는지를 모두 명시해야 합니다. 이 경량 접근 방식 덕분에 컨텍스트 부담 없이 많은 Skills를 설치할 수 있습니다. 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-processing/
├── 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 문서, 대규모 데이터셋 또는 광범위한 예제를 포함할 수 있습니다. 사용되지 않는 번들 콘텐츠에 대한 컨텍스트 부담은 없습니다.



예시: PDF 처리 Skill 로드하기

다음은 Claude가 앞선 예시의 사용자 정의 pdf-processing Skill(사전 구축된 pdf Skill이 아님)을 로드하고 사용하는 방법입니다:

1. 시작: 시스템 프롬프트에 다음이 포함됩니다: pdf-processing - 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.
2. 사용자 요청: "이 PDF에서 텍스트를 추출하고 요약해 주세요"
3. Claude 호출: bash: cat pdf-processing/SKILL.md → 지침이 컨텍스트에 로드됨
4. Claude 판단: 양식 작성이 필요하지 않으므로 FORMS.md를 읽지 않음
5. Claude 실행: SKILL.md의 지침을 사용하여 작업 완료



Skills를 사용할 수 있는 곳

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



Claude API

Claude API는 사전 구축된 Agent Skills와 사용자 정의 Skills를 모두 지원합니다. 둘 다 동일하게 작동합니다. 코드 실행 도구와 함께 container 매개변수에 관련 skill_id를 지정합니다.

사전 요구 사항: API를 통해 Skills를 사용하려면 Skills가 실행되는 컨테이너를 제공하는 코드 실행 도구와 하나의 베타 헤더가 필요합니다:

• skills-2025-10-02 - Skills 기능 활성화

Files API를 사용하여 컨테이너에 입력 파일을 업로드하거나 Skill이 생성한 파일을 다운로드할 때는 두 번째 헤더인 files-api-2025-04-14를 추가하세요.

사전 구축된 Agent Skills는 skill_id(pptx, xlsx, docx, pdf)를 참조하여 사용하거나, Skills API(/v1/skills 엔드포인트)를 통해 직접 만들어 업로드할 수 있습니다. 사용자 정의 Skills는 워크스페이스 전체에서 공유됩니다. 모든 워크스페이스 구성원이 접근할 수 있습니다.

API의 Skills는 네트워크 접근과 런타임 패키지 설치가 불가능한 샌드박스 컨테이너에서 실행됩니다. 자세한 내용은 제한 사항 및 제약 조건을 참조하세요.

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



Claude Code

Claude Code는 사용자 정의 Skills를 지원합니다. 사전 구축된 문서 Skills(PowerPoint, Excel, Word, PDF)는 Claude Code에서 사용할 수 없지만, 오픈소스 Claude API skill은 함께 번들로 제공됩니다. Claude Code와 함께 제공되는 내장 명령 및 Skills의 전체 목록을 참조하세요.

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

Claude Code의 사용자 정의 Skills는 파일시스템 기반이며 API 업로드가 필요하지 않습니다. ~/.claude/skills/(개인) 또는 .claude/skills/(프로젝트)에 배치하세요.

자세한 내용은 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 헬프 센터의 다음 리소스를 참조하세요:

• 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가 언제 사용해야 하는지를 모두 포함해야 합니다. 전체 작성 지침은 Skill 작성 모범 사례를 참조하세요.



보안 고려 사항

신뢰할 수 있는 출처의 Skills만 사용하세요. 직접 만들었거나 Anthropic에서 얻은 것이어야 합니다. Skills는 지침과 코드를 통해 Claude에게 새로운 기능을 부여하는데, 이는 악의적인 Skill이 Skill의 명시된 목적과 일치하지 않는 방식으로 Claude가 도구를 호출하거나 코드를 실행하도록 지시할 수 있다는 의미이기도 합니다.

주요 보안 고려 사항:

• 철저한 감사: 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 skill: Claude에게 최신 API 참조 자료, SDK 문서, 8개 프로그래밍 언어에 대한 모범 사례를 제공합니다. Claude Code와 함께 번들로 제공되며 skills 저장소에서 설치할 수도 있습니다.



사용자 정의 Skills 예시

사용자 정의 Skills의 전체 예시는 Skills cookbook을 참조하세요.



데이터 보존

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

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



제한 사항 및 제약 조건

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 API:
  • 네트워크 접근 불가: Skills는 외부 API 호출을 하거나 인터넷에 접근할 수 없습니다.
  • 런타임 패키지 설치 불가: 사전 설치된 패키지만 사용할 수 있습니다. 실행 중에 새 패키지를 설치할 수 없습니다.
  • 사전 구성된 종속성만 사용 가능: 사용 가능한 패키지 목록은 코드 실행 도구 문서를 확인하세요.
• Claude Code:
  • 전체 네트워크 접근: Skills는 사용자 컴퓨터의 다른 프로그램과 동일한 네트워크 접근 권한을 갖습니다.
  • 전역 패키지 설치 권장하지 않음: Skills는 사용자의 컴퓨터에 영향을 주지 않도록 패키지를 로컬에만 설치해야 합니다.

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



다음 단계