references/ — 스킬의 참고서 폴더

선생님의 가방 속 비밀

학창 시절, 수업 중에 갑자기 어려운 질문이 나왔던 적 기억나세요?

"선생님, 이게 왜 이렇게 되는 건데요?"

그러면 선생님이 이렇게 말하죠: "잠깐만, 참고 자료 좀 찾아볼게."

그리고 커다란 가방에서 참고서를 한 권 꺼내요. 그 안에서 해당 페이지를 찾아서, "여기 보렴, 이렇게 되어 있어" 하고 설명해줘요.

선생님이 교과서 내용은 다 외우고 있지만, 모든 세부 사항을 머리에 담고 있지는 않잖아요? 그래서 참고서를 가방에 넣고 다니는 거예요.

AI 스킬의 references/ 폴더도 정확히 같은 역할이에요.

SKILL.md가 "교과서 본문"이라면, references/는 "선생님 가방 속 참고서들"이에요. 평소에는 가방 안에 잠들어 있다가, 필요한 순간에 꺼내서 참고하는 거예요.

왜 SKILL.md에 다 넣으면 안 되나요?

"그냥 SKILL.md 하나에 다 쓰면 되지, 왜 파일을 나눠요?"

좋은 질문이에요! 처음에는 저도 그렇게 생각했거든요. 근데 세 가지 문제가 있어요.

문제 1: 너무 길어지면 읽기 어렵다

카카오톡에서 친구가 메시지를 보냈는데, 스크롤을 5분이나 내려야 끝나는 메시지라면 어떨 것 같아요? 읽다가 중간에 포기하죠.

SKILL.md도 마찬가지예요. AI가 읽는 거라고 해도, 파일이 너무 길면 중요한 지시사항이 묻혀버릴 수 있어요. "이건 중요한 규칙인데, 3000줄 중 2847번째 줄에 있으니까 AI가 놓쳤네..." 이런 상황이 생길 수 있어요.

핵심 지시사항은 SKILL.md에 간결하게 넣고, 세부 참고 자료는 따로 빼는 게 훨씬 효율적이에요.

문제 2: 수정할 때 다른 부분이 망가질 수 있다

파일 하나가 모든 걸 담고 있으면, 한 부분을 고치다가 실수로 다른 부분을 건드릴 수 있어요.

예를 들어 스타일 가이드를 수정하려고 SKILL.md를 열었는데, 실수로 위에 있는 핵심 지시사항의 줄바꿈을 하나 지워버린 거예요. 눈에 안 보이는 작은 실수인데, 스킬이 갑자기 이상하게 작동하기 시작해요.

파일을 나누면 이런 위험이 줄어들어요. 스타일 가이드를 고칠 때는 STYLE-GUIDE.md만 열면 되니까요.

문제 3: 여러 스킬이 같은 자료를 못 쓴다

이게 가장 큰 이유예요.

회사에서 3개의 스킬을 만들었다고 해봐요:

• weekly-report-writer (주간 보고서 작성)
• meeting-note-taker (회의록 작성)
• email-drafter (이메일 초안 작성)

이 세 스킬 모두 "우리 회사 문체 가이드"를 따라야 해요. 존댓말 쓰기, 간결하게 쓰기, 특정 용어 사용하기 같은 규칙이요.

만약 문체 가이드가 각 SKILL.md 안에 복사-붙여넣기 되어 있다면? 가이드가 바뀔 때마다 세 파일을 모두 수정해야 해요. 귀찮고, 실수할 가능성도 높아요.

하지만 문체 가이드가 references/STYLE-GUIDE.md에 따로 있고, 세 스킬 모두 이 파일을 참고하게 하면? 하나만 수정하면 세 스킬 모두 업데이트돼요.

references/ 안에 뭘 넣을까?

그럼 구체적으로 어떤 파일들이 references/에 들어갈까요? 대표적인 것들을 소개할게요.

1. SHARED-PREAMBLE.md — 공유 서문

"preamble"은 "서문", "전문"이라는 뜻이에요. 여러 스킬이 공통으로 지켜야 할 규칙을 적어놓는 파일이에요.

예를 들면:

# 공유 서문

## 기본 규칙
- 항상 한국어로 응답하세요
- 존댓말을 사용하세요
- 마크다운 형식으로 출력하세요

