SKILL.md 구조 완전 해부
SKILL.md의 구성 요소, 필수·선택 필드, 좋은 스킬의 3원칙과 나쁜 스킬의 5가지 함정을 예시 중심으로 정리한 작성 가이드
한 줄 요약
SKILL.md는 4부 구조(이름·설명 / 입력 / 처리 규칙 / 출력 형식)만 지키면 충분합니다. 좋은 스킬의 3원칙은 명확한 입출력 · 구체적 처리 규칙 · 재사용 가능한 범용성 입니다.
기본 뼈대
---
name: weekly-review
description: "주간 업무 로그를 한 장 리뷰로. 한국어 지시 예: 이번 주 리뷰 만들어줘 / weekly review."
---
# 주간 리뷰 스킬
## 입력
- 자유 형식 업무 로그 (메모·회의 메모·할 일 혼재 OK)
## 처리 규칙
1. 입력을 3영역으로 분류: 완료 · 진행중 · 블로커
2. 각 영역의 핵심 3개만 추출
3. 다음 주 Top 3 우선순위 + 왜 중요한가 한 줄씩
4. 모호한 항목은 질문으로 남김
## 출력 형식
- 제목 + 주간 기간
- 3영역 요약 (완료 / 진행중 / 블로커)
- 다음 주 Top 3
- 열린 질문 (있으면)이것이 최소 유효 SKILL.md. 이 뼈대만 지키면 바로 쓸 수 있습니다.
필수 vs 선택 필드
Frontmatter
| 필드 | 필수 | 설명 |
|---|---|---|
name | ✅ | 스킬의 영문 식별자. 소문자 + 하이픈. 예: weekly-review |
description | ✅ | 한 문장 설명. 한국어 지시 예시를 포함하면 발견성이 높아짐 |
version | 선택 | 시맨틱 버전. 팀 배포 시 추천 |
recommended_model | 선택 | opus / sonnet / haiku 중 하나 |
tags | 선택 | 카테고리 태그 |
본문 4부
| 섹션 | 필수 | 설명 |
|---|---|---|
## 입력 | ✅ | 무엇을 받는가. 형식·예시 |
## 처리 규칙 | ✅ | 단계별 지시. 최소 3단계 |
## 출력 형식 | ✅ | 무엇을 내보내는가. 포맷 고정 |
## 예시 | 선택 | 입력/출력 샘플 1~2개 |
## 엣지 케이스 | 선택 | 오류·예외 처리 |
좋은 스킬의 3원칙
flowchart LR G1["1. 명확한 입출력"] --> Q["좋은 스킬"] G2["2. 구체적 처리 규칙"] --> Q G3["3. 재사용 가능한 범용성"] --> Q
원칙 1 — 명확한 입출력
테스트: 동료에게 스킬 이름과 ## 입력, ## 출력 형식만 보여줬을 때 "아, 이게 뭐하는 거구나" 가 바로 와야 합니다. 본문을 읽어야 이해되는 스킬은 쓰이지 않습니다.
나쁜 예:
## 입력
- 업무 관련 내용
## 출력 형식
- 정리된 결과좋은 예:
## 입력
- 참가자 엑셀 (이름 / 소속 / 직급 / 교육명 / 수료일 컬럼 필수)
- 명찰 PPTX 템플릿 ({{name}}, {{org}} 플레이스홀더 포함)
## 출력 형식
- output/badges/명찰_전체.pptx — N장 슬라이드 단일 파일
- output/certificates/{name}_수료증.docx — N개 개별 파일
- 실행 요약: "정상 N건 / 실패 M건 / 소요 X초"원칙 2 — 구체적 처리 규칙
테스트: "이 규칙을 어떻게 해석해도 결과가 같게 나오는가?" 가 기준.
나쁜 예:
## 처리 규칙
1. 잘 정리한다
2. 중요한 것만 뽑는다
3. 깔끔하게 만든다좋은 예:
## 처리 규칙
1. 입력 로그에서 "완료" / "진행중" / "블로커" 3영역으로 분류
2. 각 영역에서 **상위 3개** 만 추출. 선정 기준: (a) 고객에게 영향이 큰 것, (b) 금액 영향이 큰 것, (c) 마감이 가까운 것 순서
3. 블로커는 반드시 "무엇이 막고 있는가" 를 한 줄로 설명
4. 다음 주 Top 3 는 "왜 중요한가" 를 한 줄로 근거 제시
5. 수치는 전주 대비 증감을 괄호로 표시. 예: "45건 (+8)"포인트: "상위 3개 추출"이 아니라 "어떤 기준으로" 상위인가까지 적어야 재현 가능.
원칙 3 — 재사용 가능한 범용성
테스트: "이 스킬을 이번에 한 번만 쓰고 버릴 건가?" vs "매주/매번 쓸 건가?"
나쁜 예: 4월 13일 ACME 고객사 보고서 전용 스킬. 고객사명·날짜가 하드코딩.
좋은 예: 회사명·날짜·항목을 입력 파라미터로 받는 범용 보고서 스킬. 고객사가 바뀌면 엑셀만 갈아끼움.
나쁜 스킬의 5가지 함정
1. 프롬프트 덩어리
SKILL.md 가 사실상 긴 프롬프트 한 덩어리. 구조가 없고, 동료가 읽어도 뭘 고쳐야 할지 모름. → 처방: 4부 구조로 쪼개기.
2. 매뉴얼 설명
"이 스킬은 매우 유용합니다. 많은 상황에서 쓸 수 있고..." 같은 독자용 설명이 본문을 차지.
→ 처방: SKILL.md는 AI에게 주는 지시서이지 독자에게 주는 팸플릿이 아님. 설명은 README.md 또는 이 활용서(책)에 둔다.
3. 톤이 박혀 있음
처리 규칙 안에 "정중하게", "공식체로" 같은 톤 지시가 섞여 있음. 스킬마다 반복.
→ 처방: 톤은 CLAUDE.md로 분리. SKILL.md 는 "무엇을 할지"만.
4. 출력 형식 미정
처리 규칙만 있고 출력 형식 섹션이 없음. 결과가 매번 다름. → 처방: 출력 형식은 구조 + 순서 + 제약 을 명시. 마크다운 템플릿을 붙여도 됨.
5. 예외 무시
정상 경로만 적혀 있고 "입력이 없으면 / 데이터가 불완전하면 / 외부 API가 실패하면" 없음.
→ 처방: ## 엣지 케이스 섹션 추가. 최소 3개는 나옴.
팀 공유 시 추가할 것
- 버전 번호 (
version: 0.2.0) - 변경 이력 (
## 변경 이력섹션) - 예시 입력/출력 (동료가 실행 전 기대를 가질 수 있도록)
- 엣지 케이스 (사고 방지)
- 담당자 (누가 관리하는가)
자주 묻는 질문
Q. 처리 규칙에 너무 많은 단계를 쓰면 Claude가 혼란스러워하지 않나요?
A. 반대입니다. 단계가 많을수록 결과가 일관됩니다. 다만 20단계가 넘어가면 중간에 스킬을 둘로 쪼개는 것을 고려하세요. 한 스킬이 한 일만 하도록.
Q. SKILL.md 안에 Python 코드를 써도 되나요?
A. 됩니다. Claude 는 코드 블록을 인식해 실행 계획으로 활용합니다. 특히 엑셀·PDF 처리 같은 건 Python 코드를 스킬에 포함하는 게 정확도가 높습니다. name-badge 스킬이 이 방식을 씁니다.
Q. 같은 업무인데 사람마다 Skill을 따로 만들면 어떻게 합쳐야 하나요?
A. 한 사람이 "표준 Skill"을 먼저 올리고, 다른 사람들은 차이점을 이슈로 올리는 방식이 가장 빠릅니다. 합의 후 표준 Skill에 옵션 · 분기로 흡수. "모두의 Skill"을 동시에 만들려 하면 합의가 안 됩니다.
다음 읽을거리
변경 이력
- v1 (2026-04-11): 최초 작성 — Claude@IGM Cohort 1 교재용