Claude의 스킬(Agent Skills)은 SKILL.md 파일이 든 폴더 하나로 Claude에게 특정 작업의 절차·맥락·모범 사례를 가르치는 기능입니다. 스킬이 무엇이고 어떻게 쓰는지는 Claude Code 스킬 가이드에서 다뤘으니, 이 글은 처음부터 내 스킬을 직접 만드는 실전 과정에 집중합니다. 폴더를 만들고, frontmatter를 채우고, 지침을 쓰고, 설치해 쓰는 순서를 Anthropic 공식 문서 기준으로 정리했습니다.
스킬의 최소 구성
스킬은 폴더 + 그 안의 SKILL.md 파일이 전부입니다. SKILL.md 하나만 있으면 동작하고, 나머지(추가 문서·스크립트·자료)는 모두 선택입니다. SKILL.md는 두 부분으로 나뉩니다 — 맨 위의 YAML frontmatter(Claude가 "언제 이 스킬을 쓸지" 판단하는 메타데이터)와, 그 아래의 마크다운 본문(실제 수행 지침)입니다.
왜 이렇게 동작하나 — 3단계 점진적 공개
스킬의 핵심 설계는 점진적 공개(progressive disclosure)입니다. 모든 내용을 한 번에 불러오지 않고, 필요한 단계까지만 컨텍스트에 올립니다.
| 단계 | 로드 시점 | 토큰 비용 | 내용 |
|---|---|---|---|
| Level 1 · 메타데이터 | 항상(세션 시작) | 스킬당 약 100 토큰 | frontmatter의 name·description |
| Level 2 · 지침 | 스킬이 트리거될 때 | 5천 토큰 미만 | SKILL.md 본문(지침·안내) |
| Level 3 · 리소스 | 필요할 때만 | 사실상 무제한 | 번들 파일을 bash로 실행, 내용은 컨텍스트에 안 올림 |
덕분에 스킬을 수십 개 설치해도 평소에는 이름·설명(약 100토큰)만 차지하고, 실제로 그 스킬이 필요한 순간에만 본문이 로드됩니다.
1단계 — 폴더와 SKILL.md 만들기
스킬 이름으로 폴더를 만들고 그 안에 SKILL.md를 둡니다.
my-skill/
└── SKILL.mdSKILL.md의 기본 골격은 다음과 같습니다.
---
name: my-skill
description: 이 스킬이 무엇을 하고 언제 써야 하는지 짧게 설명
---
# My Skill
## Instructions
[Claude가 따라야 할 단계별 지침]
## Examples
[이 스킬을 쓰는 구체적 예시]2단계 — frontmatter 작성 (가장 중요)
필수 필드는 name과 description 둘뿐입니다. 이 두 줄을 Claude가 세션 시작 때 읽어 "이 스킬을 언제 쓸지" 판단하므로, 품질이 스킬의 성패를 좌우합니다. 공식 문서가 규정한 제약은 다음과 같습니다.
- name: 최대 64자, 소문자·숫자·하이픈만 사용, XML 태그 불가, 예약어
anthropic·claude는 쓸 수 없습니다. - description: 비어 있으면 안 되고 최대 1024자, XML 태그 불가. 무엇을 하는지 + 언제 써야 하는지를 모두 담아야 합니다.
특히 description에는 트리거가 될 키워드를 구체적으로 넣는 것이 좋습니다. 예를 들어 PDF 처리 스킬이라면 이렇게 씁니다.
description: PDF에서 텍스트·표를 추출하고 양식을 채우거나 문서를 병합한다.
PDF·양식·문서 추출을 다루거나 사용자가 PDF를 언급할 때 사용한다.3단계 — 본문(지침) 작성
본문에는 Claude가 따라야 할 절차·모범 사례·예시를 적습니다. 명확한 단계와 구체적 입출력 예시가 핵심입니다. 공식 문서는 본문을 간결하게(대략 500줄 이하) 유지하고, 길어지면 별도 파일로 분리해 링크하도록 권합니다.
4단계 — 자료·스크립트 번들 (선택)
스킬 폴더에는 추가 문서, 스크립트, 참고 자료를 함께 넣을 수 있습니다.
pdf-skill/
├── SKILL.md (메인 지침)
├── FORMS.md (양식 채우기 가이드)
├── REFERENCE.md (상세 레퍼런스)
└── scripts/
└── fill_form.py이 파일들은 참조될 때만 로드됩니다. 특히 스크립트는 Claude가 bash로 실행하고 결과값만 받으므로, 스크립트 코드 자체는 컨텍스트를 차지하지 않습니다. 그래서 방대한 레퍼런스나 데이터셋을 넣어도, 쓰지 않으면 토큰 비용이 사실상 0입니다.
만든 스킬 설치·사용하기
스킬을 쓰는 곳(surface)마다 설치 방법이 다릅니다. 공식 문서에 따르면 커스텀 스킬은 surface 간 자동으로 동기화되지 않으므로, 쓰려는 곳마다 따로 올려야 합니다.
- Claude Code: 파일시스템 기반입니다. 개인용은
~/.claude/skills/, 프로젝트용은.claude/skills/에 스킬 폴더를 두면 Claude가 자동으로 인식합니다. 별도 업로드가 필요 없습니다. - claude.ai: 스킬 폴더를 zip으로 압축해 설정 > 기능(Settings > Features)에서 업로드합니다. 코드 실행이 켜진 Pro·Max·Team·Enterprise 플랜에서 쓸 수 있고, 사용자 개인 단위로 적용됩니다(조직 차원의 공유·중앙 관리는 지원하지 않습니다).
- Claude API:
/v1/skills엔드포인트로 업로드한 뒤, code execution 도구와 함께container에skill_id를 지정합니다. 베타 헤더code-execution-2025-08-25,skills-2025-10-02,files-api-2025-04-14가 필요합니다. 업로드한 커스텀 스킬은 워크스페이스 전체가 공유합니다.
참고로 Claude는 PowerPoint(pptx)·Excel(xlsx)·Word(docx)·PDF(pdf) 같은 사전 제작 스킬도 기본 제공하며, 이들은 별도 설치 없이 문서 작업 시 자동으로 쓰입니다.
작성 팁 (베스트 프랙티스)
- description를 구체적으로: "무엇 + 언제"를 명확히 하고, 트리거 키워드를 충분히 넣어 Claude가 적절한 순간에 스킬을 떠올리게 합니다.
- SKILL.md는 간결하게: 본문이 길어지면 참조 파일로 쪼개고 링크합니다. 100줄을 넘는 참조 문서에는 목차를 답니다.
- 결정적 작업은 스크립트로: 매번 코드를 새로 생성하기보다, 검증·변환 같은 반복 작업은 스크립트로 만들어두면 안정적이고 토큰도 아낄 수 있습니다.
- 예시를 넣기: 구체적인 입출력 예시는 Claude가 스킬을 정확히 따르도록 돕습니다.
보안 주의
스킬은 신뢰할 수 있는 출처(직접 만든 것 또는 Anthropic이 제공한 것)만 쓰는 것이 원칙입니다. 스킬은 Claude에게 도구 호출·코드 실행 능력을 주므로, 악의적 스킬은 데이터 유출이나 무단 접근으로 이어질 수 있습니다. 출처가 불분명한 스킬은 SKILL.md·스크립트·자료를 모두 점검하고, 외부 URL에서 데이터를 가져오는 스킬은 특히 주의해야 합니다. "소프트웨어를 설치하는 것"과 같은 신중함이 필요합니다.
마무리
스킬 만들기는 결국 폴더 하나에 SKILL.md를 두고, frontmatter(name·description)와 지침을 잘 쓰는 일로 요약됩니다. 작게 시작해 실제로 써 보며 description과 지침을 다듬는 것이 가장 빠른 길입니다. 더 자세한 작성 지침은 Anthropic 공식 문서(Agent Skills 개요, 베스트 프랙티스)를 참고하세요.