프론트매터: 스킬의 신분증

주민등록증을 떠올려보세요

여러분의 주민등록증(또는 운전면허증)을 한번 떠올려보세요.

거기에 뭐가 적혀있나요?

• 이름: 홍길동
• 생년월일: 1995.03.15
• 주소: 서울시 강남구...
• 사진: (말 안 할게요... 신분증 사진은 다 못생기게 나오니까)

이 작은 카드 한 장으로 "이 사람이 누구인지"를 빠르게 알 수 있어요.

스킬 패키지에도 이런 "신분증"이 있어요. SKILL.md 파일을 열면 맨 위에 적혀 있는 특별한 영역인데, 이걸 프론트매터(frontmatter)라고 불러요.

오늘은 이 프론트매터를 뜯어볼 거예요. 어렵지 않아요 — 약속!

잠깐, YAML이 뭐예요?

프론트매터를 이해하려면, 먼저 YAML이라는 걸 아주 살짝만 알아야 해요.

"야... 뭐?" 네, YAML(야믈)이에요. 이름이 좀 이상하죠. 원래 "YAML Ain't Markup Language"의 약자인데, 그건 몰라도 돼요.

YAML은 딱 한 마디로 설명하면 이거예요:

예를 들어볼게요. 여러분이 카페에서 주문서를 작성한다고 해봐요:

이름: 홍길동
음료: 아이스 아메리카노
사이즈: 벤티
샷 추가: 2
테이크아웃: 네

이게 YAML이에요. (거의요.)

"키: 값" 형태. 왼쪽에 항목 이름, 콜론(:), 오른쪽에 내용. 끝이에요.

어렵지 않죠? 엑셀 시트의 A열(항목)과 B열(내용)을 세로로 쓴 거라고 생각하면 돼요.

프론트매터, 실제로 이렇게 생겼어요

자, 이제 진짜 SKILL.md의 프론트매터를 볼게요. SKILL.md 파일을 열면 맨 위에 이렇게 생긴 부분이 있어요:

---
name: weekly-report-writer
description: >-
  매주 월요일 주간 현황 보고 이메일을 작성해주는 스킬입니다.
  사용자에게 주요 성과와 수치를 물어보고, 정해진 양식에 맞춰
  깔끔한 보고서를 생성합니다.
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
---

# 주간 보고서 작성 스킬

이 스킬은 매주 주간 보고서를 작성합니다...
(이하 스킬 본문)

보이시나요? --- 세 개로 시작하고, 다시 --- 세 개로 끝나는 영역. 이 사이가 프론트매터예요.

프론트매터가 끝나면 그 아래부터가 스킬의 본문(실제 지시사항)이에요.

마치 편지 봉투에 보내는 사람, 받는 사람, 주소를 적고, 봉투를 열면 실제 편지 내용이 나오는 것과 같아요. 프론트매터 = 봉투 겉면, 본문 = 봉투 안 편지.

각 항목 뜯어보기

프론트매터의 각 항목을 하나씩 살펴볼게요.

1. name — 스킬의 이름

name: weekly-report-writer

말 그대로 스킬의 이름이에요. 사람의 이름처럼, 이 스킬을 부르는 방법이에요.

규칙:

• 케밥 케이스로 쓰기 (챕터 5에서 배웠죠!)
• 짧지만 뭘 하는지 알 수 있게 쓰기
• 영어로 쓰기 (시스템이 인식해야 하니까)

2. description — 스킬의 자기소개

description: >-
  매주 월요일 주간 현황 보고 이메일을 작성해주는 스킬입니다.
  사용자에게 주요 성과와 수치를 물어보고, 정해진 양식에 맞춰
  깔끔한 보고서를 생성합니다.

이 항목이 가장 중요해요. 왜냐하면, Claude가 "이 스킬을 쓸까 말까"를 결정할 때 description을 보고 판단하거든요.

면접 때 자기소개와 같아요. 자기소개를 잘 하면 면접관이 "오, 이 사람 적합하네!" 하고 뽑아주듯, description을 잘 쓰면 Claude가 "오, 이 스킬이 딱 맞네!" 하고 사용해줘요.

좋은 description을 쓰는 팁:

• 뭘 하는지 명확하게 쓰기 ("주간 보고서를 작성한다")
• 언제 쓰는지 쓰기 ("매주 월요일")
• 어떻게 하는지 간략히 쓰기 ("사용자에게 물어보고 양식에 맞춰 생성")

참고로 >-는 "여러 줄을 한 줄처럼 이어서 읽어줘"라는 YAML 문법이에요. 긴 설명을 줄바꿈하면서 쓸 수 있게 해줘요. 지금은 "description이 길 때 이렇게 쓰는구나" 정도만 기억하면 돼요.

3. allowed-tools — 스킬의 자격증

