SKILL.md 파일이란 무엇인가요? (Claude Skill의 구성)

2026년 6월 18일

SKILL.md 파일은 모든 Claude Skill의 핵심입니다 — 짧은 YAML 헤더(name과 description)로 시작하고 Claude가 따라야 할 지침이 뒤따르는 마크다운 파일입니다. description은 Claude가 언제 스킬을 사용할지 알려주고, 본문은 어떻게 사용할지 알려줍니다.

이 용어를 본 적이 있고 실제로 내부에 무엇이 들어 있는지 궁금했다면, SKILL.md의 구조, 각 부분이 중요한 이유, 그리고 제대로 작동하는 파일을 작성하는 방법을 알려드립니다.

SKILL.md란 무엇인가

Claude Skill은 폴더이며, SKILL.md는 그 루트에 반드시 있어야 하는 파일입니다. 일반 마크다운 파일이므로 어떤 텍스트 편집기에서도 열 수 있습니다. Claude는 이 파일을 읽어 특정 작업에 대한 단계, 규칙, 모범 사례 등 기능을 학습합니다. 선택적으로 템플릿, 스크립트, 참조 파일 등이 같은 폴더에 있을 수 있지만, SKILL.md는 모든 스킬에 반드시 필요한 파일입니다.

SKILL.md의 두 부분

1. 프런트매터(메타데이터)

맨 위에는 --- 구분자 사이에 작은 YAML 블록이 있습니다. 최소한 name과 description을 포함하는 필수 메타데이터를 담고 있습니다:

---
name: weekly-report
description: Formats raw notes into our standard weekly report. Use when the user asks for a weekly update, status report, or to "write up the week."
---

이 블록은 특별합니다: 세션이 시작될 때 Claude는 설치된 모든 스킬의 이름과 설명만 미리 불러옵니다 — 전체 파일은 아닙니다. 덕분에 컨텍스트 창이 가벼워지고 description이 중요한 역할을 합니다.

2. 본문(지침)

프런트매터 아래, 일반 마크다운 형식으로 Claude가 실제로 수행할 작업을 작성합니다 — 이상적으로는 명확한 번호 매긴 단계와 규칙 또는 예시를 포함하여:

## Steps
1. Group the notes under Wins, In Progress, and Blockers.
2. Keep each bullet to one sentence, past tense.
3. End with a one-line "Next week" summary.
4. Never invent metrics that aren't in the notes.

description이 가장 중요한 이유

트리거는 전적으로 description에 달려 있습니다. 작업 중 Claude는 요청을 각 스킬의 description과 비교하고 일치할 때만 전체 파일을 불러옵니다. 모호한 description("보고서에 도움")은 거의 작동하지 않습니다. 구체적인 description("사용자가 주간 업데이트나 상태 보고서를 요청할 때 사용")은 신뢰성 있게 작동합니다. 한 가지 규칙만 기억한다면, description은 스킬을 언제 사용할지에 대해 작성해야 하며, 단순히 무엇인지에 대한 설명이 아닙니다.

Claude가 파일을 사용하는 방법

시작 시: Claude는 모든 스킬의 이름과 description을 읽습니다.
작업 중: 요청이 description과 일치하면 해당 스킬의 전체 SKILL.md와 첨부 리소스를 불러옵니다.
그 후: Claude는 본문의 지침을 따라 작업을 완료합니다.

이 “필요할 때만 불러오기” 방식은 점진적 공개(progressive disclosure)라고 하며, 많은 스킬을 설치해도 모델의 컨텍스트가 과부하되지 않도록 해줍니다.

좋은 SKILL.md 작성법

description을 명확히 작성하세요. 스킬이 언제 작동해야 하는지 분명히 적으세요.
첫 버전은 간결하게 유지하세요. 5~10줄의 명확한 단계가 방대한 문서보다 낫습니다.
구체적으로 작성하세요. 번호 매긴 단계, 명확한 규칙, 짧은 예시를 포함하세요.
실제 작업에서 테스트하세요. Claude가 놓치는 부분만 확장하세요.

직접 작성해야 하나요?

아니요. 자신만의 워크플로우에 맞게 작성하는 것이 좋지만, 결과만 원한다면 이미 만들어지고 테스트된 SKILL.md가 포함된 기성 스킬을 사용하세요. 300개 이상의 스킬, 프롬프트 팩, 에이전트를 모은 KissMySkills 라이브러리나 Claude Code 스킬 컬렉션을 둘러보세요. 먼저 사용해보고 싶다면 무료 생성기를 사용하거나 무료 스킬을 받아보세요.