에이전트 스킬 (Agent Skills)¶
에이전트 스킬(Agent Skills)은 Claude의 기능을 확장해 주는 모듈형 능력이에요. 각 스킬은 지침(instructions), 메타데이터, 그리고 필요에 따라 붙일 수 있는 리소스(스크립트·템플릿)를 하나로 묶어서, 상황이 맞을 때 Claude가 알아서 꺼내 쓰게 해 줘요.
왜 스킬을 쓸까요¶
스킬은 재사용 가능한 파일 기반 리소스예요. 도메인 특화된 전문성을 Claude에 심어 주죠. 워크플로우·컨텍스트·모범 사례 같은 것을 담아서 "만능 에이전트"를 "그 분야 전문가"로 만들어 주는 셈이에요.
프롬프트(일회성 작업을 위한 대화 수준 지침)와 달리, 스킬은 필요할 때 불러오는(on-demand) 방식이라서 매번 같은 안내를 대화에 반복해서 넣을 필요가 없어요.
주요 장점:
- Claude를 특화: 도메인별 작업에 맞춰 능력을 조정
- 반복 줄이기: 한 번 만들어 두면 자동으로 활용
- 능력 합성: 복잡한 다단계 작업을 위해 여러 스킬을 조합
스킬 사용하기¶
Anthropic은 흔한 문서 작업(PowerPoint, Excel, Word, PDF)용 사전 제작 스킬(Pre-built Agent Skills)을 제공하고, 여러분이 직접 만드는 커스텀 스킬(Custom Skills)도 지원해요. 둘 다 동작 방식은 같아요. 스킬이 환경에만 준비되어 있으면, 요청에 관련이 있을 때 Claude가 자동으로 사용해요.
- 사전 제작 스킬은 claude.ai, Claude API, Claude Platform on AWS, Microsoft Foundry에서 쓸 수 있어요. Microsoft Foundry에서는 Agent Skills를 쓰려면 Hosted on Anthropic 배포 방식이 필요해요. 전체 목록은 Available Skills를 보면 돼요.
- 커스텀 스킬은 도메인 전문성과 조직 지식을 담아 두는 거예요. Claude 제품 전반에서 만들 수 있어요. Claude Code에서 만들거나, Claude API로 업로드하거나, claude.ai 설정에서 추가하면 되죠. Claude Platform on AWS와 Microsoft Foundry에서는 Skills API로 커스텀 스킬을 업로드해요.
스킬은 어떻게 동작하나요¶
스킬은 Claude의 VM(가상 머신) 환경을 활용해서, 프롬프트만으로는 못 하는 능력을 제공해요. Claude는 파일시스템 접근 권한이 있는 가상 머신 안에서 동작하는데, 그래서 스킬은 지침·실행 가능한 코드·참고 자료가 담긴 디렉터리 형태로 존재해요. 새 팀원을 위해 만들어 두는 온보딩 가이드와 비슷한 구조라고 생각하면 돼요.
이 파일시스템 기반 구조 덕분에 점진적 공개(progressive disclosure)가 가능해요. Claude는 처음부터 모든 컨텍스트를 소비하는 대신, 필요한 만큼 단계별로 정보를 불러와요.
스킬에는 세 종류의 콘텐츠가 들어갈 수 있고, 각각 서로 다른 시점에 불러와져요.
레벨 1: 메타데이터 (항상 불러옴)¶
스킬의 YAML 프론트매터(frontmatter)는 발견(discovery) 정보를 담아요:
---
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가 요청을 스킬과 매칭시킬 때 비교하는 값이라서, 무엇을 하는지와 언제 써야 하는지 둘 다 담아야 해요. 이 가벼운 방식 덕분에 컨텍스트 페널티 없이 스킬을 많이 설치할 수 있어요. 스킬이 트리거되기 전까지는 이름과 설명만 컨텍스트를 차지하거든요.
레벨 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.
스킬의 `description`과 일치하는 요청이 들어오면, Claude는 bash를 써서 파일시스템에서 SKILL.md를 읽어요. 그때서야 이 내용이 컨텍스트 윈도우에 들어오는 거예요.
### 레벨 3: 리소스와 코드 (필요할 때 불러옴)
스킬에는 추가 자료를 묶어 둘 수 있어요:
- **지침(Instructions):** FORMS.md, REFERENCE.md 같은 추가 마크다운 파일. 전문적인 안내와 워크플로우를 담아요.
- **코드(Code):** fill_form.py, validate.py 같은 실행 가능한 스크립트. Claude가 bash로 실행해서, 코드를 컨텍스트에 넣지 않고도 결정적인(결과가 일관된) 동작을 보장해요.
- **리소스(Resources):** 데이터베이스 스키마, API 문서, 템플릿, 예제 같은 참고 자료.
Claude는 이 파일들을 **참조할 때만** 접근해요. 파일시스템 모델 덕분에 콘텐츠 유형마다 강점이 달라져요. 지침은 유연한 안내에, 코드는 신뢰성에, 리소스는 사실 조회에 좋죠.
| 레벨 | 불러오는 시점 | 토큰 비용 | 내용 |
|---|---|---|---|
| **레벨 1: 메타데이터** | 항상 (시작 시) | 스킬당 약 100 토큰 | YAML 프론트매터의 `name`과 `description` |
| **레벨 2: 지침** | 스킬이 트리거될 때 | 5k 토큰 미만 | 지침과 안내가 담긴 SKILL.md 본문 |
| **레벨 3+: 리소스** | 필요할 때 | 접근 전까지 없음 | 번들 파일. 참조 파일은 읽을 때 컨텍스트로. 스크립트는 bash로 실행되고 출력만 컨텍스트에 들어감 |
이렇게 점진적으로 공개하기 때문에, 어떤 시점이든 관련 있는 콘텐츠만 컨텍스트 윈도우를 차지하게 돼요.
### 스킬 아키텍처
스킬은 Claude가 파일시스템 접근·bash 명령·코드 실행 능력을 갖는 **코드 실행 환경**에서 돌아가요. 스킬은 가상 머신 위의 디렉터리로 존재하고, Claude는 여러분이 컴퓨터에서 파일을 탐색할 때 쓰는 것과 동일한 bash 명령으로 스킬과 상호작용해요.
**Claude가 스킬 콘텐츠에 접근하는 방법:**
스킬이 트리거되면 Claude는 bash로 SKILL.md를 읽어서 그 지침을 컨텍스트 윈도우로 가져와요. 그 지침이 다른 파일(FORMS.md나 데이터베이스 스키마 같은)을 참조하면, 추가 bash 명령으로 그것도 읽어요. 지침이 실행 가능한 스크립트를 언급하면 Claude는 bash로 실행하고 **출력만** 받아요 — 스크립트 코드 자체는 절대 컨텍스트에 들어오지 않아요.
**이 아키텍처가 가능하게 하는 것:**
- **주문형 파일 접근:** Claude는 각 작업에 필요한 파일만 읽어요. 스킬에 참조 파일이 수십 개 있어도, 작업에 판매(sales) 스키마만 필요하다면 그 파일 하나만 불러오고 나머지는 파일시스템에 남아 토큰을 0개 소비해요.
- **효율적인 스크립트 실행:** `validate_form.py`를 실행할 때 스크립트 코드는 컨텍스트 윈도우에 로드되지 않아요. 출력("Validation passed" 같은)만 토큰을 소비하죠. 그래서 스크립트가 Claude가 그때그때 코드를 생성하는 것보다 훨씬 효율적이에요.
- **번들 콘텐츠의 실질적 무제한:** 파일은 접근하기 전까지 컨텍스트를 소비하지 않으니, 포괄적인 API 문서·대용량 데이터셋·방대한 예제를 담아도 돼요. 쓰지 않는 번들 콘텐츠에는 컨텍스트 페널티가 없어요.
### 예시: PDF 처리 스킬 불러오기
앞선 예시의 커스텀 `pdf-processing` 스킬(사전 제작 `pdf` 스킬이 아니라)을 Claude가 어떻게 불러와 쓰는지 볼게요:
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의 지침을 활용해 작업 완료
## 스킬은 어디에서 쓸 수 있나요
스킬은 Claude의 다양한 에이전트 제품에서 사용할 수 있어요.
### Claude API
Claude API는 사전 제작 스킬과 커스텀 스킬을 모두 지원해요. 둘 다 똑같이 동작해요. `container` 파라미터의 `skill_id`와 함께 [코드 실행 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)를 지정하면 돼요.
**전제 조건:** API에서 스킬을 쓰려면 [코드 실행 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)가 필요해요. 이 도구의 컨테이너 안에서 스킬이 실행되거든요.
사전 제작 스킬은 `skill_id`(`pptx`, `xlsx`, `docx`, `pdf`)를 참조해서 쓰고, Skills API(`/v1/skills` 엔드포인트)로 나만의 스킬을 만들어 업로드할 수도 있어요. 커스텀 스킬은 **워크스페이스 전체에 공유**돼서, 워크스페이스의 모든 구성원이 접근할 수 있어요.
API의 스킬은 **네트워크 접근이 없고, 런타임 패키지 설치가 불가능한** 샌드박스 컨테이너에서 실행돼요. 자세한 내용은 Limitations and constraints 부분을 보면 돼요.
더 자세히 알고 싶다면 [API에서 Agent Skills 사용하기](https://platform.claude.com/docs/en/build-with-claude/skills-guide)를 참고하세요.
### Claude Code
[Claude Code](https://code.claude.com/docs/en/overview)는 커스텀 스킬을 지원해요. 사전 제작 문서 스킬(PowerPoint, Excel, Word, PDF)은 Claude Code에서는 쓸 수 없지만, 오픈소스인 [Claude API 스킬](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill)이 번들로 함께 제공돼요. Claude Code에 포함된 [내장 명령과 스킬 전체 목록](https://code.claude.com/docs/en/commands)도 확인해 보세요.
**커스텀 스킬:** SKILL.md 파일이 있는 디렉터리로 스킬을 만들면 돼요. Claude가 자동으로 발견해서 사용해요.
Claude Code의 커스텀 스킬은 파일시스템 기반이라 API 업로드가 필요 없어요. 개인용은 `~/.claude/skills/`, 프로젝트용은 `.claude/skills/`에 두면 돼요.
더 자세히 알고 싶다면 [Claude Code에서 스킬 사용하기](https://code.claude.com/docs/en/skills)를 참고하세요.
### claude.ai
[claude.ai](https://claude.ai)는 사전 제작 스킬과 커스텀 스킬을 모두 지원해요.
**사전 제작 스킬:** 문서를 만들 때 자동으로 활성화돼요. 별도 설정 없이 Claude가 사용해요.
**커스텀 스킬:** Settings > Features에서 zip 파일로 업로드해요. [코드 실행이 활성화된](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude) Pro, Max, Team, Enterprise 요금제에서 사용 가능해요. 커스텀 스킬은 **사용자 개인**에 한정돼요. 조직 전체에 공유되지 않고, 관리자가 중앙에서 관리할 수도 없어요.
claude.ai에서 스킬을 쓰는 자세한 방법은 Claude Help Center 글을 참고하세요:
- [스킬이란 무엇인가요?](https://support.claude.com/en/articles/12512176-what-are-skills)
- [Claude에서 스킬 사용하기](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
- [커스텀 스킬 만드는 방법](https://support.claude.com/en/articles/12512198-creating-custom-skills)
- [스킬로 나만의 작업 방식을 Claude에게 가르치기](https://support.claude.com/en/articles/12580051-teach-claude-your-way-of-working-using-skills)
## 스킬 구조
모든 스킬은 YAML 프론트매터가 있는 `SKILL.md` 파일이 필요해요:
```markdown
---
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에는 무엇을 하는지와 Claude가 언제 써야 하는지 둘 다 반드시 들어가야 해요. 작성법 전체 가이드는 스킬 작성 모범 사례를 참고하세요.
보안 고려 사항¶
스킬은 신뢰할 수 있는 출처에서만 사용하세요. 직접 만들었거나 Anthropic에서 받은 것만요. 스킬은 지침과 코드를 통해 Claude에 새 능력을 부여하는데, 이 말은 악의적인 스킬이 Claude를 조종해서 스킬이 주장하는 목적과 다른 방식으로 도구를 호출하거나 코드를 실행하게 할 수도 있다는 뜻이에요.
주요 보안 고려 사항:
- 철저히 감사하기: 스킬에 번들된 모든 파일(SKILL.md, 스크립트, 이미지, 기타 리소스)을 검토하세요. 예상치 못한 네트워크 호출, 파일 접근 패턴, 또는 스킬이 주장하는 목적과 맞지 않는 동작 같은 특이한 패턴을 살펴보세요.
- 외부 출처는 위험해요: 외부 URL에서 데이터를 가져오는 스킬은 특히 위험해요. 가져온 콘텐츠에 악의적인 지침이 들어 있을 수 있으니까요. 신뢰할 만한 스킬이라도 외부 의존성이 시간에 따라 바뀌면 손상될 수 있어요.
- 도구 남용: 악의적인 스킬이 도구(파일 작업, bash 명령, 코드 실행)를 유해한 방식으로 호출할 수 있어요.
- 데이터 노출: 민감한 데이터에 접근할 수 있는 스킬이 외부 시스템으로 정보를 유출하도록 설계될 수 있어요.
- 소프트웨어 설치처럼 다루기: 민감한 데이터나 중요한 작업에 접근하는 프로덕션 시스템에 스킬을 통합할 때는 특히 조심하세요.
조직 단위의 거버넌스·검증·배포 가이드는 기업용 스킬을 참고하세요. Claude Enterprise 조직은 claude.ai와 Claude Cowork에 업로드한 커스텀 스킬에 대해 스킬 콘텐츠 스캔도 켤 수 있어요. 단, 이 스캔은 Skills API나 Claude Console로 업로드한 스킬에는 적용되지 않아요.
사용 가능한 스킬¶
사전 제작 스킬¶
다음 사전 제작 Agent 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에 제공해요. Claude Code에 번들되어 있고 skills 저장소에서 설치할 수도 있어요.
커스텀 스킬 예시¶
커스텀 스킬의 완전한 예시는 Skills cookbook을 참고하세요.
데이터 보존¶
Agent Skills는 ZDR(제로 데이터 보존) 약정 대상이 아니에요. 스킬 정의와 실행 데이터는 Anthropic의 표준 데이터 보존 정책에 따라 보관돼요.
모든 기능의 ZDR 자격에 대해서는 API와 데이터 보존을 참고하세요.
Skills API 작업의 감사 로깅에 대해서는 API에서 Agent Skills 사용하기 문서의 감사 로깅 부분을 보세요.
제한 사항과 제약 조건¶
Claude Platform on AWS와 Microsoft Foundry는 아래 하위 절에서 설명하는 Claude API와 동일한 제약을 따릅니다.
표면 간 가용성¶
커스텀 스킬은 표면(surface) 간에 동기화되지 않아요. 한 표면에 업로드한 스킬은 다른 표면에서 자동으로 사용할 수 없어요:
- 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:
- 네트워크 접근이 다양함: 사용자/관리자 설정에 따라 스킬이 완전·부분·또는 네트워크 접근 없음일 수 있어요. 자세한 내용은 파일 만들기·편집 지원 문서를 참고하세요.
- Claude API:
- 네트워크 접근 없음: 스킬은 외부 API 호출이나 인터넷 접근을 할 수 없어요.
- 런타임 패키지 설치 불가: 사전 설치된 패키지만 사용 가능해요. 실행 중에 새 패키지를 설치할 수 없어요.
- 사전 구성된 의존성만: 코드 실행 도구 문서에서 사용 가능한 패키지 목록을 확인하세요.
- Claude Code:
- 완전한 네트워크 접근: 스킬은 사용자 컴퓨터의 다른 프로그램과 동일한 네트워크 접근 권한을 가져요.
- 전역 패키지 설치 비권장: 스킬은 사용자 컴퓨터에 간섭하지 않도록 패키지를 로컬에만 설치해야 해요.
이런 제약 안에서 동작하도록 스킬을 설계하세요.