allowed-tools:
  - Bash
  - Read
  - Write
  - Edit

이건 이 스킬이 사용할 수 있는 도구 목록이에요.

비유하면 "자격증"이에요. 병원에서 의사만 수술할 수 있듯이, 스킬도 허용된 도구만 사용할 수 있어요.

• Bash: 터미널 명령어를 실행할 수 있는 도구
• Read: 파일을 읽을 수 있는 도구
• Write: 파일을 새로 만들 수 있는 도구
• Edit: 기존 파일을 수정할 수 있는 도구

목록 형식 (앞에 -가 붙는 것)은 YAML에서 "여러 개의 항목"을 나열하는 방법이에요. 쇼핑 리스트를 쓸 때 각 항목 앞에 점(-)을 찍는 것과 같아요.

4. 그 외 선택 항목들

이 세 가지(name, description, allowed-tools)가 핵심이지만, 필요에 따라 더 추가할 수 있어요:

---
name: weekly-report-writer
description: >-
  매주 월요일 주간 현황 보고 이메일을 작성해주는 스킬입니다.
allowed-tools:
  - Read
  - Write
version: 1.0.0
author: hong-gildong
license: MIT
tags:
  - productivity
  - email
  - korean
---

• version: 스킬의 버전 (앱 업데이트처럼, 1.0 → 1.1 → 2.0)
• author: 누가 만들었는지
• license: 다른 사람이 이 스킬을 어떻게 쓸 수 있는지 (챕터 3에서 배운 오픈소스 라이선스!)
• tags: 검색할 때 찾기 쉽게 해주는 키워드

이것들은 선택사항이에요. 없어도 스킬은 작동해요. 하지만 있으면 스킬을 관리하고 공유할 때 편해요. 마치 책에 ISBN 번호가 없어도 읽을 수 있지만, 있으면 도서관에서 찾기 쉬운 것처럼요.

초보자가 자주 하는 실수

YAML은 간단하지만, 몇 가지 함정이 있어요. 미리 알려드릴게요.

실수 1: 탭(Tab) 대신 스페이스를 써야 해요

YAML에서 들여쓰기는 반드시 스페이스(공백)로 해야 해요. Tab 키를 누르면 안 돼요.

# 맞는 예 (스페이스 2칸으로 들여쓰기)
allowed-tools:
  - Bash
  - Read

# 틀린 예 (탭으로 들여쓰기 - 오류 발생!)
allowed-tools:
	- Bash
	- Read

"아니, 눈으로 보면 똑같은데 왜 안 되는 거예요?" 이건 프로그래밍 세계의 오래된 논쟁거리예요. 스페이스와 탭은 눈에 보이는 건 같지만, 컴퓨터에게는 다른 문자거든요. YAML은 탭을 싫어해요. 그냥 그렇다고 외우세요.

실수 2: 들여쓰기를 맞춰야 해요

# 맞는 예 (같은 레벨은 같은 들여쓰기)
allowed-tools:
  - Bash
  - Read
  - Write

# 틀린 예 (들여쓰기가 제각각)
allowed-tools:
  - Bash
    - Read
 - Write

YAML은 들여쓰기로 구조를 파악해요. 같은 그룹에 속하는 항목은 같은 칸수로 들여써야 해요. 마치 아웃라인을 쓸 때 같은 레벨의 항목을 같은 위치에 쓰는 것처럼요.

실수 3: 콜론(:) 뒤에 공백이 있어야 해요

# 맞는 예
name: weekly-report-writer

# 틀린 예 (콜론 뒤에 공백 없음)
name:weekly-report-writer

키: 값 형태에서 콜론 뒤에 반드시 공백(스페이스)이 하나 있어야 해요. 이거 빼먹으면 오류가 나요.

프론트매터 = 책의 표지

마지막으로 전체를 관통하는 비유 하나 더 할게요.

서점에 가면 책을 어떻게 고르시나요? 대부분 표지를 먼저 보죠.

• 제목을 보고 → "아, 이런 주제구나" (= name)
• 뒷표지 소개글을 읽고 → "아, 이런 내용이구나" (= description)
• 저자, 출판사를 확인하고 → "아, 이 사람이 썼구나" (= author, version)

표지만 보고 "이 책 읽어볼까 말까"를 결정하잖아요?

Claude도 똑같이 해요. 프론트매터를 보고 "이 스킬 쓸까 말까"를 결정해요. 그래서 프론트매터를 잘 쓰는 게 중요한 거예요.

표지가 어수선하고 소개글이 모호한 책은 안 집어들게 되잖아요? 프론트매터가 엉성한 스킬도 Claude가 잘 안 써요. 반대로, 프론트매터가 깔끔하고 description이 명확한 스킬은 Claude가 딱 필요한 순간에 "아, 이 스킬이 있네!" 하고 꺼내줘요.