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 프런트매터는 검색 정보를 제공합니다.

---
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를 읽습니다. 그때 비로소 이 콘텐츠가 "context window"(컨텍스트 윈도우)에 들어갑니다.

레벨 3: 리소스 및 코드 (필요에 따라 로드됨)

Skills는 추가 자료를 번들로 포함할 수 있습니다.

• pdf-processing/
  • SKILL.md (주요 지침)
  • FORMS.md (양식 작성 가이드)
  • REFERENCE.md (상세 API 레퍼런스)
  • scripts/
    • fill_form.py (유틸리티 스크립트)

지침: 전문적인 안내와 워크플로를 담은 추가 마크다운 파일(FORMS.md, REFERENCE.md)

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

리소스: 데이터베이스 스키마, API 문서, 템플릿, 예제 등의 참조 자료

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

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

Skills 아키텍처

Skills는 Claude가 파일시스템 접근, bash 명령, 코드 실행 역량을 갖춘 코드 실행 환경에서 실행됩니다. Skills는 가상 머신의 디렉터리로 존재하며, Claude는 사용자가 컴퓨터에서 파일을 탐색할 때 사용하는 것과 동일한 bash 명령으로 Skills와 상호작용합니다.

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는 이 도구의 컨테이너에서 실행됩니다.

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

claude.ai에서 Skills를 사용하는 방법에 대해 자세히 알아보려면 Claude 도움말 센터의 다음 리소스를 참조하세요.

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

Skill 구조

모든 Skill에는 YAML 프런트매터가 있는 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 작성 모범 사례를 참조하세요.

보안 고려 사항

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

주요 보안 고려 사항:

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

조직 규모의 거버넌스, 검증, 배포 안내는 엔터프라이즈용 Skills를 참조하세요. Claude Enterprise 조직은 claude.ai 및 Claude Cowork에 업로드된 커스텀 Skills에 대해 Skill 콘텐츠 스캔을 켤 수도 있습니다. 스캔은 Skills API 또는 Claude Console을 통해 업로드된 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 및 데이터 보존을 참조하세요.

Skills API 작업의 감사 로깅에 대해서는 API에서 Agent 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 플러그인을 통해 공유할 수도 있습니다.

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

런타임 환경 제약

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

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

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

다음 단계