SKILL.md

정의#

SKILL.md는 Skill의 설계도이자 작업 지시서다. Claude는 이 파일을 읽고 해당 Skill이 무엇을 하는지·언제 호출되어야 하는지·어떤 도구를 쓰는지를 판단한다. 구조는 표준 마크다운으로, 개발자가 아니어도 내용을 이해하고 수정할 수 있다.

구조#

---
name: my-skill
description: 이 Skill이 하는 일과 호출 조건
allowed-tools: Read, Write, Bash
---

# 본문

## 사용 시점
- 언제 써야 하는지

## Workflow
1. 무엇을 먼저 하고
2. 다음에 무엇을 하는지

• 프론트매터(frontmatter) — name, description, allowed-tools 등 메타데이터. Claude가 Skill을 고를 때 가장 먼저 본다
• 본문 — 실제 작업 절차를 자연어로 서술

Progressive Disclosure (점진 공개)#

SKILL.md는 보통 3단계로 로드된다. 프론트매터(약 100토큰)만 항상 읽히고, 본문(약 5000토큰)은 트리거가 맞을 때, 번들 파일은 필요할 때만 읽힌다. 이 설계 덕분에 수많은 Skill이 등록되어 있어도 컨텍스트를 낭비하지 않는다.

.skill 파일과의 관계#

Claude Cowork에서 다운로드하는 .skill 파일은 사실상 zip 아카이브이며, 그 안의 핵심 파일이 바로 SKILL.md다. 확장자를 .zip으로 바꿔 풀어 보면 내용을 직접 확인할 수 있다.