Agent Skills 만들기

Agent Skills는 Claude의 기능을 확장하는 모듈형 역량입니다. 각 스킬은 지침, 메타데이터, 그리고 선택적 리소스(스크립트, 템플릿)를 하나로 묶어 두며, Claude는 필요할 때 이를 자동으로 활용합니다.

이 기능은 영구 데이터 미보존(ZDR, Zero Data Retention) 대상이 아닙니다. 데이터는 해당 기능의 표준 보존 정책에 따라 보관됩니다.

스킬을 사용하는 이유

스킬은 재사용 가능한 파일시스템 기반 리소스로, Claude에 도메인별 전문성을 제공합니다. 즉 워크플로, 맥락, 모범 사례를 담아 범용 에이전트를 전문가로 탈바꿈시킵니다. 일회성 작업을 위한 대화 단위 지침인 프롬프트와 달리, 스킬은 필요할 때 로드되므로 여러 대화에 걸쳐 같은 안내를 반복해서 제공할 필요가 없습니다.

주요 이점은 다음과 같습니다.

Claude 전문화: 도메인별 작업에 맞게 역량을 맞춤화합니다.
반복 감소: 한 번 만들어 두면 자동으로 재사용됩니다.
역량 결합: 여러 스킬을 조합해 복잡한 워크플로를 구성합니다.

Agent Skills의 아키텍처와 실제 활용 사례를 더 깊이 살펴보려면 엔지니어링 블로그 글 "Equipping agents for the real world with Agent Skills"를 참고하세요.

스킬 사용하기

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

사전 제작 Agent Skills는 claude.ai, Claude API, AWS의 Claude Platform, Microsoft Foundry에서 사용할 수 있습니다. 전체 목록은 Available Skills를 참고하세요.

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

시작하기:

사전 제작 Agent Skills: API에서 PowerPoint, Excel, Word, PDF 스킬을 바로 사용해 보려면 quickstart 튜토리얼을 참고하세요.
커스텀 스킬: 직접 스킬을 만드는 방법은 Agent Skills Cookbook에서 확인하세요.

스킬의 작동 원리

스킬은 Claude의 VM 환경을 활용해, 프롬프트만으로는 불가능한 역량을 제공합니다. Claude는 파일시스템에 접근할 수 있는 가상 머신에서 동작하므로, 스킬은 지침, 실행 가능한 코드, 참조 자료를 담은 디렉터리로 존재할 수 있습니다. 마치 새로 합류한 팀원을 위해 만드는 온보딩 가이드처럼 구성되는 셈입니다.

이러한 파일시스템 기반 아키텍처는 점진적 공개(progressive disclosure)를 가능하게 합니다. 즉 Claude는 모든 정보를 미리 컨텍스트에 채워 넣는 대신, 필요한 단계마다 정보를 나눠서 로드합니다.

스킬 콘텐츠의 세 가지 유형, 로딩의 세 단계

스킬은 세 가지 유형의 콘텐츠를 담을 수 있으며, 각각 서로 다른 시점에 로드됩니다.

1단계: 메타데이터(항상 로드됨)

콘텐츠 유형: 지침. 스킬의 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는 시작 시점에 이 메타데이터를 로드해 시스템 프롬프트에 포함합니다. 이렇게 가벼운 방식 덕분에 컨텍스트 부담 없이 많은 스킬을 설치할 수 있습니다. 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단계: 리소스와 코드(필요할 때 로드됨)

**콘텐츠 유형: 지침, 코드, 리소스.** 스킬에는 추가 자료를 함께 묶어 둘 수 있습니다.

