클로드 코드(Claude Code)에서 **스킬(Skills)**은 가장 강력한 확장 기능 중 하나입니다. 같은 지시를 매번 반복해서 입력하는 것이 번거로우셨다면, 스킬 기능이 바로 그 문제를 해결해 줄 수 있습니다.
이 글에서는 클로드 코드 스킬이 무엇인지, 어떻게 동작하는지, 그리고 직접 만들어 사용하는 방법까지 쉬운 예제와 함께 차근차근 알려드리겠습니다.
📌 클로드 코드(Claude Code)란? Anthropic이 제공하는 에이전트형 코딩 도구로, 터미널, IDE, 데스크톱 앱, 브라우저 등 다양한 환경에서 클로드에게 코딩 작업을 맡길 수 있습니다. 이 글에서 다루는 스킬 기능은 Claude.ai와 Claude API에서도 동일한 형식으로 사용할 수 있습니다.
1. 스킬(Skills)이란 무엇인가요?
스킬은 클로드(Claude)에게 특정 작업을 수행하는 방법을 미리 알려주는 폴더입니다. 한 번 만들어두면 클로드가 관련 작업을 할 때마다 알아서 그 지침을 참고하기 때문에, 매번 같은 설명을 반복할 필요가 없습니다.
Anthropic의 공식 문서에 따르면, 스킬은 워크플로, 컨텍스트, 모범 사례를 담은 재사용 가능한 파일시스템 기반 리소스입니다. 일반적인 프롬프트가 한 번의 대화에서만 적용되는 일회성 지시라면, 스킬은 여러 대화에 걸쳐 동일한 지침을 반복하지 않아도 되도록 만들어줍니다.
핵심 특징을 정리하면 다음과 같습니다.
- 폴더 단위로 구성되며, 그 안에
SKILL.md파일이 반드시 들어 있습니다. - 클로드가 작업 내용에 맞춰 자동으로 관련 스킬을 불러옵니다.
- 필요한 시점에만 로드되기 때문에 컨텍스트(맥락) 창을 효율적으로 사용합니다.
- 공식 문서 작성용(PDF, Word, Excel, PowerPoint 등) 스킬은 Anthropic에서 미리 만들어 제공합니다.
💡 참고: 스킬은 클로드 코드뿐 아니라 Claude.ai, Claude API에서도 동일한 형식으로 동작하도록 설계된 Agent Skills 공개 표준을 따릅니다.
2. 스킬이 왜 필요한가요?
스킬 기능이 만들어진 배경에는 몇 가지 명확한 이유가 있습니다.
1) 반복되는 지시를 한 번에 정리할 수 있습니다
매번 새로운 대화를 시작할 때마다 "우리 회사 브랜드 컬러는 #FF6B35이고, 헤더는 Montserrat Bold를 써주세요"라고 입력하는 건 번거롭습니다. 스킬에 한 번만 적어두면 이후로는 자동으로 적용됩니다.
2) 컨텍스트 창을 효율적으로 씁니다
스킬은 점진적 공개(Progressive Disclosure) 방식으로 동작합니다. 처음에는 스킬의 이름과 설명(description)만 클로드의 시스템 프롬프트에 로드되고, 실제로 그 스킬이 필요한 순간이 오면 그제서야 본문 내용을 읽어 들입니다.
이 덕분에 수십 개의 스킬을 설치해두어도 평소에는 컨텍스트를 거의 잡아먹지 않습니다.
3) 팀과 공유하기 쉽습니다
스킬은 단순한 폴더이므로 Git으로 버전 관리가 가능하고, 팀원들과 동일한 작업 표준을 공유할 수 있습니다.
스킬 vs CLAUDE.md vs MCP — 무엇이 다른가요?
처음 클로드 코드를 접하면 비슷해 보이는 개념들이 많아 헷갈리실 수 있습니다. 간단히 정리하면 다음과 같습니다.
- CLAUDE.md — 프로젝트의 영구적인 컨텍스트 파일로, 매 대화마다 항상 로드됩니다. 짧은 사실 정보(우리 회사는 무엇을 하는지, 사용하는 기술 스택은 무엇인지 등)에 적합합니다.
- 스킬(Skills) — 필요할 때만 로드되는 절차적 지침입니다. 본문이 길어도 사용하지 않는 동안에는 컨텍스트를 차지하지 않습니다.
- MCP(Model Context Protocol) — 외부 도구와 시스템에 연결해서 새로운 기능을 추가합니다(예: Slack, Asana, 데이터베이스 등).
공식 문서에서는 CLAUDE.md의 한 섹션이 단순한 사실 정보가 아니라 점점 절차적인 내용으로 자라났다면, 그것이 스킬로 옮겨야 할 신호라고 설명합니다.
3. 스킬의 구조 — SKILL.md 파일 살펴보기
모든 스킬은 SKILL.md라는 마크다운 파일을 중심으로 구성됩니다. 이 파일은 두 부분으로 나뉩니다.
- YAML 프론트매터(Frontmatter) — 스킬의 메타데이터(이름, 설명 등)
- 마크다운 본문 — 클로드가 따라야 할 실제 지침
가장 기본적인 SKILL.md 예시
Anthropic 공식 스킬 저장소에서 제공하는 템플릿은 다음과 같이 생겼습니다.
---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---
# My Skill Name
[클로드가 이 스킬을 활성화했을 때 따를 지침을 여기에 작성합니다]
## Examples
- 사용 예시 1
- 사용 예시 2
## Guidelines
- 가이드라인 1
- 가이드라인 2
프론트매터의 필수 필드
공식 문서에 따르면, YAML 프론트매터에는 두 개의 필드가 필수입니다.
| 필드 | 설명 | 제한 |
|---|---|---|
name |
스킬 이름. 슬래시 명령어로도 사용됩니다. | 최대 64자, 소문자/숫자/하이픈만 허용 |
description |
스킬이 무엇을 하고 언제 써야 하는지에 대한 설명 | 최대 1024자 |
description이 가장 중요합니다. 클로드는 이 설명만 보고 "지금 이 스킬을 써야 할까?"를 판단하기 때문입니다. 그래서 "무엇을 하는지 + 언제 써야 하는지"를 명확하게 적어야 합니다.
폴더 구조
스킬은 단순한 마크다운 파일이 아니라 폴더입니다. 필요하다면 보조 파일들을 함께 넣을 수 있습니다.
my-skill/
├── SKILL.md (필수)
├── scripts/ (선택: 클로드가 실행할 수 있는 스크립트)
├── references/ (선택: 필요할 때 참고하는 추가 문서)
└── assets/ (선택: 템플릿, 아이콘, 폰트 등)
💡 팁: 공식 모범 사례 가이드에서는 SKILL.md 본문을 500줄 이내로 유지하라고 권장합니다. 그보다 길어지면 별도 파일로 쪼개는 것이 좋습니다.
4. 직접 만들어보는 간단한 스킬 예제
이론은 이쯤 하고, 실제로 동작하는 간단한 스킬 하나를 만들어보겠습니다.
예제: 코드 설명 스킬 만들기
Claude Code 공식 문서에서 소개하는 예제를 그대로 따라가 보겠습니다. 코드를 받았을 때 비유와 다이어그램을 사용해 설명하도록 가르치는 스킬입니다.
1단계: 폴더와 파일 만들기
홈 디렉터리 아래에 다음 경로로 파일을 만듭니다.
~/.claude/skills/explain-code/SKILL.md
2단계: 파일에 내용 작성하기
---
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---
When explaining code, always include:
1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?
3단계: 사용해보기
이제 클로드 코드 안에서 코드 파일을 보여주며 "이 코드 어떻게 동작해?"라고 물어보면, 클로드가 자동으로 이 스킬을 불러와 비유와 다이어그램을 곁들인 설명을 해줍니다. 또는 명시적으로 /explain-code 명령어로 호출할 수도 있습니다.
폴더 위치 두 가지 — 개인용 vs 프로젝트용
스킬을 어디에 두느냐에 따라 적용 범위가 달라집니다.
- 개인용(User-level) —
~/.claude/skills/경로에 두면 모든 프로젝트에서 사용할 수 있습니다. - 프로젝트용(Project-level) — 프로젝트 폴더 안의
.claude/skills/경로에 두면 해당 프로젝트에서만 적용되며, Git을 통해 팀원들과 공유할 수 있습니다.
5. 한 단계 더 — 좋은 description 쓰는 법
스킬을 만들어도 클로드가 알아서 써주지 않는다면 십중팔구 description이 모호하기 때문입니다. 공식 문서와 모범 사례에서 강조하는 좋은 description의 공식은 다음과 같습니다.
무엇을 하는지 + 언제 써야 하는지 + 핵심 기능
나쁜 예와 좋은 예 비교
❌ 나쁜 예시:
description: Helps with code
너무 광범위해서 클로드가 언제 호출해야 할지 판단할 수 없습니다.
✅ 좋은 예시:
description: Reviews pull requests for security vulnerabilities using OWASP Top 10. Use when reviewing PRs, auditing code for security issues, or when the user mentions security review.
이렇게 적으면 클로드는 "PR 리뷰", "보안 검토" 같은 키워드가 등장할 때 자동으로 이 스킬을 활성화합니다.
💡 공식 가이드의 팁: 클로드는 스킬을 "덜 호출하는" 경향이 있다고 알려져 있습니다. 그래서 description에 트리거 단어들을 명시적으로 적어주는 것이 활성화율을 높이는 데 도움이 됩니다.
6. 미리 만들어진 스킬 사용하기
직접 만들지 않아도 Anthropic이 제공하는 공식 스킬들을 바로 쓸 수 있습니다. 대표적으로는 다음과 같은 것들이 있습니다.
- docx — Word 문서 생성, 편집, 분석
- pdf — PDF 텍스트/표 추출, 폼 작성, 병합/분할
- pptx — PowerPoint 슬라이드 생성 및 편집
- xlsx — Excel 스프레드시트 작업
- claude-api — Claude API 사용 시 최신 SDK 문서와 모범 사례 제공
이 스킬들은 Anthropic 공식 스킬 저장소에서 확인할 수 있고, 유료 플랜(Pro, Max, Team, Enterprise)의 Claude.ai에서는 이미 사용 가능하도록 준비되어 있습니다.
클로드 코드에서 플러그인으로 설치하기
클로드 코드에서는 Anthropic 공식 스킬 저장소를 플러그인 마켓플레이스로 등록해서 스킬을 설치할 수 있습니다. 클로드 코드 안에서 다음 명령을 입력하면 됩니다.
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills
설치 후에는 "PDF 스킬을 써서 이 파일의 폼 필드를 추출해줘" 같이 자연스럽게 요청하면 클로드가 알아서 해당 스킬을 사용합니다.
7. 스킬 사용 가능 환경
공식 도움말 문서에 따르면, 커스텀 스킬은 다음 환경에서 사용할 수 있습니다.
- Claude.ai — Pro, Max, Team, Enterprise 플랜에서 코드 실행이 활성화된 경우 사용 가능합니다. 설정(Settings) → 기능(Features)에서 zip 파일로 업로드합니다.
- Claude API — Skills API를 통해 업로드하고 사용할 수 있습니다.
- 클로드 코드 —
.claude/skills/디렉터리에 폴더로 두거나 플러그인 마켓플레이스로 설치합니다.
⚠️ 중요: 공식 문서에 따르면, 한 곳에 업로드한 스킬이 다른 환경으로 자동 동기화되지는 않습니다. 즉 Claude.ai에 업로드한 스킬은 API에 별도로 업로드해야 하고, 클로드 코드의 스킬은 파일시스템 기반이라 둘 모두와 별개로 관리됩니다.
8. 안전하게 사용하기 위한 주의사항
스킬은 강력한 만큼 사용에 주의가 필요합니다. Anthropic 공식 문서에서도 다음을 강조하고 있습니다.
- 신뢰할 수 있는 출처의 스킬만 사용하세요. 스킬은 클로드 환경에서 임의의 코드를 실행할 수 있습니다. 본인이 직접 만들었거나 Anthropic이 공식 제공하는 스킬을 우선적으로 사용할 것이 권장됩니다.
- 민감 정보를 하드코딩하지 마세요. API 키, 비밀번호, 토큰 같은 정보는 스킬 파일에 직접 적지 말아야 합니다.
- 외부에서 받은 스킬은 활성화 전에 내용을 검토하세요.
9. 정리
여기까지 클로드 코드 스킬 기능에 대해 알아보았습니다. 핵심을 다시 한번 정리하면 다음과 같습니다.
- 스킬은 클로드에게 특정 작업 방법을 알려주는 폴더입니다.
- SKILL.md 파일 하나만 있으면 시작할 수 있고, 프론트매터의
name과description이 핵심입니다. - 점진적 공개 방식 덕분에 많이 설치해도 컨텍스트 창을 거의 차지하지 않습니다.
- 개인용은
~/.claude/skills/, **프로젝트용은 프로젝트의.claude/skills/**에 둡니다. - 공식 스킬을 그대로 쓰거나, 직접 만들어서 팀과 공유하거나, 마켓플레이스에서 가져올 수 있습니다.
매일 같은 지시를 반복하고 있다면, 그것이 바로 스킬로 만들어야 한다는 신호입니다. 작은 스킬 하나부터 시작해보시면 워크플로가 한층 가벼워지는 것을 느끼실 수 있을 겁니다.