뼈대 살펴보기 — 파일 구조와 규칙

모든 건물에는 설계도가 있다

노래를 생각해보세요.

어떤 노래든 대부분 이런 구조를 따르잖아요: 인트로 → 벌스 → 후렴 → 벌스 → 후렴 → 브릿지 → 후렴 → 아웃트로.

BTS의 "Dynamite"도, 아이유의 "좋은 날"도, 여러분이 좋아하는 어떤 노래든 이 구조를 크게 벗어나지 않아요.

건물도 마찬가지예요. 아파트든, 카페든, 학교든 — 기초, 기둥, 벽, 지붕이라는 기본 구조가 있어요.

스킬 패키지도 예측 가능한 구조가 있어요.

이 구조를 알면 엄청난 이점이 있어요: 어떤 스킬이든 열어보는 순간 "아, 이렇게 되어 있구나" 하고 바로 이해할 수 있거든요. 마치 처음 가보는 아파트에서도 "현관 → 거실 → 부엌 → 방" 순서를 예상할 수 있는 것처럼요.

오늘은 스킬 패키지의 뼈대를 세 가지 레벨로 나눠서 살펴볼 거예요.

스킬의 세 가지 레벨

스킬 패키지는 복잡도에 따라 크게 세 가지 단계로 나눌 수 있어요. 제가 이름을 붙여봤어요:

1. 얇은 스킬 (Thin) — 포스트잇 한 장
2. 보통 스킬 (Medium) — 직원 핸드북
3. 두꺼운 스킬 (Thick) — 전체 교육 프로그램

하나씩 살펴볼게요.

레벨 1: 얇은 스킬 — 포스트잇 한 장

가장 단순한 형태예요. 지난 챕터에서 본 바로 그것:

my-thin-skill/
└── SKILL.md

끝이에요. 폴더 하나, 파일 하나.

이건 어떨 때 쓸까요? 지식만 전달하면 되는 경우예요.

예를 들면:

• "이메일 쓸 때 항상 이 양식을 써줘"
• "코드 리뷰할 때 이 체크리스트를 따라줘"
• "한국어로 답변할 때 이 문체 가이드를 지켜줘"

별도의 참고 자료나 스크립트 없이, SKILL.md 안에 모든 것이 담겨 있는 거예요.

초보자라면? 무조건 여기서 시작하세요. 스킬 만들기의 "Hello, World"예요.

레벨 2: 보통 스킬 — 직원 핸드북

스킬이 조금 복잡해지면, SKILL.md 하나로는 부족해질 때가 와요. "이 내용도 넣어야 하고, 저 내용도 넣어야 하는데, 파일이 너무 길어진다..."

그때 references/ 폴더가 등장합니다:

my-medium-skill/
├── SKILL.md
└── references/
    ├── STYLE-GUIDE.md
    ├── TEMPLATES.md
    └── EXAMPLES.md

references/는 이름 그대로 "참고 자료" 폴더예요.

SKILL.md가 "메인 설명서"라면, references/ 안의 파일들은 "부록"이에요. 교과서의 본문과 부록의 관계라고 생각하면 돼요.

• STYLE-GUIDE.md: "이런 스타일로 써줘" (문체, 톤앤매너 가이드)
• TEMPLATES.md: "이 양식을 사용해" (재사용 가능한 템플릿 모음)
• EXAMPLES.md: "이런 식으로 하면 돼" (예시 모음)

언제 이 레벨이 필요할까요?

• SKILL.md가 너무 길어져서 읽기 어려울 때
• 여러 스킬이 같은 참고 자료를 공유해야 할 때
• 참고 자료를 따로 관리하고 싶을 때

레벨 3: 두꺼운 스킬 — 전체 교육 프로그램

가끔은 스킬이 정말 많은 일을 해야 할 때가 있어요. 단순히 "글을 써줘"가 아니라, "스크립트를 실행하고, 파일을 생성하고, API를 호출해"처럼요.

그때 bin/과 src/ 폴더가 추가됩니다:

my-thick-skill/
├── SKILL.md
├── references/
│   ├── SHARED-PREAMBLE.md
│   ├── ARCHITECTURE.md
│   └── API-GUIDE.md
├── bin/
│   ├── setup.sh
│   └── deploy.sh
└── src/
    ├── helpers.js
    └── templates/
        ├── report.hbs
        └── email.hbs

와, 갑자기 복잡해 보이죠? 근데 걱정 마세요. 하나씩 볼게요:

