SKILL.md 파일은 모든 Claude Skill의 핵심입니다 - 짧은 YAML 헤더(name과 description)로 시작하고 Claude가 따라야 할 지침이 이어지는 Markdown 파일입니다. 설명은 Claude에게 Skill을 언제 사용할지 알려 주고, 본문은 방법을 알려 줍니다.
이 페이지
이 용어를 보고 실제로 무엇이 들어 있는지 궁금했다면, 다음은 SKILL.md, 각 부분이 중요한 이유와 제대로 작동하는 파일을 작성하는 방법입니다.
SKILL.md란
Claude Skill은 폴더이며, SKILL.md는 루트에 있어야 하는 필수 파일입니다. 일반 Markdown이므로 어떤 텍스트 편집기에서든 열 수 있습니다. Claude는 이 파일을 읽고 특정 종류의 작업에 필요한 기능, 단계, 규칙, 모범 사례를 학습합니다. 선택적 추가 파일(템플릿, 스크립트, 참고 파일)은 같은 폴더에 함께 둘 수 있지만, 모든 Skill에 반드시 필요한 파일은 SKILL.md입니다.
처음부터 만들지 않고 범위가 잘 정의된 SKILL.md를 보고 싶으신가요? Yuri의 프런트매터와 지침은 이미 작성되고 테스트되어 코드 검토에서 버그, 보안 취약점, 성능 문제를 찾아냅니다.
Yuri - Code Reviewer AI Skill 보기 →SKILL.md의 두 부분
1. 프런트매터(메타데이터)
맨 위에는 --- 마커 사이에 작은 YAML 블록이 있습니다. 여기에는 핵심 메타데이터가 들어가며, 최소한 name과 description이 포함됩니다:
---
name: weekly-report
description: 원시 메모를 표준 주간 보고서로 정리합니다. 사용자가 주간 업데이트, 상태 보고서를 요청하거나 "이번 주 내용을 정리해 달라"고 할 때 사용하세요.
---이 블록은 특별합니다. 세션이 시작되면 Claude는 설치된 각 Skill의 이름과 설명만 미리 불러오며, 파일 전체는 불러오지 않습니다. 덕분에 컨텍스트 창을 가볍게 유지할 수 있으며, 이것이 설명이 많은 역할을 하는 이유입니다.
2. 본문(지침)
프런트매터 아래의 일반 Markdown에 Claude가 실제로 수행해야 할 작업을 작성하세요 - 가능한 한 명확한 번호 매기기 단계와 규칙 또는 예시를 포함하세요:
## 단계
1. 메모를 성공, 진행 중, 장애 요소로 분류하세요.
2. 각 글머리 기호는 과거 시제의 한 문장으로 작성하세요.
3. 한 줄짜리 "다음 주" 요약으로 마무리하세요.
4. 메모에 없는 지표는 절대 만들어 내지 마세요.설명이 가장 중요한 줄인 이유
실행 여부는 전적으로 설명에 달려 있습니다. 작업하는 동안 Claude는 요청을 각 스킬의 설명과 비교하고, 일치할 때만 전체 파일을 불러옵니다. 모호한 설명("보고서 작성 지원")은 거의 실행되지 않습니다. 구체적인 설명("사용자가 주간 업데이트나 상태 보고서를 요청할 때 사용")은 안정적으로 실행됩니다. 한 가지 규칙만 기억한다면 이것으로 하세요. 스킬이 무엇인지뿐만 아니라 언제 사용해야 하는지를 설명하도록 작성하세요.
Claude가 파일을 사용하는 방식
- 시작 시: Claude가 모든 스킬의 이름과 설명을 읽습니다.
-
작업 중: 요청이 설명과 일치하면 Claude가 해당 스킬의 전체
SKILL.md와 첨부된 리소스를 불러옵니다. - 그다음: Claude가 본문의 지침에 따라 작업을 완료합니다.
이러한 "필요할 때만 불러오기" 방식은 점진적 공개라고 하며, 모델의 컨텍스트를 불필요하게 늘리지 않고 많은 스킬을 설치해 둘 수 있게 해 줍니다.
좋은 SKILL.md 작성하기
- 설명을 정확하게 작성하세요. 스킬이 언제 실행되어야 하는지 명확하게 밝히세요.
- 첫 버전은 작게 유지하세요. 명확한 단계로 작성한 5~10줄이 장황한 문서보다 낫습니다.
- 구체적으로 작성하세요. 번호가 매겨진 단계, 명확한 규칙, 짧은 예시를 포함하세요.
- 실제 작업에서 테스트하세요. Claude가 놓치는 부분만 확장하세요.
직접 작성해야 하나요?
아니요. 자신만의 워크플로에 맞춘 작업에는 직접 작성하는 것이 좋지만, 결과만 원한다면 바로 사용할 수 있는 스킬에 이미 작성 및 테스트가 완료된 SKILL.md가 포함되어 있습니다. 1,000개 이상의 스킬, prompt 팩, 에이전트를 제공하는 KissMySkills 라이브러리나 Claude Code 스킬 컬렉션을 둘러보세요. 먼저 실제 작동 모습을 보고 싶으신가요? 무료 생성기를 사용해 보거나 무료 스킬을 받아 보세요.
대
비서실장 채용모든 SKILL.md가 코더를 위한 것은 아닙니다. Ryan의 프런트매터와 지침은 편집 없이 이사회 자료, 전사 메모, 임원 브리핑을 작성할 수 있도록 구성되어 있습니다.
Ryan - Chief of Staff AI Skill 보기 →
자주 묻는 질문
SKILL.md는 단순한 Markdown인가요?
예. 상단에 YAML 프런트매터 블록이 있는 표준 Markdown 파일입니다. 모든 텍스트 편집기에서 열 수 있으며 별도의 소프트웨어는 필요하지 않습니다.
SKILL.md에 필요한 것은 무엇인가요?
최소한 이름과 설명이 포함된 프런트매터 블록이 필요합니다. 지침이 담긴 본문이 Skill을 유용하게 만들지만, 검색 및 트리거가 가능하게 만드는 것은 메타데이터입니다. SKILL.md 파일은 어디에 위치하나요? Skill 폴더의 루트에 있습니다. Claude Code에서는 Skill이 개인적으로 사용하려면 프로젝트 내부의
~/.claude/skills/<name>/
.claude/skills/<name>/ SKILL.md 폴더 루트에 있습니다.
SKILL.md의 콘텐츠를 ChatGPT 또는 Gemini에서 사용할 수 있나요?
예. 지침은 이식 가능하므로 본문을 ChatGPT 또는 Gemini의 맞춤 지침에 붙여 넣으면 동일한 동작을 구현할 수 있습니다. 프런트매터를 통한 자동 트리거는 Claude의 기능입니다.
요약하면:
YAML 프런트매터를 직접 작성하는 수고를 덜고 싶다면, Yuri - Code Reviewer는 개발자에게 좋은 선택이며, Ryan - Chief of Staff는 임원 및 비즈니스 문서 작성을 지원합니다. 코딩 없이 Claude, ChatGPT 및 모든 AI 채팅에서 작동하며 30일 환불 보장이 제공됩니다.
작동하는 예시로 시작하기
SKILL.md를 이해하는 가장 빠른 방법은 좋은 예시 하나를 읽는 것입니다. 무료 Skill을 받아 파일을 열고, 프런트매터와 단계로 구성된 구조가 실제로 어떻게 작동하는지 확인한 다음, 3분 만에 설치 방법을 읽어 보세요.