레슨 2: 스킬의 해부학: SKILL.md 파일

학습 목표:

• SKILL.md의 두 부분 구조 이해하기
• YAML 프론트매터의 필수 필드 파악하기
• 실제로 작동하는 description 작성법 익히기
• 지시문 섹션을 구성하는 방법 살펴보기

전제: << 레슨 1 | 다음: 레슨 3 >>

스킬 파일은 어떻게 생겼나

어떤 스킬을 열어 봐도 같은 모양입니다.¹

이 파일은 두 부분으로 이루어져 있습니다.

1. YAML 프론트매터(--- 마커 사이의 모든 내용): 이 스킬의 기본 정보를 Claude에게 알려 주는 메타데이터
2. Markdown 지시문(그 뒤의 모든 내용): Claude가 무엇을 해야 하는지 알려 주는 실제 지시

YAML 프론트매터: Claude가 스킬을 찾아내는 방법

프론트매터는 파일 맨 위에 ---로 감싸인 블록입니다. 여기에서 가장 중요한 두 가지를 Claude에게 알려 줍니다.^{2 3}

name: 스킬의 고유 식별자

• 규칙: 소문자, 숫자, 하이픈만 사용합니다. 공백은 안 됩니다.
• 역할: name이 그대로 /task-organizer 같은 명령이 됩니다.
• 조언: 설명적이고, 짧고, 한눈에 뜻이 통하는 이름으로 지으세요.

좋은 이름:

• meeting-notes
• code-review
• changelog-generator

나쁜 이름:

• my-skill-1(아무것도 알려 주지 않음)
• super_amazing_task_helper(너무 길고, 언더스코어는 쓸 수 없음)
• taskOrganizer(camelCase — 소문자와 하이픈이어야 함)

description: 가장 중요한 필드

이 한 문장이 세 가지를 결정합니다:⁴

1. Claude가 이 스킬을 스스로 읽어 들일지 여부
2. 사용자가 스킬 목록에서 보게 되는 내용
3. Claude가 이 스킬을 무엇을 위한 것으로 이해할지

그래서 파일 안의 그 무엇보다 공들여 쓸 가치가 있습니다.⁴

"The description is the single most important field in your frontmatter. A bad description means your skill either never triggers or triggers on everything. The formula: What it does + When to use it + Key capabilities."

(description은 프론트매터에서 가장 중요한 필드입니다. 이것이 부실하면 스킬은 아예 발동하지 않거나 아무 데서나 발동합니다. 공식은 '무엇을 하는지 + 언제 쓰는지 + 주요 기능'입니다.)

좋은 description:

나쁜 description:

선택 필드(여기가 아니라 레슨 6에서 다룹니다)

• model: 사용할 모델을 고른다
• allowed-tools: 이 스킬이 건드릴 수 있는 도구를 제한한다
• version: 버전 번호

첫 스킬에는 name과 description만 있으면 충분합니다.³

Markdown 지시문: Claude에게 방법을 알려 주기

프론트매터 뒤의 모든 내용은 Claude가 읽고 따르도록 쓰인 것입니다.¹

좋은 지시문에는 세 가지 공통점이 있습니다.

1. 명확한 섹션

제목을 사용해 각 부분을 나눕니다.

2. 구체적인 단계

약한 방식:

강한 방식:

3. 예시

출력 형식이 중요하다면 하나 보여 주세요.

예시가 하나 있으면 Claude는 어떻게 배치해야 할지 정확히 알게 됩니다. 설명하는 것보다 보여 주는 것이 낫습니다. 샘플 출력 하나가 형식에 관한 세 문단의 설명보다 더 많은 일을 합니다.

두 부분이 함께 작동하는 방식

프론트매터는 발견하는 장치이고, 지시문은 실행을 안내하는 지침입니다.^{5 6}

1. 여러분이 /task-organizer를 입력하거나, 그냥 "이 작업들 좀 정리해 줘"라고 말한다
2. Claude가 프론트매터의 name과 description을 읽고, 이 스킬을 읽어 들일지 판단한다
3. 읽어 들이기로 했다면, Claude가 지시문 전체를 읽는다
4. Claude가 쓰인 그대로 단계를 밟아 나간다
5. 출력이 지시문에서 지정한 형식과 일치한다

description이 좋아야만 하는 이유가 여기에 있습니다. Claude가 이 스킬을 쓸지 말지 판단할 때 가진 유일한 근거이기 때문입니다.⁴

"작업을 도와준다"라고 쓰면 Claude는 어떤 상황에서 써야 할지 알지 못합니다. "어수선한 할 일 목록을 우선순위와 마감일에 따라 그룹으로 정리한다"라고 쓰면, 요청에 들어 있는 "정리", "할 일", "작업" 같은 말만으로도 이 스킬을 불러들이기에 충분합니다.

실제 예시: 코드 리뷰 스킬 뜯어보기

실제로 쓰이고 있는 스킬을 보겠습니다.

뜯어보면 이렇습니다.

• 프론트매터의 description: 무엇을 하는지(코드를 리뷰한다)와 무엇을 점검하는지(컨벤션, 버그, 성능)를 밝히고 있다
• 지시문은 세 개의 체크리스트로 나뉜다: 컨벤션, 버그, 성능. 각각에 살펴볼 구체적인 항목이 있다
• 출력 형식이 명시되어 있다: 모든 문제에는 위치, 문제, 제안이 반드시 따라붙어야 한다

이렇게 쓰인 스킬은 한 번에 제대로 동작합니다.

정리

• SKILL.md는 두 부분: YAML 프론트매터(메타데이터)와 Markdown 지시문(지시)
• 필수 프론트매터 필드: name(소문자, 하이픈, 고유)과 description(자동 발동을 좌우한다)
• description 공식: 무엇을 하는지 + 언제 쓰는지 + 주요 기능
• 좋은 지시문의 세 가지 특징: 명확한 섹션, 구체적인 단계, 잘 만든 예시
• 두 부분이 맞물리는 방식: 프론트매터로 Claude가 스킬을 찾고, 지시문으로 Claude가 그것을 실행한다

다음 레슨에서는 아무것도 없는 상태에서 시작해 완전한 스킬 하나를 처음부터 끝까지 작성합니다.

>> 레슨 3: 실습: 첫 스킬 작성하기

Footnotes

1. Claude Code 공식 문서: Extend Claude Code with skills — https://code.claude.com/docs/en/skills ↩ ↩²

2. Anthropic 엔지니어링 블로그: Equipping agents for the real world with Agent Skills — https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills ↩

3. Anthropic 헬프 센터: How to create custom skills — https://support.claude.com/en/articles/12512198-how-to-create-custom-skills ↩ ↩²

4. Building skills for Claude 실습: YAML frontmatter와 테스트 — https://sjramblings.io/building-skills-for-claude-part-2/ ↩ ↩² ↩³

5. Anthropic 플랫폼 문서: Agent Skills overview — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview ↩

6. Claude Skills 심층 분석(제1원리 관점) — https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/ ↩