• SKILL.md: 여전히 메인 설명서. 항상 여기가 시작점이에요.
• references/: 참고 자료 폴더 (레벨 2와 동일)
• bin/: 실행 가능한 스크립트들이 들어가는 곳. "bin"은 "binary"의 줄임말인데, 쉽게 말해 "실행 파일 모음"이에요.
• src/: 소스 코드가 들어가는 곳. "source"의 줄임말이에요.

"잠깐, 스크립트? 코드? 코딩 못하는데요?"

걱정 마세요! 두꺼운 스킬은 나중에 필요할 때 만드는 거예요. 그리고 그때쯤이면 이 책을 다 읽고, AI에게 코드 작성을 시키는 방법도 알게 될 거예요. 지금은 "이런 구조도 있구나" 정도만 알면 충분해요.

세 레벨 한눈에 비교

표로 정리하면 이렇게 돼요:

중요한 건, 어떤 레벨이든 SKILL.md는 항상 있다는 거예요. SKILL.md가 "정문"이에요. AI는 항상 SKILL.md를 먼저 읽고, 거기에 적힌 안내에 따라 다른 파일들을 참고해요.

이름 짓기 규칙

스킬 패키지를 만들 때 지켜야 할 이름 짓기 규칙이 있어요. 어렵지 않으니까 가볍게 읽어주세요.

폴더 이름: 케밥 케이스

"케밥 케이스(kebab-case)"라는 이름이 재미있죠? 이게 뭐냐면, 단어를 하이픈(-)으로 연결하는 거예요.

# 좋은 예
weekly-report-writer
code-review-helper
email-template-maker

# 나쁜 예
weeklyReportWriter     (카멜 케이스 - 여기선 안 써요)
Weekly_Report_Writer   (스네이크 케이스 - 여기선 안 써요)
weeklyreportwriter     (읽기 어려워요)

왜 케밥 케이스를 쓰냐고요? 읽기 쉬우니까요! 그리고 URL이나 파일 시스템에서 문제가 안 생기거든요.

파일 이름: 대문자 마크다운

스킬의 주요 파일들은 대문자로 이름을 짓는 게 관례예요:

SKILL.md          (메인 설명서 - 필수!)
SHARED-PREAMBLE.md  (공유 서문)
STYLE-GUIDE.md    (스타일 가이드)
TEMPLATES.md      (템플릿 모음)
EXAMPLES.md       (예시 모음)

대문자를 쓰는 이유? 눈에 띄게 하려고요. 폴더를 열었을 때 "이게 중요한 파일이구나!" 하고 바로 알 수 있잖아요.

이건 사실 오래된 프로그래밍 관례예요. README.md라는 파일 이름 들어보셨나요? 오픈소스 프로젝트에서 "나를 먼저 읽어!"라는 뜻으로 대문자로 쓰는 건데, 같은 원리예요.

황금 규칙: SKILL.md는 항상 정문이다

이 챕터에서 딱 하나만 기억한다면, 이걸 기억하세요:

이게 왜 중요하냐면요. 스킬 패키지를 처음 보는 사람(혹은 AI)은 어디서부터 읽어야 할지 알아야 하거든요. SKILL.md가 그 "시작점" 역할을 해요.

SKILL.md 안에는 이런 내용이 들어가요:

• 이 스킬이 뭘 하는지 (소개)
• 어떻게 사용하는지 (사용법)
• 어떤 참고 자료를 봐야 하는지 (references/ 안내)
• 어떤 규칙을 지켜야 하는지 (제약 조건)

그래서 아무리 복잡한 스킬이라도, SKILL.md만 열어보면 전체 그림을 파악할 수 있어요.

마치 뮤지컬의 프로그램 북처럼요. 공연장에 들어가서 프로그램 북을 보면, 전체 줄거리, 배우 소개, 막 구성이 다 적혀 있잖아요. SKILL.md도 그런 역할이에요.

어디서 시작하면 좋을까?

대답은 명확해요: 무조건 얇은 스킬부터.

이건 요리를 배울 때와 같아요. 처음부터 코스 요리를 만들려고 하면 좌절하잖아요? 라면부터 끓이세요. 라면이 잘 되면 볶음밥. 볶음밥이 잘 되면 파스타. 이렇게 단계를 밟아가는 거예요.

스킬도 마찬가지예요:

1. 얇은 스킬로 시작 → SKILL.md 하나 잘 쓰는 법을 익히기
2. 보통 스킬로 확장 → 참고 자료를 분리하는 법 익히기
3. 두꺼운 스킬로 진화 → 스크립트와 코드를 연동하는 법 익히기

이 책에서도 이 순서대로 진행할 거예요. 제3부에서 직접 얇은 스킬을 만들어보고, 그 다음에 점점 키워나갈 거예요.