```text
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는 이러한 파일을 참조될 때만 사용합니다. 파일시스템 모델 덕분에 각 콘텐츠 유형은 저마다의 강점을 살립니다. 즉 지침은 유연한 안내에, 코드는 신뢰성에, 리소스는 사실 조회에 적합합니다.

단계	로드 시점	토큰 비용	콘텐츠
1단계: 메타데이터	항상(시작 시점)	스킬당 약 100토큰	YAML frontmatter의 `name`과 `description`
2단계: 지침	스킬이 트리거될 때	5천 토큰 미만	지침과 안내가 담긴 SKILL.md 본문
3단계 이상: 리소스	필요할 때	사실상 무제한	내용을 컨텍스트에 로드하지 않고 bash로 실행되는 번들 파일

점진적 공개 덕분에 어느 시점에도 관련 있는 콘텐츠만 컨텍스트 윈도를 차지합니다.

스킬 아키텍처

스킬은 Claude가 파일시스템 접근, bash 명령, 코드 실행 기능을 갖춘 코드 실행 환경에서 동작합니다. 이렇게 생각하면 됩니다. 스킬은 가상 머신상의 디렉터리로 존재하고, Claude는 여러분이 컴퓨터에서 파일을 탐색할 때 쓰는 것과 똑같은 bash 명령으로 그 디렉터리를 다룹니다.

Claude가 스킬 콘텐츠에 접근하는 방식:

스킬이 트리거되면 Claude는 bash로 SKILL.md를 읽어 그 지침을 컨텍스트 윈도로 가져옵니다. 그 지침이 다른 파일(예: FORMS.md나 데이터베이스 스키마)을 참조하면, Claude는 추가 bash 명령으로 그 파일들도 읽습니다. 지침이 실행 가능한 스크립트를 언급하면, Claude는 bash로 그것을 실행하고 결과만 받습니다(스크립트 코드 자체는 컨텍스트에 들어오지 않습니다).

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

필요할 때만 파일 접근: Claude는 각 작업에 필요한 파일만 읽습니다. 스킬에 참조 파일이 수십 개 들어 있더라도, 작업에 sales 스키마만 필요하다면 Claude는 그 파일 하나만 로드합니다. 나머지는 파일시스템에 남아 토큰을 전혀 소비하지 않습니다.

효율적인 스크립트 실행: Claude가 validate_form.py를 실행할 때, 스크립트의 코드는 컨텍스트 윈도에 로드되지 않습니다. "Validation passed"나 특정 오류 메시지 같은 스크립트의 출력만 토큰을 소비합니다. 그래서 Claude가 즉석에서 같은 코드를 생성하는 것보다 스크립트를 쓰는 편이 훨씬 효율적입니다.

번들 콘텐츠 용량에 사실상 제한 없음: 파일은 접근하기 전까지 컨텍스트를 소비하지 않으므로, 스킬에는 방대한 API 문서, 대용량 데이터셋, 풍부한 예시 등 필요한 참조 자료를 얼마든지 담을 수 있습니다. 사용되지 않는 번들 콘텐츠에는 컨텍스트 비용이 들지 않습니다.

이 파일시스템 기반 모델이 바로 점진적 공개를 작동하게 하는 핵심입니다. 온보딩 가이드의 특정 부분을 찾아보듯, Claude는 여러분의 스킬을 탐색하며 각 작업에 꼭 필요한 부분만 가져옵니다.

예시: PDF 처리 스킬 로드하기

Claude가 PDF 처리 스킬을 로드하고 사용하는 과정은 다음과 같습니다.

시작: 시스템 프롬프트에 다음이 포함됩니다. PDF Processing - Extract text and tables from PDF files, fill forms, merge documents
사용자 요청: "이 PDF에서 텍스트를 추출하고 요약해 줘"
Claude 호출: bash: read pdf-skill/SKILL.md → 지침이 컨텍스트로 로드됨
Claude 판단: 양식 작성은 필요 없으므로 FORMS.md는 읽지 않음
Claude 실행: SKILL.md의 지침을 사용해 작업을 완료함

다이어그램은 다음을 보여 줍니다.

시스템 프롬프트와 스킬 메타데이터가 미리 로드된 기본 상태
Claude가 bash로 SKILL.md를 읽어 스킬을 트리거함
Claude가 필요에 따라 FORMS.md 같은 추가 번들 파일을 선택적으로 읽음
Claude가 작업을 진행함

이러한 동적 로딩 덕분에 관련 있는 스킬 콘텐츠만 컨텍스트 윈도를 차지합니다.

스킬을 사용할 수 있는 곳

스킬은 Claude의 여러 에이전트 제품에서 사용할 수 있습니다.

AWS의 Claude Platform과 Microsoft Foundry는 이어지는 모든 섹션에서 Claude API와 동일한 스킬 동작을 따릅니다.

Claude API

Claude API는 사전 제작 Agent Skills와 커스텀 스킬을 모두 지원합니다. 둘은 동일하게 작동하며, 코드 실행 도구와 함께 container 파라미터에 해당 skill_id를 지정하면 됩니다.

사전 요건: API를 통해 스킬을 사용하려면 다음 세 가지 베타 헤더가 필요합니다.

code-execution-2025-08-25 - 스킬은 코드 실행 컨테이너에서 동작합니다.
skills-2025-10-02 - 스킬 기능을 활성화합니다.
files-api-2025-04-14 - 컨테이너로 파일을 업로드하거나 컨테이너에서 파일을 다운로드하는 데 필요합니다.

사전 제작 Agent Skills는 해당 skill_id(예: pptx, xlsx)를 참조해 사용하고, 직접 만든 스킬은 Skills API(/v1/skills 엔드포인트)를 통해 만들어 업로드합니다. 커스텀 스킬은 워크스페이스 전체에 공유되어, 워크스페이스의 모든 구성원이 접근할 수 있습니다.

자세한 내용은 "Use Skills with the Claude API"를 참고하세요.

Claude Code

Claude Code는 커스텀 스킬만 지원합니다.

커스텀 스킬: SKILL.md 파일이 든 디렉터리로 스킬을 만듭니다. Claude가 이를 자동으로 발견해 사용합니다.

Claude Code의 커스텀 스킬은 파일시스템 기반이며 API 업로드가 필요하지 않습니다.

자세한 내용은 "Use Skills in Claude Code"를 참고하세요.

claude.ai

claude.ai는 사전 제작 Agent Skills와 커스텀 스킬을 모두 지원합니다.

사전 제작 Agent Skills: 이 스킬들은 여러분이 문서를 만들 때 이미 뒤에서 작동하고 있습니다. Claude는 별도의 설정 없이도 이를 사용합니다.

커스텀 스킬: Settings > Features를 통해 직접 만든 스킬을 zip 파일로 업로드합니다. 코드 실행이 활성화된 Pro, Max, Team, Enterprise 요금제에서 사용할 수 있습니다. 커스텀 스킬은 사용자별로 개별 관리되며, 조직 전체에 공유되지 않고 관리자가 중앙에서 관리할 수도 없습니다.

claude.ai에서 스킬을 사용하는 방법은 Claude Help Center의 다음 자료에서 확인하세요.

What are Skills?
Using Skills in Claude
How to create custom Skills
Teach Claude your way of working using Skills

스킬 구조

모든 스킬에는 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에는 스킬이 무엇을 하는지와 Claude가 언제 사용해야 하는지를 모두 담아야 합니다. 작성에 관한 전체 가이드는 모범 사례 가이드를 참고하세요.

보안 고려 사항

스킬은 신뢰할 수 있는 출처, 즉 여러분이 직접 만들었거나 Anthropic에서 받은 것만 사용하세요. 스킬은 지침과 코드를 통해 Claude에 새로운 역량을 부여하는데, 이것이 스킬을 강력하게 만드는 동시에 위험 요소이기도 합니다. 악의적인 스킬은 명시된 목적과 맞지 않는 방식으로 Claude가 도구를 호출하거나 코드를 실행하도록 유도할 수 있습니다.

신뢰할 수 없거나 출처가 불분명한 스킬을 꼭 써야 한다면, 극도로 주의하고 사용 전에 철저히 감사하세요. Claude가 스킬을 실행할 때 어떤 권한을 갖는지에 따라, 악의적인 스킬은 데이터 유출, 무단 시스템 접근 등 보안 위험으로 이어질 수 있습니다.

핵심 보안 고려 사항:

철저히 감사하기: 스킬에 묶인 모든 파일, 즉 SKILL.md, 스크립트, 이미지, 기타 리소스를 검토하세요. 예상치 못한 네트워크 호출, 비정상적인 파일 접근 패턴, 스킬의 명시된 목적과 맞지 않는 동작 같은 이상 징후를 살피세요.
외부 출처는 위험함: 외부 URL에서 데이터를 가져오는 스킬은 특히 위험합니다. 가져온 콘텐츠에 악의적인 지침이 들어 있을 수 있기 때문입니다. 신뢰할 만한 스킬이라도 외부 의존성이 시간이 지나며 변질되면 침해될 수 있습니다.
도구 오용: 악의적인 스킬은 도구(파일 작업, bash 명령, 코드 실행)를 해로운 방식으로 호출할 수 있습니다.
데이터 노출: 민감한 데이터에 접근하는 스킬은 정보를 외부 시스템으로 유출하도록 설계될 수 있습니다.
소프트웨어 설치처럼 다루기: 신뢰할 수 있는 출처의 스킬만 사용하세요. 특히 민감한 데이터나 중요한 운영에 접근하는 프로덕션 시스템에 스킬을 통합할 때는 각별히 주의하세요.

사용 가능한 스킬

사전 제작 Agent Skills

다음 사전 제작 Agent Skills를 바로 사용할 수 있습니다.

PowerPoint (pptx): 프레젠테이션 생성, 슬라이드 편집, 프레젠테이션 콘텐츠 분석
Excel (xlsx): 스프레드시트 생성, 데이터 분석, 차트가 포함된 보고서 생성
Word (docx): 문서 생성, 콘텐츠 편집, 텍스트 서식 지정
PDF (pdf): 서식이 적용된 PDF 문서와 보고서 생성

이 스킬들은 Claude API, AWS의 Claude Platform, Microsoft Foundry, claude.ai에서 사용할 수 있습니다. API에서 사용을 시작하려면 quickstart 튜토리얼을 참고하세요.

오픈소스 스킬

Anthropic은 skills 저장소에 오픈소스 스킬도 공개합니다.

Claude API: 8개 프로그래밍 언어에 대한 최신 API 레퍼런스, SDK 문서, 모범 사례를 Claude에 제공합니다. Claude Code에 기본 번들로 포함되어 있으며, skills 저장소에서 설치할 수도 있습니다.

커스텀 스킬 예시

커스텀 스킬의 전체 예시는 Skills cookbook을 참고하세요.

데이터 보존

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

모든 기능에 대한 ZDR 적용 자격은 "API and data retention"을 참고하세요.

한계와 제약

이러한 한계를 이해하면 스킬 배포를 효과적으로 계획할 수 있습니다. AWS의 Claude Platform과 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 Plugins를 통해 공유할 수도 있습니다.

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

런타임 환경 제약

스킬에 제공되는 정확한 런타임 환경은 스킬을 사용하는 제품 서피스에 따라 달라집니다.

claude.ai:
가변적인 네트워크 접근: 사용자/관리자 설정에 따라 스킬은 전체, 부분, 또는 없음 수준의 네트워크 접근을 가질 수 있습니다. 자세한 내용은 "Create and Edit Files" 지원 문서를 참고하세요.
Claude API:
네트워크 접근 불가: 스킬은 외부 API를 호출하거나 인터넷에 접근할 수 없습니다.
런타임 패키지 설치 불가: 사전 설치된 패키지만 사용할 수 있으며, 실행 중에 새 패키지를 설치할 수 없습니다.
사전 구성된 의존성만 사용 가능: 사용 가능한 패키지 목록은 코드 실행 도구 문서를 확인하세요.
Claude Code:
전체 네트워크 접근: 스킬은 사용자 컴퓨터의 다른 프로그램과 동일한 수준의 네트워크 접근을 갖습니다.
전역 패키지 설치 지양: 스킬은 사용자 컴퓨터에 간섭하지 않도록 패키지를 로컬에만 설치해야 합니다.

이러한 제약 안에서 작동하도록 스킬을 계획하세요.