SKILL.md 완전 가이드
Claude 스킬 파일의 구조, 작성법, 최적화 방법
SKILL.md는 Claude에게 특정 작업을 수행하는 방법을 가르치는 지침 파일입니다. Claude가 특정 요청을 받으면 관련 SKILL.md를 먼저 읽고, 그 안의 지침에 따라 작업을 수행합니다. 스킬은 Claude의 기본 능력 위에 도메인별 전문 지식과 최적화된 워크플로우를 추가하는 방식으로 동작합니다.
1. 파일 구조
스킬은 단일 파일이 아니라 폴더 단위로 구성됩니다.
skill-name/ ├── SKILL.md ← 필수: 메인 지침 파일 ├── scripts/ ← 선택: 반복 작업용 실행 스크립트 ├── references/ ← 선택: 참고 문서 (필요 시에만 로딩) └── assets/ ← 선택: 템플릿, 폰트, 아이콘 등
스킬 폴더는 기본적으로 .claude/skills/ 경로 아래에 위치합니다. 사용자가 설치한 플러그인 스킬은 원격 플러그인 경로에 위치하기도 합니다.
2. SKILL.md 기본 형식
모든 SKILL.md는 YAML 프론트매터(frontmatter)로 시작하고, 그 아래에 마크다운 형식의 지침 본문이 이어집니다.
--- name: skill-name description: 이 스킬이 무엇을 하는지, 언제 사용해야 하는지에 대한 설명. Claude가 스킬을 선택할 때 이 description만 보고 판단합니다. --- # 스킬 제목 ## 작업 방식 여기에 Claude가 따라야 할 지침을 작성합니다.
3. 프론트매터 필드 상세
name (필수)
스킬의 고유 식별자입니다. 폴더명과 일치시키는 것이 관례입니다.
name: docx
description (필수, 가장 중요)
Claude가 어떤 스킬을 사용할지 결정할 때 오직 이 필드만 참고합니다. description에는 두 가지를 반드시 담아야 합니다.
- 무엇을 하는 스킬인지 — 기능 설명
- 언제 사용해야 하는지 — 트리거 조건 (구체적인 키워드 포함)
description: | Word 문서(.docx)를 생성, 수정, 분석하는 스킬. 'Word 문서', '.docx', '보고서', '계약서', '레터헤드'라는 단어가 나오거나 전문 문서 포맷이 필요한 경우 반드시 사용.
compatibility (선택)
필요한 외부 도구나 의존성을 명시합니다. 대부분의 스킬에서는 생략합니다.
compatibility: requires: [node, pandoc]
4. 3단계 로딩 시스템
스킬의 모든 내용이 항상 Claude의 컨텍스트에 올라가 있는 것은 아닙니다. 효율을 위해 3단계로 나뉘어 필요할 때만 로딩됩니다.
이 구조 덕분에 references/ 폴더에 수천 줄의 참고 문서를 두어도 컨텍스트 낭비 없이 필요한 시점에만 불러올 수 있습니다.
5. 본문 작성 패턴
기본 구조
--- name: my-skill description: 이 스킬이 하는 일과 언제 사용해야 하는지. --- # My Skill ## 개요 이 스킬이 왜 필요한지, 어떤 문제를 해결하는지 간략히 설명. ## 작업 순서 1. 첫 번째 단계 2. 두 번째 단계 3. 세 번째 단계 ## 출력 형식 결과물이 어떤 형태여야 하는지 명시. ## 주의사항 흔한 실수나 피해야 할 패턴. ## 참고 파일 - 상세 API 문서: `references/api.md` (복잡한 포맷 작업 시 참조) - 템플릿: `assets/template.docx`
출력 포맷 정의 패턴
## 보고서 구조 항상 아래 템플릿을 정확히 사용할 것: # [제목] ## 요약 ## 주요 발견사항 ## 권고사항
예시(Example) 패턴
## 커밋 메시지 형식 **예시 1:** 입력: JWT 토큰으로 사용자 인증 추가 출력: feat(auth): implement JWT-based authentication **예시 2:** 입력: 로그인 버튼 클릭 시 오류 수정 출력: fix(ui): resolve login button click error
참고 파일 링크 패턴
## 상세 설정
기본 사용법은 이 파일의 지침으로 충분합니다.
고급 테이블 포맷이 필요하면 `references/tables.md`를 읽을 것.
이미지 삽입 방법은 `references/images.md` 참조.
6. scripts/ 폴더 활용
반복적이거나 복잡한 작업(파일 변환, 압축, 검증 등)은 스크립트로 분리하면 매번 Claude가 같은 코드를 작성하는 낭비를 줄일 수 있습니다.
scripts/ ├── create_docx.js ← docx 파일 생성 ├── validate.py ← 출력 결과 검증 └── pack.py ← 파일 패키징
SKILL.md에서 스크립트를 참조하는 방식:
## 문서 생성
항상 `scripts/create_docx.js`를 사용해 파일을 생성할 것.
직접 코드를 작성하지 말고 스크립트를 실행할 것:
```bash
node scripts/create_docx.js --output result.docx
```
scripts/에 한 번 저장해두는 것이 맞습니다. 이후 모든 실행에서 재작성하는 낭비를 막습니다.
7. 좋은 예 vs 나쁜 예
--- name: report description: 보고서를 만듭니다. --- 보고서를 잘 만들어주세요. 깔끔하고 전문적으로. ALWAYS 마크다운을 사용하세요. NEVER 표를 빠뜨리세요.
--- name: report description: | 전문 보고서·분석 문서를 작성하는 스킬. '보고서', '문서 작성', '발표 자료 정리' 등 구조화된 문서가 필요할 때 반드시 사용. --- # Report Skill ## 목적 독자가 핵심을 빠르게 파악할 수 있는 구조화된 문서를 만드는 것이 목표입니다. 의사결정을 돕는 문서를 지향합니다.
나쁜 예의 문제점: description이 짧아 트리거 안 됨 · 지침에 이유(why)가 없음 · ALWAYS/NEVER 남용으로 경직된 동작
8. references/ 폴더 활용
SKILL.md 본문을 500줄 이하로 유지하면서도 깊은 내용을 담으려면 references/를 활용합니다.
references/ ├── advanced-tables.md ← 복잡한 테이블 작성법 ├── xml-schema.md ← XML 구조 레퍼런스 └── api-guide.md ← 외부 API 사용 가이드
# API Guide ## 목차 - [인증](#인증) - [문서 생성](#문서-생성) - [파일 업로드](#파일-업로드) ## 인증 ...
9. 멀티 도메인 스킬 구성
하나의 스킬이 여러 환경이나 플랫폼을 지원할 때 도메인별로 분리합니다.
cloud-deploy/ ├── SKILL.md ← 공통 워크플로우 + 플랫폼 선택 로직 └── references/ ├── aws.md ← AWS 전용 설정 ├── gcp.md ← GCP 전용 설정 └── azure.md ← Azure 전용 설정
SKILL.md에서 플랫폼을 분기하는 방식:
## 플랫폼 선택
사용자가 언급한 플랫폼에 따라 해당 references 파일을 읽을 것:
- AWS → `references/aws.md`
- GCP → `references/gcp.md`
- Azure → `references/azure.md`
명시하지 않은 경우 어떤 플랫폼을 사용할지 먼저 확인할 것.
10. 스킬 작성 체크리스트
name이 폴더명과 일치하는가description에 기능 설명과 트리거 조건이 모두 있는가description이 충분히 구체적인가 (너무 짧으면 트리거 안 됨)
- 500줄 이하인가 (초과 시 references/로 분리)
- 각 지침에 이유(why)가 설명되어 있는가
- ALWAYS/NEVER를 최소화하고 판단 기준을 설명했는가
- 예시(example)가 포함되어 있는가
- 참조 파일이 있다면 명확히 링크했는가
- 반복 작업은 scripts/로 분리했는가
- 대용량 참고 문서는 references/로 분리했는가
- references/ 파일에 목차가 있는가
11. 실전 예시: 번역 스킬
처음부터 끝까지 완성된 스킬 파일 예시입니다.
--- name: translate description: | 텍스트 번역 스킬. '번역해줘', 'translate', '한국어로', '영어로', '일본어로' 등의 요청이 있을 때 반드시 사용. 단순 번역부터 문서 전체 번역, 전문 용어가 포함된 기술·법률·의학 번역까지 모두 이 스킬로 처리. --- # Translate Skill ## 목적 단순히 단어를 옮기는 것이 아니라 원문의 톤, 뉘앙스, 문화적 맥락을 자연스럽게 전달하는 번역을 제공합니다. ## 번역 원칙 - 직역보다 의역을 우선합니다 (자연스러움이 목표) - 전문 용어는 해당 분야의 관례적 표현을 따릅니다 - 타겟 언어의 문장 구조와 표현 방식을 따릅니다 ## 출력 형식 번역문만 출력합니다. 번역이 어색하거나 여러 해석이 가능한 경우, 번역문 아래에 간략히 표기합니다: `[참고] 원문의 X는 Y로도 해석될 수 있습니다.` ## 전문 번역 기술, 법률, 의학 등 전문 분야의 경우 `references/domain-terms.md`를 참조할 것.
설치 위치
.claude/skills/translate/SKILL.md
스킬 작성이 완료되면 skill-creator 스킬을 통해 테스트하고 .skill 파일로 패키징해 공유할 수 있습니다.
12. OpenClaw에서의 스킬
SKILL.md는 Claude에만 국한된 개념이 아닙니다. OpenClaw는 오픈소스 자율 AI 에이전트 플랫폼으로, Claude와 유사한 스킬/플러그인 시스템을 채택하고 있습니다. 어떤 LLM을 쓰든 스킬 구조의 핵심 원리는 동일합니다.
Claude vs OpenClaw 스킬 비교
| 항목 | Claude (Cowork/Claude Code) | OpenClaw |
|---|---|---|
| 스킬 파일 | SKILL.md | 플러그인(Plugin) 단위 |
| 패키지 형식 | .skill 파일 | .plugin 파일 / npm 패키지 |
| 트리거 방식 | description 필드 → LLM 판단 | 명령어 기반 + LLM 라우팅 |
| LLM 의존성 | Claude 전용 | LLM 무관 (GPT, Claude, Gemini 등) |
| 실행 환경 | Cowork VM / 터미널 | 자체 호스팅 Node.js 서비스 |
| 대표 스킬 예시 | docx, pptx, pdf, xlsx | Atlas (문서 검색), SecureClaw (보안) |
공통 설계 원칙
플랫폼이 달라도 잘 설계된 스킬의 원칙은 같습니다.
- 단일 책임 — 스킬 하나는 한 가지 도메인에 집중합니다
- 명확한 트리거 조건 — 언제 사용해야 하는지가 정의되어 있습니다
- 점진적 로딩 — 항상 필요한 것만 컨텍스트에 올립니다
- 재사용 가능한 스크립트 — 반복 작업은 코드로 분리합니다
13. Universe Skills
OpenClaw의 RL(강화학습) 맥락에서 Universe는 AI 에이전트가 실제로 동작하는 환경(environment)을 의미합니다. 브라우저, OS, 특정 앱, API 등이 모두 Universe가 될 수 있습니다. Universe Skills는 특정 환경에 종속되지 않고 여러 Universe에서 동작할 수 있는 스킬을 말합니다.
Universe의 종류
OS Universe
파일 시스템, 앱 실행, 시스템 설정 등 OS 수준 작업
Browser Universe
웹 탐색, 폼 입력, 데이터 스크래핑 등 브라우저 내 작업
API Universe
외부 서비스 호출, 데이터 송수신, 인증 처리
Messaging Universe
Slack, Telegram, WhatsApp 등 메신저 내 작업
Universe-agnostic 스킬 설계
좋은 Universe Skill은 실행 환경에 관계없이 동일하게 동작합니다. 이를 위해 환경 감지 로직을 스킬 초반에 두는 패턴을 씁니다.
## 환경 감지
작업 시작 전 현재 환경을 확인할 것:
- 브라우저 접근 가능 → `references/browser-actions.md` 참조
- API 키 존재 → `references/api-actions.md` 참조
- OS 직접 접근 → `references/os-actions.md` 참조
어떤 환경에서도 최종 출력 형식은 동일하게 유지할 것.
Atlas가 Universe Skill인 이유
OpenClaw의 Atlas 플러그인은 대표적인 Universe Skill입니다. 문서가 로컬 파일이든, 웹 URL이든, API 응답이든 관계없이 동일한 Vectorless RAG 방식으로 검색하고 인용합니다. 환경에 종속되지 않는 추상화가 핵심입니다.
14. Skill Gap
Skill Gap은 AI가 현재 수행할 수 있는 것과 실제 전문가 수준의 정확도 사이의 간격을 말합니다. 이 간격을 메우는 것이 AI 트레이닝의 핵심 과제이며, 전문가 라벨링·평가 플랫폼 생태계(Scale, Surge, Outlier, Mercor, Appen 등)가 존재하는 이유이기도 합니다.
Skill Gap의 구조
Skill Gap을 채우는 방법
Skill Gap은 전문 지식과 문서의 결합을 통해 채워집니다. 한 곳이 전부를 담당하기보다, 아래와 같은 플랫폼·도구들이 라벨링 · 평가 · 워크플로 관리 역할을 나눕니다.
전문가 라벨링·평가 플랫폼 생태계
| 플랫폼 | 주요 역할 | 특징 |
|---|---|---|
| Scale AI | RLHF, 레드팀, 대규모 평가 | 프론티어 랩·엔터프라이즈 대상, 엔드투엔드 데이터 파이프라인 |
| Surge AI | 고품질 LLM 학습 데이터 | 선호도 랭킹, 창작·추론 품질 검증에 강점 |
| Outlier | 도메인 전문가 크라우드 | Scale 생태계 · 의료·법률·코딩 등 분야별 평가·라벨링 |
| Mercor | 검증된 전문가 매칭 | 프로젝트별 전문가 채용·온보딩에 특화 |
| Appen | 글로벌 크라우드 어노테이션 | 다국어·음성·비전 등 전통 NLP/ML 라벨링 규모 |
| Toloka | 대규모 마이크로태스크 | 분류·랭킹·수집 등 대량 라벨링 속도 |
| Sama | 윤리적 소싱 어노테이션 | 컴퓨터 비전·NLP, 공급망 투명성 강조 |
| Labelbox | 라벨링 워크플로 플랫폼 | ML 팀이 자체 데이터·어노테이터를 관리하는 SaaS |
| Snorkel AI | 프로그래매틱 라벨링 | 규칙·약지도(weak supervision)로 라벨 생성 자동화 |
| Invisible | 전문가 팀 임베딩 | 모델 트레이닝·평가 운영을 외주형 전문 인력으로 수행 |
같은 “전문가 라벨링”이라도 초점이 다릅니다. Scale·Surge는 프론티어 모델 품질·RLHF에, Outlier·Mercor는 분야별 전문가 풀에, Appen·Toloka·Sama는 다국어·대량·비전/음성 데이터에, Labelbox·Snorkel은 기업 내부 파이프라인 구축에 가깝습니다. 실무에서는 여러 벤더를 조합하거나, 자체 스킬·루브릭으로 평가 기준을 고정한 뒤 외부 플랫폼에 태스크만 분배하기도 합니다.
공통 작업 유형
- 전문가 라벨링 — 의사, 변호사, 엔지니어 등이 AI 출력을 직접 평가하고 교정
- 문서 기반 검증 — 실제 전문 문서(논문, 판례, 매뉴얼 등)와 비교해 정확도 측정
- 루브릭 기반 평가 — 분야별 평가 기준을 전문가가 직접 설계
- 다언어·다분야 동시 진행 — 언어와 도메인에 관계없이 동시다발적으로 진행
스킬과 Skill Gap의 관계
잘 설계된 SKILL.md는 Skill Gap을 줄이는 도구입니다. 스킬 안에 전문가의 판단 기준, 체크리스트, 도메인 특화 지식을 담으면 AI가 그 전문성을 따라 동작하게 됩니다. 즉, 스킬 파일은 전문 지식을 코드화한 것입니다.
## 의료 보고서 검토 기준 ← 전문가 판단 기준을 스킬에 내재화 다음 항목을 반드시 확인할 것: - 진단 코드(ICD-10)가 증상과 일치하는가 - 처방 용량이 체중·나이 기준을 벗어나지 않는가 - 금기 약물 조합이 포함되어 있는가 불확실한 경우 "전문의 확인 필요" 표기 후 진행.