🧩 레슨

참조 파일·폴더 설계 — 컨텍스트 아끼는 스킬

스킬에 다 욱여넣지 마세요. 필요할 때만 읽는 참조 파일 구조가 좋은 스킬을 만들어요.

① 오늘의 미션

두꺼워진 매뉴얼

지난 레슨에서 만든 '신메뉴 공지' 스킬에, 공지 양식·예문·금지어 목록·계절별 문구까지 전부 적었더니 SKILL.md가 책 한 권이 됐어요. 그런데 이상해요 — 간단한 공지 하나 시킬 때도 Claude의 책상(컨텍스트)이 벌써 묵직합니다.

오늘은 직원 매뉴얼을 얇은 본편 + 두꺼운 부록으로 나눠, 컨텍스트를 아끼는 스킬 설계를 배웁니다.

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

~/my-shop

$ _

📚 「참조 파일·폴더 설계 — 컨텍스트 아끼는 스킬」 레슨 내용 전체 텍스트로 훑어보기

두꺼워진 매뉴얼

오늘은 직원 매뉴얼을 얇은 본편 + 두꺼운 부록으로 나눠, 컨텍스트를 아끼는 스킬 설계를 배웁니다.

스킬 폴더 안의 SKILL.md 본문은, Claude가 이 스킬을 쓸 때 언제 책상에 올라올까요?

맞아요. SKILL.md 본문은 늘 로드돼요. 스킬이 켜지는 순간 본문 전체가 책상에 올라옵니다. 그러니 본문이 두꺼울수록 매번 그 무게를 통째로 부담하는 셈이에요.

핵심은 간단해요. 본문(SKILL.md)엔 핵심 지시만 적고, 길고 가끔 쓰는 자료는 같은 폴더의 참조 파일로 빼는 거예요.

왜 절약될까

· SKILL.md → 스킬이 켜지면 늘 로드 (항상 책상에)
· 같은 폴더의 reference.md 같은 참조 파일 → 필요할 때만 읽힘
· 그래서 두꺼운 양식·예문을 부록으로 빼면, 안 쓰는 날엔 책상이 가벼워요

매뉴얼로 치면 — 직원이 늘 펴 두는 건 얇은 본편 1장, 두꺼운 양식집은 필요할 때만 꺼내 보는 부록이죠.

신메뉴 공지 스킬, 두 가지 설계를 나란히 봐요.

📚 다 욱여넣기: SKILL.md 한 파일에 양식·예문·금지어·계절문구까지 전부.
켜질 때마다 책 한 권을 통째로 책상에 올려요. 간단한 일에도 무겁죠.

📄 본편 + 부록: SKILL.md엔 "신메뉴 공지를 쓴다 + 양식은 reference.md를 읽어라"만.
두꺼운 양식은 reference.md로 분리 → 공지를 실제로 쓸 때만 읽혀 가벼워요.

같은 폴더에 SKILL.md와 reference.md를 두고 스킬을 켰어요. 이 순간 책상에는 무엇이 올라올까요?

맞아요. SKILL.md만 늘 로드되고, reference.md는 본문이 '읽어라'고 지시할 때 비로소 읽혀요. 이 차이가 컨텍스트 절약 설계의 핵심이에요.

가게 스킬 폴더에서, 두꺼운 양식을 부록 파일로 분리해봐요. 먼저 빈 참조 파일을 만들어요.

cd .claude/skills/new-menu-notice — 신메뉴 공지 스킬 폴더로 이동해요

touch reference.md — 두꺼운 양식을 담을 부록 파일을 만들어요

ls — 이제 폴더 안에 본편과 부록이 나란히 있어요

이제 SKILL.md = 본편(늘 로드), reference.md = 부록(필요할 때만). 다음은 본편에서 부록을 가리키게 해줘요.

부록을 따로 둔 것만으론 부족해요. 본편이 "이럴 땐 저 부록을 읽어라"고 길을 안내해야 Claude가 제때 꺼내 봐요.

SKILL.md 본문에 들어갈 한 줄

"신메뉴 공지를 작성할 때는 같은 폴더의 reference.md에서 공지 양식과 예문을 읽고 따른다."

이렇게 본문엔 핵심 지시 + 부록으로 가는 안내만 남기면, 두꺼운 양식은 실제로 공지를 쓸 때만 책상에 올라와요.

SKILL.md 본문에서, 양식이 필요할 때 부록을 읽게 만드는 핵심 동사는 무엇일까요? 빈칸을 채워보세요.

좋아요! 핵심은 "읽어라"는 지시예요. 부록만 만들어 두고 본문이 가리키지 않으면, Claude는 그 부록의 존재를 모른 채 지나칠 수 있어요.

신메뉴 공지 스킬에서, 다음 중 부록(reference.md)으로 빼기 가장 좋은 것은?

맞아요. 길고, 가끔만 쓰는 자료(양식·예문 모음)일수록 부록으로. 반대로 스킬의 정체와 핵심 지시는 본문에 남아야 해요 — 그건 늘 필요하니까요.

분리가 잘 됐는지 Claude에게 직접 물어보면 돼요. 가게 폴더에서 Claude를 켜고 대화해봐요.

신메뉴 공지 스킬의 SKILL.md와 reference.md 중, 스킬이 켜질 때 늘 읽히는 건 뭐고 언제만 읽히는 건 뭐야?

— 본편과 부록이 어떻게 읽히는지 확인해요

이렇게 설계가 맞는지도 Claude에게 물어보며 확인하면 돼요. 본편은 얇게, 부록은 따로 — 책상이 한결 가벼워졌어요.

한 줄로

스킬에 다 욱여넣으면 켜질 때마다 책상이 무거워요. 본문(SKILL.md)엔 핵심 지시만, 긴 자료는 참조 파일(reference.md)로 분리하고 본문이 "필요할 때 읽어라"고 가리키면, 그 자료는 쓸 때만 읽혀 컨텍스트가 절약돼요.

다음 레슨에서

스킬은 Claude가 알아서 꺼내 쓰는 도구였죠. 그런데 내가 직접 부르고 싶은 명령은 어떻게 만들까요? 다음 레슨 '슬래시 커맨드 — 나만의 명령'에서 만들어 봐요. 가게는 계속 자랍니다. 🌱