## 회사 용어
- "고객" 대신 "파트너"라고 부르세요
- "문제" 대신 "개선 기회"라고 표현하세요
- "실패" 대신 "학습 포인트"라고 말하세요

이 파일 하나를 여러 스킬이 참고하면, 모든 스킬이 같은 기본 규칙을 따르게 돼요.

2. TEMPLATES.md — 재사용 가능한 양식 모음

스킬이 자주 사용하는 양식을 모아놓는 파일이에요.

# 보고서 템플릿 모음

## 주간 보고서 양식

**제목:** [날짜] 주간 현황 보고
**작성자:** [이름]
**기간:** [시작일] ~ [종료일]

### 1. 주요 성과
-

### 2. 진행 중인 과제
-

### 3. 다음 주 계획
-

### 4. 도움이 필요한 사항
- 

SKILL.md에서 "보고서를 작성할 때는 references/TEMPLATES.md의 양식을 사용하세요"라고 쓰면, AI가 이 템플릿을 참고해서 일관된 양식의 보고서를 만들어줘요.

3. EXAMPLES.md — 예시 모음

"이런 식으로 만들어줘"라는 예시를 모아놓는 파일이에요. AI는 예시가 있으면 훨씬 더 정확하게 일해요.

# 예시 모음

## 좋은 보고서 예시

**제목:** 2024.03.15 주간 현황 보고

안녕하세요, 금주 현황 공유드립니다.

### 1. 주요 성과
- 신규 파트너 30건 계약 완료 (목표 대비 120%)
- 고객 만족도 조사 결과 4.5/5.0 달성

### 2. 진행 중인 과제
- Q2 마케팅 전략 수립 중 (진행률 60%)

감사합니다.

---

## 나쁜 보고서 예시 (이렇게 쓰지 마세요)

이번 주 매출 올랐고 고객도 늘었습니다. 다음 주도 열심히 하겠습니다.

좋은 예시와 나쁜 예시를 같이 보여주면, AI가 "아, 이런 방향으로 쓰면 되고, 이렇게 쓰면 안 되는구나" 하고 명확하게 이해해요.

4. 도메인 지식 파일

특정 분야의 전문 지식을 담아놓는 파일이에요. 예를 들어:

• PRODUCT-INFO.md: 우리 회사 제품 정보
• COMPETITOR-ANALYSIS.md: 경쟁사 분석 자료
• INDUSTRY-TERMS.md: 업계 전문 용어 사전
• BRAND-VOICE.md: 브랜드 톤앤매너 가이드

이런 파일들이 있으면 AI가 우리 회사, 우리 업계의 맥락을 이해하고 더 적절한 결과물을 만들어줘요.

실제 예시로 보기

이론만으론 감이 안 올 수 있으니, 구체적인 예시를 보여드릴게요.

"마케팅 콘텐츠 작성 스킬"을 만든다고 가정해볼게요:

marketing-content-writer/
├── SKILL.md
└── references/
    ├── BRAND-VOICE.md
    ├── TEMPLATES.md
    ├── EXAMPLES.md
    └── PRODUCT-INFO.md

각 파일의 역할:

• SKILL.md: "마케팅 콘텐츠를 작성하는 방법. 블로그 글, SNS 포스트, 뉴스레터를 만들 수 있음. references/의 가이드를 참고할 것."
• BRAND-VOICE.md: "우리 브랜드는 친근하고 유머러스한 톤을 사용합니다. '당신' 대신 '여러분'을 쓰세요..."
• TEMPLATES.md: 블로그 글 양식, SNS 포스트 양식, 뉴스레터 양식
• EXAMPLES.md: 실제로 잘 쓴 콘텐츠 예시 3-5개
• PRODUCT-INFO.md: 우리 제품의 이름, 특징, 가격, 타겟 고객 정보

이제 "블로그 글 써줘"라고 하면, AI가:

1. SKILL.md를 읽고 → "아, 마케팅 콘텐츠를 만드는 스킬이구나"
2. BRAND-VOICE.md를 참고하고 → "친근한 톤으로 써야 하네"
3. TEMPLATES.md의 블로그 양식을 따르고 → "이 구조로 쓰면 되겠다"
4. EXAMPLES.md를 참고하고 → "이런 느낌으로 쓰면 되는구나"
5. PRODUCT-INFO.md에서 제품 정보를 가져와서 → "이 내용을 포함시키자"

