🧩 레슨

SKILL.md 만들기

① 오늘의 미션

스킬의 속을 직접 열어본다

지난 레슨에서 '우리동네 반찬가게'의 신상품 등록 스킬(product-add)을 만들었어요. 오늘은 그 스킬의 SKILL.md 파일을 직접 열어보고, 내 손으로 채워봐요.

SKILL.md는 어려운 코드가 아니라, 알바생에게 적어주는 인수인계 메모예요.

설명을 따라 진행하면, 여기서 직접 쳐보게 돼요 👇

~/my-shop

$ _

📚 「SKILL.md 만들기」 레슨 내용 전체 텍스트로 훑어보기

스킬의 속을 직접 열어본다

SKILL.md는 어려운 코드가 아니라, 알바생에게 적어주는 인수인계 메모예요.

Claude가 내 매뉴얼을 '제때, 제대로' 따라 하게 하려면, SKILL.md에 무엇이 들어 있어야 할까요?

맞아요. 좋은 SKILL.md엔 ① 언제 쓰는지(발동 조건) ② 어떤 순서로(단계) ③ 결과 예시가 들어가요. 알바생에게 신상품 등록을 인수인계할 때 적어주는 메모랑 똑같아요.

SKILL.md는 그냥 글로 쓴 메모 파일이에요. 아래 3칸만 채우면 돼요.

1️⃣ 언제 (발동 조건)

"사용자가 '이 신상품 등록해줘'라고 할 때." → Claude가 언제 이 매뉴얼을 꺼낼지 판단하는 기준이에요.

2️⃣ 순서 (단계)

"1) 상품 이미지를 받는다 2) 설명·가격을 정리한다 3) 카테고리를 골라 상품 페이지에 추가한다." → 일하는 절차를 단계로 적어요.

3️⃣ 예시 (결과 모양)

"등록된 상품 카드는 이렇게 생겼어요 ↓" 하고 완성 예시를 하나 보여줘요. 예시가 있으면 결과가 확 일정해져요.

먼저 지난 레슨에서 만든 스킬 파일이 어떻게 생겼는지 셸 명령으로 들여다봐요.

ls .claude/skills/product-add — 스킬 폴더 안 파일을 봐요

cat .claude/skills/product-add/SKILL.md — SKILL.md 내용을 출력해봐요

보이죠? 언제 · 순서 · 예시 딱 3칸이에요. 사람이 읽을 수 있는 평범한 글이에요.

가장 중요한 첫 칸이에요. '재고 점검 스킬'을 만든다면, 언제 발동해야 할까요? 빈칸을 한 단어로 채워보세요.

좋아요! 발동 조건은 사용자가 실제로 칠 말과 닮을수록 정확히 켜져요. "재고 점검해줘"라는 말이 곧 스위치예요.

Claude에게 재고 점검 Skill 만들어줘. SKILL.md도 채워줘 라고 하면 어떻게 될까요?

맞아요. Claude는 3요소를 채우는 게 좋은 SKILL.md임을 알아서, 빠진 칸을 되물어가며 직접 작성해줘요. 외울 필요가 없어요. 시켜볼까요? 👇

Claude를 켜고, 새 스킬의 SKILL.md를 말로 채워달라고 해요.

claude — Claude Code를 켜요

재고 점검 Skill 만들어줘. SKILL.md에 언제·순서·예시 3칸 채워줘 — 재고 점검 스킬을 SKILL.md까지 채워달라고 해요

3요소가 알아서 채워졌어요. 내가 한 일은 '무슨 스킬'인지 말한 것뿐이에요.

좋은 SKILL.md를 쓰는 순서를 맞춰보세요. (↑↓로 정렬)

정확해요! 언제 → 순서 → 예시 → 검증. 이 3칸이 스킬의 품질을 결정해요.

방금 만든 재고 점검 스킬이 한마디로 발동하는지 확인해요.

재고 점검해줘 — 발동 조건대로 한마디 시켜요

발동 조건("재고 점검해줘")이 정확해서 스킬이 바로 켜졌어요. SKILL.md를 잘 쓴 보람이죠.

같은 스킬도 SKILL.md를 어떻게 쓰느냐로 품질이 갈려요.

😕 막연한 매뉴얼: "재고 알아서 봐줘" 한 줄.
언제 켜질지·기준이 뭔지 불명확 → 결과가 들쭉날쭉.

✅ 또렷한 매뉴얼: 언제("재고 점검해줘")·순서(합산→계산→표시)·기준(5개 이하)·예시까지.
매번 같은 품질로 나와요.

기억할 건 딱 하나

SKILL.md = 언제 · 순서 · 예시 세 칸을 채운 메모 파일. 직접 외워 쓸 필요 없어요 — Claude에게 "Skill로 만들어줘" 하면 이 3요소를 물어보며 알아서 적어줘요.

한 줄로

SKILL.md는 '언제·순서·예시'를 채운 인수인계 메모예요. 또렷할수록 스킬이 정확히 발동하고 결과가 일정해져요.

다음 레슨에서

그런데 SKILL.md에 긴 자료까지 다 욱여넣으면, 스킬이 켜질 때마다 책상이 무거워져요. 다음 '참조 파일·폴더 설계 — 컨텍스트 아끼는 스킬'에서, 필요할 때만 읽히는 참조 구조를 배워요. 🌱