에이전트 스킬
에이전트 스킬 (Agent Skills)
에이전트 스킬(Agent Skills)은 클로드의 기능을 확장하는 모듈식 능력이에요. 각 스킬은 지시, 메타데이터, 그리고 선택적 리소스(스크립트, 템플릿)를 패키징하며, 클로드가 관련될 때 자동으로 사용해요. 프롬프트처럼 대화마다 같은 지침을 반복할 필요 없이, 필요할 때만 로드되는 파일시스템 기반 리소스로 일반 에이전트를 전문가로 바꿔주는 방식이에요.
출처: 문서
본문
왜 스킬을 사용하나요 (Why use Skills)
스킬은 재사용 가능한 파일시스템 기반 리소스로, 클로드에 도메인 특화 전문성을 부여해요. 워크플로우, 컨텍스트, 모범 사례가 일반 에이전트를 전문가로 바꾸는 거죠. 프롬프트(일회성 작업을 위한 대화 수준 지시)와 달리 스킬은 필요할 때만 로드되므로, 대화마다 같은 지침을 반복하지 않아도 돼요.
주요 이점:
- 클로드 전문화: 도메인 특화 작업을 위해 능력을 맞춤 설정
- 반복 줄이기: 한 번 만들면 자동으로 사용
- 능력 조합: 복잡한 다단계 작업을 위해 스킬 결합
스킬 사용하기 (Using Skills)
Anthropic은 흔한 문서 작업(PowerPoint, Excel, Word, PDF)을 위한 사전 구축 에이전트 스킬을 제공하며, 직접 커스텀 스킬을 만들 수도 있어요. 둘 다 같은 방식으로 작동해요. 환경에 스킬이 있으면 관련 요청에 클로드가 자동으로 사용해요.
사전 구축 에이전트 스킬은 claude.ai, Claude API, Claude Platform on AWS, Microsoft Foundry에서 사용할 수 있어요. Microsoft Foundry에서는 에이전트 스킬에 Hosted on Anthropic 배포가 필요해요. 전체 목록은 사용 가능한 스킬을 참고하세요.
커스텀 스킬은 도메인 전문성과 조직 지식을 패키징하게 해요. 클로드 제품 전반에서 사용할 수 있어요. Claude Code에서 만들고, Claude API로 업로드하거나, claude.ai 설정에 추가할 수 있어요. Claude Platform on AWS와 Microsoft Foundry에서는 Skills API를 통해 커스텀 스킬을 업로드해요.
스킬이 작동하는 방식 (How Skills work)
스킬은 클로드의 VM 환경을 사용해 프롬프트만으로는 불가능한 능력을 제공해요. 클로드는 파일시스템 접근이 있는 가상 머신에서 운영되므로, 스킬은 지시, 실행 가능한 코드, 참조 자료를 담은 디렉터리로 존재할 수 있어요. 새 팀원을 위해 만드는 온보딩 가이드처럼 조직된 구조죠.
이 파일시스템 기반 아키텍처는 **점진적 공개(progressive disclosure)**를 가능하게 해요. 클로드는 컨텍스트를 미리 소비하기보다 단계별로 필요할 때 정보를 로드해요.
스킬은 각각 다른 시점에 로드되는 세 가지 유형의 콘텐츠를 담을 수 있어요:
레벨 1: 메타데이터 (항상 로드)
스킬의 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.
---
클로드는 시작 시 이 메타데이터를 로드해 시스템 프롬프트에 포함해요. description은 클로드가 스킬을 발동시킬지 결정할 때 요청과 매칭하는 부분이므로, 스킬이 무엇을 하는지와 언제 사용해야 하는지 모두 말해야 해요. 이 가벼운 접근 방식 덕분에 컨텍스트 비용 없이 많은 스킬을 설치할 수 있어요. 스킬이 발동되기 전까지는 이름과 설명만 컨텍스트를 차지하니까요.
레벨 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).
스킬 설명과 일치하는 것을 요청하면 클로드는 bash를 사용해 파일시스템에서 SKILL.md를 읽어요. 이때서야 이 콘텐츠가 컨텍스트 창에 들어와요.
레벨 3: 리소스와 코드 (필요할 때 로드)
스킬은 추가 자료를 번들할 수 있어요:
-
pdf-processing/SKILL.md(주 지시)FORMS.md(양식 작성 가이드)REFERENCE.md(상세 API 참조)scripts/fill_form.py(유틸리티 스크립트)
지시: 특화된 지침과 워크플로우를 담은 추가 마크다운 파일(FORMS.md, REFERENCE.md)
코드: 클로드가 bash로 실행하는 실행 가능한 스크립트(fill_form.py, validate.py). 코드를 컨텍스트에 로드하지 않고 결정적 작업을 제공해요.
리소스: 데이터베이스 스키마, API 문서, 템플릿, 예시 같은 참조 자료
클로드는 참조할 때만 이런 파일에 접근해요. 파일시스템 모델은 각 콘텐츠 유형이 다른 강점을 갖게 해요. 유연한 지침은 지시, 안정성은 코드, 사실 조회는 리소스에요.
| 레벨 | 로드 시점 | 토큰 비용 | 콘텐츠 |
|---|---|---|---|
| 레벨 1: 메타데이터 | 항상 (시작 시) | 스킬당 약 100 토큰 | YAML 프론트매터의 name과 description |
| 레벨 2: 지시 | 스킬 발동 시 | 5k 토큰 미만 | 지시와 안내가 있는 SKILL.md 본문 |
| 레벨 3+: 리소스 | 필요할 때 | 접근 전까지 없음 | 번들 파일. 참조 파일은 읽을 때 컨텍스트에 로드됨. 스크립트는 bash로 실행되며 출력만 컨텍스트에 들어감 |
점진적 공개는 어느 순간에도 오직 관련 콘텐츠만 컨텍스트 창을 차지하도록 보장해요.
스킬 아키텍처
스킬은 클로드에 파일시스템 접근, bash 명령, 코드 실행 능력이 있는 코드 실행 환경에서 실행돼요. 스킬은 가상 머신의 디렉터리로 존재하며, 클로드는 컴퓨터에서 파일을 탐색할 때 쓰는 것과 같은 bash 명령으로 상호작용해요.
클로드가 스킬 콘텐츠에 접근하는 방식:
스킬이 발동되면 클로드는 bash로 파일시스템에서 SKILL.md를 읽어 그 지시를 컨텍스트 창으로 가져와요. 그 지시가 다른 파일(FORMS.md나 데이터베이스 스키마 등)을 참조하면, 클로드는 추가 bash 명령으로 그 파일들도 읽어요. 지시가 실행 가능한 스크립트를 언급하면, 클로드는 bash로 실행하고 출력만 받아요.(스크립트 코드 자체는 결코 컨텍스트에 들어오지 않아요.)
이 아키텍처가 가능하게 하는 것:
- 주문형 파일 접근: 클로드는 각 작업이 필요로 하는 파일만 읽어요. 스킬에 수십 개의 참조 파일이 있어도, 작업이 판매 스키마만 필요하면 클로드가 로드하는 파일은 그것뿐이에요. 나머지는 파일시스템에 남아 토큰 비용이 0이에요.
- 효율적인 스크립트 실행: 클로드가
validate_form.py를 실행할 때 스크립트 코드는 컨텍스트 창에 로드되지 않아요. 출력("Validation passed"나 특정 오류 메시지 등)만 토큰을 소비하므로, 클로드가 즉석에서 동등한 코드를 생성하는 것보다 훨씬 효율적이에요. - 번들 콘텐츠에 실질적 한계 없음: 파일은 접근하기 전까지 컨텍스트를 소비하지 않으므로, 스킬에 포괄적인 API 문서, 대규모 데이터셋, 광범위한 예시를 포함할 수 있어요. 사용되지 않는 번들 콘텐츠에는 컨텍스트 비용이 없어요.
예시: PDF 처리 스킬 로드하기
앞선 예시의 커스텀 pdf-processing 스킬(사전 구축 pdf 스킬이 아님)을 클로드가 로드하고 사용하는 방식은 다음과 같아요:
- 시작: 시스템 프롬프트가
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.를 포함해요. - 사용자 요청: "Extract the text from this PDF and summarize it"
- 클로드 호출:
bash: cat pdf-processing/SKILL.md→ 지시가 컨텍스트에 로드됨 - 클로드 판단: 양식 작성이 필요 없으므로 FORMS.md를 읽지 않음
- 클로드 실행: SKILL.md의 지시를 사용해 작업 완료
스킬이 작동하는 곳 (Where Skills work)
스킬은 클로드의 에이전트 제품 전반에서 사용할 수 있어요:
Claude API
Claude API는 사전 구축 에이전트 스킬과 커스텀 스킬을 모두 지원해요. 둘 다 동일하게 작동해요. 코드 실행 도구와 함께 container 파라미터에 관련 skill_id를 지정하세요.
전제 조건: API로 스킬을 사용하려면 코드 실행 도구가 필요하며, 그 컨테이너에서 스킬이 실행돼요.
사전 구축 에이전트 스킬은 skill_id(pptx, xlsx, docx, pdf)를 참조해 사용하거나, Skills API(/v1/skills 엔드포인트)로 직접 만들어 업로드할 수 있어요. 커스텀 스킬은 워크스페이스 전체에서 공유돼요. 모든 워크스페이스 멤버가 접근할 수 있어요.
API의 스킬은 네트워크 접근이 없고 런타임 패키지 설치가 없는 샌드박스 컨테이너에서 실행돼요. 자세한 내용은 제한 사항 및 제약을 참고하세요.
자세한 내용은 API에서 에이전트 스킬 사용하기를 참고하세요.
Claude Code
Claude Code는 커스텀 스킬을 지원해요. 사전 구축 문서 스킬(PowerPoint, Excel, Word, PDF)은 Claude Code에서 사용할 수 없지만, 오픈소스 Claude API 스킬이 함께 번들되어 나와요. Claude Code에 포함된 내장 명령과 스킬 목록 전체를 참고하세요.
커스텀 스킬: SKILL.md 파일이 있는 디렉터리로 스킬을 만드세요. 클로드가 자동으로 발견하고 사용해요.
Claude Code의 커스텀 스킬은 파일시스템 기반이며 API 업로드가 필요 없어요. ~/.claude/skills/(개인) 또는 .claude/skills/(프로젝트)에 두세요.
자세한 내용은 Claude Code에서 스킬 사용하기를 참고하세요.
claude.ai
claude.ai는 사전 구축 에이전트 스킬과 커스텀 스킬을 모두 지원해요.
사전 구축 에이전트 스킬: 문서를 만들 때 이 스킬들이 활성화돼요. 설정 없이 클로드가 사용해요.
커스텀 스킬: Settings > Features를 통해 자신의 스킬을 zip 파일로 업로드하세요. 코드 실행이 활성화된 Pro, Max, Team, Enterprise 요금제에서 사용할 수 있어요. 커스텀 스킬은 각 사용자에게 개별적이에요. 조직 전체에서 공유되지 않으며 관리자가 중앙에서 관리할 수 없어요.
claude.ai에서 스킬 사용에 대해 자세히 보려면 Claude Help Center의 다음 리소스를 참고하세요:
스킬 구조 (Skill structure)
모든 스킬에는 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은 스킬이 무엇을 하는지와 클로드가 언제 사용해야 하는지를 모두 포함해야 해요. 전체 작성 안내는 스킬 작성 모범 사례를 참고하세요.
보안 고려 사항 (Security considerations)
신뢰할 수 있는 출처의 스킬만 사용하세요. 직접 만들었거나 Anthropic에서 얻은 스킬이요. 스킬은 지시와 코드를 통해 클로드에 새 능력을 부여하며, 이는 악성 스킬이 클로드가 스킬의 표시된 목적과 일치하지 않는 방식으로 도구를 호출하거나 코드를 실행하도록 지시할 수 있음을 의미해요.
핵심 보안 고려 사항:
- 철저히 감사하기: 스킬에 번들된 모든 파일(SKILL.md, 스크립트, 이미지, 기타 리소스)을 검토하세요. 예상치 못한 네트워크 호출, 파일 접근 패턴, 스킬의 표시된 목적과 일치하지 않는 작업 같은 비정상 패턴을 찾아보세요
- 외부 출처는 위험: 외부 URL에서 데이터를 가져오는 스킬은 특히 위험해요. 가져온 콘텐츠가 악성 지시를 포함할 수 있기 때문이에요. 신뢰할 수 있는 스킬도 외부 의존성이 시간이 지나며 바뀌면 손상될 수 있어요
- 도구 오용: 악성 스킬은 도구(파일 작업, bash 명령, 코드 실행)를 해로운 방식으로 호출할 수 있어요
- 데이터 노출: 민감한 데이터에 접근하는 스킬은 외부 시스템에 정보를 유출하도록 설계될 수 있어요
- 소프트웨어 설치처럼 취급: 민감한 데이터나 중요 작업에 접근하는 프로덕션 시스템에 스킬을 통합할 때 특히 주의하세요
조직 규모의 거버넌스, 검증, 배포 지침은 엔터프라이즈용 스킬을 참고하세요. Claude Enterprise 조직은 claude.ai와 Claude Cowork에 업로드된 커스텀 스킬에 대해 스킬 콘텐츠 스캐닝을 켤 수도 있어요. 스캐닝은 Skills API나 Claude Console을 통해 업로드된 스킬에는 적용되지 않아요.
사용 가능한 스킬 (Available Skills)
사전 구축 에이전트 스킬
즉시 사용 가능한 사전 구축 에이전트 스킬은 다음과 같아요:
- PowerPoint (pptx): 프레젠테이션 만들기, 슬라이드 편집, 프레젠테이션 콘텐츠 분석
- Excel (xlsx): 스프레드시트 만들기, 데이터 분석, 차트가 있는 리포트 생성
- Word (docx): 문서 만들기, 콘텐츠 편집, 텍스트 서식 지정
- PDF (pdf): 서식 있는 PDF 문서와 리포트 생성
이 스킬들은 Claude API, Claude Platform on AWS, Microsoft Foundry, claude.ai에서 사용할 수 있어요. API에서 사용을 시작하려면 퀵스타트 튜토리얼을 참고하세요.
오픈소스 스킬
Anthropic은 또한 skills 리포지토리에 오픈소스 스킬을 게시해요:
- Claude API 스킬: 8개 프로그래밍 언어에 대한 최신 API 참조 자료, SDK 문서, 모범 사례를 클로드에 제공해요. Claude Code에 번들되어 있고 skills 리포지토리에서 설치할 수도 있어요.
커스텀 스킬 예시
커스텀 스킬의 완전한 예시는 스킬 쿡북을 참고하세요.
데이터 보존 (Data retention)
에이전트 스킬은 ZDR 계약에 포함되지 않아요. 스킬 정의와 실행 데이터는 Anthropic의 표준 데이터 보존 정책에 따라 보존돼요.
모든 기능의 ZDR 자격은 API 및 데이터 보존을 참고하세요.
Skills API 작업의 감사 로깅은 API에서 에이전트 스킬 사용하기의 감사 로깅을 참고하세요.
제한 사항 및 제약 (Limitations and constraints)
Claude Platform on AWS와 Microsoft Foundry는 다음 하위 섹션에서 Claude API와 같은 제한 사항을 따르지요.
표면 간 가용성
커스텀 스킬은 서로 다른 표면 간에 동기화되지 않아요. 한 표면에 업로드된 스킬은 다른 표면에서 자동으로 사용할 수 없어요:
- claude.ai에 업로드된 스킬은 API에 별도로 업로드해야 해요
- API를 통해 업로드된 스킬은 claude.ai에서 사용할 수 없어요
- Claude Code 스킬은 파일시스템 기반이며 claude.ai와 API 모두와 별개예요
스킬을 사용하려는 각 표면에 대해 별도로 관리하고 업로드하세요.
공유 범위
스킬은 사용 위치에 따라 공유 모델이 달라요:
- claude.ai: 개별 사용자 전용. 각 팀원이 별도로 업로드해야 해요.
- Claude API: 워크스페이스 전체. 모든 워크스페이스 멤버가 업로드된 스킬에 접근할 수 있어요.
- Claude Code: 개인(
~/.claude/skills/) 또는 프로젝트 기반(.claude/skills/). Claude Code 플러그인을 통해 공유할 수도 있어요.
claude.ai는 커스텀 스킬의 중앙 집중 관리자 관리나 조직 전체 배포를 지원하지 않아요.
런타임 환경 제약
스킬에 사용할 수 있는 정확한 런타임 환경은 사용하는 제품 표면에 따라 달라요.
-
claude.ai:
- 다양한 네트워크 접근: 사용자/관리자 설정에 따라 스킬이 전체, 부분, 또는 네트워크 접근 없음을 가질 수 있어요. 자세한 내용은 Create and Edit Files 지원 문서를 참고하세요.
-
Claude API:
- 네트워크 접근 없음: 스킬은 외부 API 호출을 하거나 인터넷에 접근할 수 없어요.
- 런타임 패키지 설치 없음: 사전 설치된 패키지만 사용할 수 있어요. 실행 중 새 패키지를 설치할 수 없어요.
- 사전 구성 의존성만: 사용 가능한 패키지 목록은 코드 실행 도구 문서를 확인하세요.
-
Claude Code:
- 전체 네트워크 접근: 스킬은 사용자 컴퓨터의 다른 프로그램과 같은 네트워크 접근을 가져요.
- 전역 패키지 설치 지양: 스킬은 사용자 컴퓨터를 방해하지 않도록 패키지를 로컬로만 설치해야 해요.
이 제약 안에서 작동하도록 스킬을 계획하세요.