결과: 우리 브랜드 톤에 맞고, 양식도 지킨, 제품 정보가 정확한 블로그 글이 뚝딱 나와요.

이게 references/ 폴더의 힘이에요.

SKILL.md에서 참고 파일 언급하기

"그래서 SKILL.md에서 references/ 파일을 어떻게 연결하는 건데요?"

아주 간단해요. 그냥 글로 말하면 돼요.

SKILL.md 안에 이렇게 쓰면 됩니다:

# 마케팅 콘텐츠 작성 스킬

이 스킬은 마케팅 콘텐츠를 작성합니다.

## 참고 자료

콘텐츠를 작성할 때 다음 파일들을 참고하세요:

- **브랜드 톤앤매너**: `references/BRAND-VOICE.md`를 읽고
  해당 가이드를 준수하세요.
- **양식**: `references/TEMPLATES.md`에서 적절한 템플릿을
  선택하여 사용하세요.
- **예시**: `references/EXAMPLES.md`의 좋은 예시를 참고하여
  비슷한 품질로 작성하세요.
- **제품 정보**: `references/PRODUCT-INFO.md`에서 정확한
  제품 정보를 가져다 사용하세요.

네, 이게 전부예요. 특별한 문법이 필요 없어요. 파일 경로를 적어주면, AI가 알아서 찾아서 읽어요.

마치 보고서에서 "자세한 내용은 부록 A를 참조하세요"라고 쓰는 것과 같아요. AI는 "아, 이 파일을 참고하라는 거구나" 하고 해당 파일을 열어봐요.

모듈화의 마법

references/ 폴더의 진짜 힘은 모듈화(modularization)에 있어요.

"모듈화"가 뭐냐고요? 쉽게 말하면 "레고 블록처럼 조립하기"예요.

레고를 생각해보세요. 같은 블록으로 집도 만들고, 자동차도 만들고, 로봇도 만들 수 있잖아요? 블록 하나를 바꾸면 완성품의 일부만 바뀌고, 나머지는 그대로예요.

references/ 파일도 마찬가지예요:

이 한 가지 변경으로 10개 스킬이 동시에 업데이트되는 거예요. 이게 모듈화의 마법이에요.

references/ = 교과서의 부록

마지막으로, 전체를 깔끔하게 정리하는 비유 하나만 더 할게요.

교과서를 떠올려보세요:

• 본문: 핵심 개념을 설명하는 부분 → SKILL.md
• 부록 A: 용어 사전: 전문 용어 정리 → references/TERMS.md
• 부록 B: 참고 표: 자주 쓰는 데이터 → references/DATA.md
• 부록 C: 예제 모음: 연습 문제와 풀이 → references/EXAMPLES.md

본문이 "이야기"를 들려준다면, 부록은 "자세한 데이터"를 제공해요.

본문만 읽어도 큰 그림은 이해할 수 있지만, 부록이 있으면 더 정확하고 풍부한 결과물을 만들 수 있어요.

스킬도 마찬가지예요. SKILL.md만으로도 작동하지만, references/가 있으면 훨씬 더 똑똑하고 일관된 결과물을 만들어줘요.

제2부를 마치며 — 해부학 완료!

여기까지 오신 여러분, 축하드려요!

제2부 "스킬 패키지 해부학"을 통해 우리가 배운 걸 전체적으로 정리해볼게요:

1. 챕터 4: 스킬은 SKILL.md 파일 하나에서 시작한다. 코딩이 아니라 글쓰기다.
2. 챕터 5: 스킬은 얇은/보통/두꺼운 세 레벨이 있다. 무조건 얇은 것부터 시작하자.
3. 챕터 6: 프론트매터(YAML 헤더)는 스킬의 신분증이다. description이 가장 중요하다.
4. 챕터 7 (지금): references/는 참고 자료 폴더다. 모듈화의 마법으로 여러 스킬을 효율적으로 관리할 수 있다.

이제 여러분은 아무 스킬 패키지나 열어봐도 읽을 수 있어요. 구조를 알고 있으니까요.

마치 자동차의 기본 구조(엔진, 바퀴, 핸들, 브레이크)를 알면 어떤 차든 운전할 수 있는 것처럼, 스킬의 기본 구조(SKILL.md, 프론트매터, references/)를 알면 어떤 스킬이든 이해할 수 있어요.

그리고 다음 파트에서는 드디어...