클로드 스킬은 그냥 마크다운 파일입니다 — 제 맥의 스킬 75개를 열어 봤습니다
한 줄 요약클로드 스킬은 폴더 하나와 그 안의 SKILL.md라는 마크다운 파일입니다.
맥에서는 ~/.claude/skills 아래에 있습니다.
제 맥의 스킬 75개는 파일로 1.3MB였습니다.
그런데 평소 클로드가 읽는 건 이름과 설명을 모은 목록뿐이었어요. /context로 재 보니 그 목록은 컨텍스트의 1.0%였습니다.
컨텍스트란 클로드가 한 번에 들고 있는 대화 공간이라는 뜻입니다.
본문은 그 스킬을 쓸 때만 읽힙니다.
이 1%는 정해진 상한입니다.
스킬이 많으면 자주 안 쓰는 스킬부터 설명이 빠집니다.
그래서 설명은 핵심부터 써야 해요.
매번 같은 설명을 채팅에 붙여 넣다가 스킬로 만들어 두신 적 있으시죠.
그렇게 하나둘 늘다 보면 걱정이 생깁니다. 이렇게 많이 넣어도 클로드가 느려지거나 멍청해지지 않을까?
스킬 만드는 법을 찾아보면 대부분 템플릿 한 장을 보여 주고 끝납니다.
정작 «깔아 둔 스킬이 평소에 무엇을 먹는지»는 잘 안 나와요.
제 맥에는 스킬이 75개 있습니다.
블로그 발행이나 스크린샷 같은 일을 하나씩 스킬로 만들다 보니 쌓였어요.
저도 같은 걱정이 들어서 오늘 폴더를 열고 숫자를 쟀습니다.
결론은 싱거웠습니다. 스킬은 그냥 마크다운 파일이었고, 평소엔 목록 한 장만 읽히고 있었습니다.
이 글에서 확인하실 수 있는 것
하나. 스킬이 실제로 어떤 파일로 이루어져 있는지 한 개를 끝까지 열어 보여 드립니다.
둘. 스킬 75개가 평소 클로드의 작업 공간을 얼마나 차지하는지 잰 값을 보실 수 있습니다.
셋. 스킬이 많을 때 설명이 어떻게 잘리는지, 그래서 왜 핵심부터 써야 하는지 확인하실 수 있습니다.
⚠️ 스킬 이름 목록은 싣지 않았습니다.
제 작업 내용이 그대로 드러나서요.
개수와 크기만 옮겼어요.
예시는 누구나 쓸 만한 스크린샷 스킬 하나만 열었습니다.
한 줄 결론 — 스킬은 폴더 하나, 파일 하나입니다
스킬은 클로드에게 특정 일을 하는 방법을 적어 둔 설명서입니다.
그 설명서의 정체는 SKILL.md라는 마크다운 파일이에요. 마크다운은 #나 - 같은 기호로 제목과 목록을 표시하는 평범한 텍스트 형식입니다.
맥에서 내가 만든 스킬은 이 위치에 있습니다.
~/.claude/skills/스킬이름/SKILL.md~는 내 사용자 폴더를 뜻합니다.
폴더 이름이 곧 스킬 이름입니다.
그 안에 SKILL.md만 있으면 스킬로 인식돼요.
중요한 건 클로드가 이 파일을 한꺼번에 읽지 않는다는 점입니다.
세 단계로 나눠 읽어요.
클로드 스킬 로딩 3단계 — 평소엔 ①만, 쓸 때 ②, 필요하면 ③
스킬 표준 문서(agentskills.io)는 이걸 점진적 공개라고 부릅니다.
필요한 만큼만 조금씩 꺼내 읽는다는 뜻이에요.
제 맥의 스킬 75개를 열어 봤습니다
2026-09-15에 ~/.claude/skills 폴더를 열어 셌습니다. SKILL.md가 있는 폴더가 75개였어요.
| 잰 것 | 값 |
|---|---|
| 스킬 수 | 75개 |
| SKILL.md 파일 하나뿐인 스킬 | 31개 |
| SKILL.md 크기 | 가장 작은 것 2KB · 가장 큰 것 67KB · 중간값 12KB |
| SKILL.md 75개를 합친 크기 | 약 1.3MB |
| 그중 «설명» 칸 글자 수 합계 | 28,649자 — 전체 글자의 2.8% |
스킬 75개 실측 — 2026-09-15, 제 맥의 ~/.claude/skills
75개 중 31개는 정말로 마크다운 파일 하나가 전부였습니다.
나머지는 스크립트나 참고 문서를 함께 넣어 둔 경우예요.
파일을 다 합치면 1.3MB입니다.
이걸 클로드가 매번 읽는다면 걱정할 만한 양이에요.
그런데 평소에 읽는 건 맨 위 «설명» 칸뿐입니다.
글자로 치면 전체의 2.8%입니다.
스킬 75개의 파일 크기와 평소 읽히는 양 — 가장 큰 스킬도 목록에서는 한 줄입니다
스킬 하나를 끝까지 열어 보면
예시로 스크린샷을 찍어 주는 webshot 스킬을 열었습니다.
블로그 글에 공식 사이트 화면을 넣을 때 쓰는 스킬이에요.
webshot 스킬의 SKILL.md 첫 24줄을 그대로 옮겼습니다 — 파일 크기 6KB
파일은 두 부분으로 나뉩니다.
위쪽 --- 사이는 프론트매터입니다. 스킬의 이름표예요. name에 이름을, description에 «언제 이 스킬을 쓰는지»를 적습니다.
클로드가 평소에 보는 건 여기뿐입니다.
아래쪽은 본문입니다. 사람에게 인수인계하듯 사용법과 주의할 점을 적었어요.
webshot 본문에는 명령어 옵션과 캡처 편집법이 들어 있습니다.
폴더에는 SKILL.md 옆에 bin이라는 폴더가 하나 더 있습니다.
실제로 스크린샷을 찍는 스크립트가 여기 있어요.
본문이 «이 스크립트를 실행하라»고 가리키면 그때 씁니다.
세 단계 중 ③이 이것입니다.
스킬은 오픈 표준입니다. 앤트로픽이 만든 형식을 agentskills.io에 공개했어요.
커서, 제미나이 CLI, 깃허브 코파일럿 같은 도구도 같은 폴더 형식을 읽습니다.
한 번 만든 스킬을 다른 도구로 옮길 수 있다는 뜻입니다.
평소에 클로드가 읽는 건 1%뿐이었습니다
그럼 목록 한 장은 실제로 얼마나 차지할까요.
클로드 코드의 /context 명령으로 쟀습니다. /context는 지금 대화 공간을 무엇이 얼마나 쓰는지 보여 주는 명령이에요.
claude -p "/context" --model sonnet-p는 대화창을 열지 않고 결과만 받는 옵션입니다.
빈 폴더에서 모델만 바꿔 두 번 돌렸습니다.
/context 결과의 카테고리 표를 그대로 옮겼습니다(Sonnet 5, 100만 토큰 창) — 스킬별 이름 목록은 뺐습니다
| 모델 | 대화 공간(컨텍스트 창) | 스킬 목록 | 비율 | 스킬 하나당 중간값 |
|---|---|---|---|---|
| Sonnet 5 | 100만 토큰 | 약 1만 토큰 | 1.0% | 약 100토큰 |
| Haiku 4.5 | 20만 토큰 | 약 2천 토큰 | 1.0% | 약 20토큰 |
스킬 75개 + 기본 제공 13개, 2026-09-15 · Claude Code 2.1.271
토큰은 모델이 글을 읽는 단위입니다.
한글 한두 글자가 대략 1토큰이라고 보시면 됩니다.
자세한 계산은 클로드 한글 토큰 실측에 정리했어요.
두 모델 모두 정확히 1.0%가 나왔습니다.
우연이 아니었어요.
공식 문서 문제 해결 절에 이유가 적혀 있었습니다.
Claude Code 공식 문서 「Claude를 skills로 확장하기」 중 «스킬 설명이 잘려 있음».
2026-09-15 조회
스킬 목록에는 «예산»이 있습니다.
모델 컨텍스트 창의 1%입니다. 1%는 저절로 작게 나온 숫자가 아니라 상한이었어요.
문서는 목록이 이 예산을 넘칠 때 벌어지는 일도 적었습니다. 스킬 이름은 항상 전부 남습니다. 대신 설명이 짧아지고, 가장 적게 부르는 스킬부터 설명이 지워집니다.
제 실측을 이 문장에 대 보면 이렇습니다.
Sonnet 5(창 100만) 에서는 예산이 1만 토큰입니다. /context의 Skills 줄이 딱 그만큼인 10k였어요.
그중 제 스킬 75개 몫이 약 8,100토큰, 하나당 중간값 100토큰이었습니다.
Haiku 4.5(창 20만) 에서는 예산이 2천 토큰입니다.
같은 75개가 들어갈 자리가 5분의 1로 줄었어요.
스킬 하나당 토큰이 100에서 20으로 떨어졌고, webshot도 약 60토큰에서 20토큰 미만이 됐습니다. 설명이 거의 이름표만 남은 셈입니다.
결론은 둘입니다.
첫째, 스킬을 많이 깔아도 대화 공간은 1% 넘게 안 씁니다. 넘치는 만큼 설명이 줄 뿐이에요.
둘째, 대신 «알아서 불리는 정확도»가 떨어질 수 있습니다. 클로드는 설명을 보고 스킬을 고릅니다.
설명이 잘리면 필요한 단어가 빠져서 못 고를 수 있어요.
문서가 «주요 사용 사례를 먼저 입력하라»고 권하는 이유입니다.
목록 하나당 설명은 예산과 별개로 1,536자까지만 들어갑니다.
예산은 설정에서 늘릴 수 있습니다.
항목 이름은 skillListingBudgetFraction이에요.
예를 들어 0.02는 2%입니다.
안 쓰는 스킬은 /skill-doctor로 찾을 수 있다고 문서에 적혀 있어요.
스킬·CLAUDE.md·채팅 붙여넣기, 무엇에 쓸까
같은 설명서라도 어디에 적느냐에 따라 읽히는 방식이 다릅니다.
지시를 적는 세 자리 — 언제 읽히고, 무엇을 차지하나
| CLAUDE.md | 스킬 | 채팅에 붙여넣기 | |
|---|---|---|---|
| 언제 읽히나 | 세션 시작 때 전부 | 평소엔 목록, 쓸 때 본문 | 붙여 넣은 그 대화에서만 |
| 길어지면 | 매번 공간을 차지 | 쓰기 전엔 거의 안 차지 | 대화가 끝나면 사라짐 |
| 맞는 내용 | 늘 지켜야 할 짧은 규칙 | 특정 작업의 긴 절차 | 한 번만 쓸 지시 |
추천은 이렇습니다.
매번 같은 절차를 채팅에 붙여 넣고 있다면, 그건 스킬로 옮길 때입니다.
CLAUDE.md는 모든 세션에 통째로 실립니다.
가끔 하는 일의 긴 절차를 여기 적으면 매번 공간만 차지해요.
그런 내용이 스킬 자리입니다.
실수를 막는 규칙의 자리는 하네스 엔지니어링 글에서 네 층으로 다뤘습니다.
내 맥에서 스킬 폴더 열어 보는 법
직접 열어 보시면 «그냥 파일»이라는 게 바로 와닿습니다.
Step 1. Finder에서 폴더로 이동합니다.
Finder에서 Command + Shift + G를 누르세요. «폴더로 이동» 창이 뜹니다.
아래 경로를 붙여 넣으세요.
~/.claude/skills.claude처럼 점으로 시작하는 폴더는 숨김 폴더라 평소엔 안 보입니다.
숨김 파일을 보려면 Command + Shift + .을 누르세요.
한 번 더 누르면 다시 숨겨집니다.
Step 2. SKILL.md를 스페이스바로 봅니다.
SKILL.md를 선택하고 스페이스바를 누르면 훑어보기로 열립니다.
텍스트 편집기로 열어도 됩니다.
Step 3. 터미널에서 개수와 크기를 셉니다.
ls ~/.claude/skills/*/SKILL.md | wc -ldu -ch ~/.claude/skills/*/SKILL.md | tail -1앞의 것은 스킬 개수, 뒤의 것은 파일 크기 합계입니다.
Step 4. 클로드 코드 안에서 차지하는 양을 봅니다.
/context클로드 코드 대화창에 치면 카테고리 표가 나옵니다. Skills 줄이 목록이 차지하는 양이에요.
Skills 줄은 1%를 넘지 않는 게 정상입니다.
예산이 1%라서요.
스킬이 자꾸 안 불린다면 그때 설명이 잘렸는지 의심하세요.
/context 결과와 스킬 폴더에는 내 스킬 이름과 설명이 전부 나옵니다.
화면을 캡처해 공유하실 땐 목록 부분을 가리세요.
저도 이 글에서는 카테고리 표만 옮겼습니다.
막히면 — 증상별로
① 스킬을 만들었는데 목록에 안 뜬다
파일 이름이 정확히 SKILL.md인지 보세요.
그리고 파일 첫 줄이 ---로 시작해야 합니다.
공식 문서는 여는 ---가 반드시 첫 줄이어야 한다고 적었어요.
그 앞에 빈 줄이 있으면 안 됩니다.
② 목록엔 있는데 알아서 안 불린다
설명의 첫 문장을 확인하세요.
클로드는 설명을 보고 이 스킬을 쓸지 정합니다. «무슨 일에 쓰는지»가 첫 문장에 없으면 잘린 목록에서 안 보일 수 있어요.
확실히 쓰고 싶으면 /스킬이름으로 직접 부르면 됩니다.
③ 작은 모델로 바꾸니 스킬을 덜 찾는다
위 실측처럼 창이 작은 모델은 목록 예산도 작습니다.
그래서 설명이 짧게 잘려요.
설명 앞부분에 동사와 대상을 넣으세요. «웹페이지 스크린샷을 찍는다»처럼요.
거의 안 쓰는 스킬을 끄면 남은 스킬의 설명이 살아납니다.
④ 스킬을 여러 개 부르고 나니 대화가 무거워졌다
본문은 한 번 부르면 그 대화 동안 계속 남습니다. 스킬을 많이 불렀다면 목록이 아니라 본문 탓이에요.
대화가 압축될 때는 최근 스킬부터 앞부분만 다시 붙습니다.
공식 문서 기준 스킬당 5,000토큰, 합계 25,000토큰까지입니다.
압축 시점은 compact 글에서 다뤘습니다.
자주 묻는 것
Q. 스킬을 100개 넘게 깔아도 되나요?
대화 공간은 괜찮습니다.
목록은 몇 개를 깔든 창의 1%를 넘지 않아요.
대신 개수가 늘수록 스킬 하나당 설명이 더 짧게 잘립니다.
100개 이상은 직접 재 보지 않았습니다.
개수보다는 비슷한 스킬이 여러 개인 게 문제입니다.
설명이 겹치면 클로드가 어느 것을 부를지 헷갈립니다.
Q. 스킬을 만들려면 코딩을 알아야 하나요?
아닙니다.
제 스킬 75개 중 31개는 마크다운 파일 하나뿐이었어요.
절차를 글로 적으면 됩니다.
스크립트는 필요할 때만 옆에 두세요.
Q. 남이 만든 스킬을 받아 써도 되나요?
받기 전에 SKILL.md와 옆의 스크립트를 열어 읽어 보세요.
스킬은 파일이라 무엇을 시키는지 전부 글로 보입니다. 모르는 곳으로 파일을 보내는 명령이 있으면 쓰지 않는 게 맞습니다.
Q. 채팅 앱(claude.ai)의 스킬도 같은 파일인가요?
형식은 같은 SKILL.md입니다.
다만 채팅 앱에서는 [사용자 지정 → 스킬]에서 올리고 켭니다.
맥의 ~/.claude/skills 폴더와 자동으로 맞춰지는지는 단정하지 않겠습니다.
공식 문서끼리 설명이 달라서요.
다음 단계
- 클로드에게 «다음엔 잘해줘»라고 쓰지 마세요 — 같은 실수를 두 번 못 하게 만드는 하네스 엔지니어링 — 스킬이 네 층 중 어디에 서는지
- 클로드 코드 compact, 언제 눌러야 하나 — 부른 스킬 본문이 압축 때 어떻게 되는지
- 클로드 한글 토큰, 직접 재봤습니다 — 이 글에 나온 토큰 숫자를 읽는 법
기준일 2026-09-15. 클로드 코드 2.1.271에서 claude -p "/context"를 Sonnet 5(100만 토큰 창)와 Haiku 4.5(20만 토큰 창)로 한 번씩 돌린 값입니다.
출처 — 공식 문서 두 쪽을 2026-09-15에 열어 확인했습니다.
스킬 문서는 code.claude.com/docs/ko/skills 입니다.
Agent Skills 표준 소개는 agentskills.io 입니다.
스킬 개수·크기·설명 글자 수는 같은 날 직접 열어 센 값입니다.
스킬 이름과 설명은 싣지 않았습니다.
'Claude code' 카테고리의 다른 글
| 클로드가 없는 법 조문을 지어냈습니다 — 출처 확인을 클로드에게 시키는 법 (0) | 2026.09.18 |
|---|---|
| 클로드 스킬 예시, 원칙당 2~3개면 충분합니다 — 지식이 아니라 «취향»을 가르치는 자리라서 (0) | 2026.09.17 |
| 클로드에게 «다음엔 잘해줘»라고 쓰지 마세요 — 같은 실수를 두 번 못 하게 만드는 하네스 엔지니어링 (0) | 2026.09.14 |
| 클로드 코드 뭘 시킬지 모를 때 — 새 레포에선 «시킬 수 있는 일 5개»부터 물어봅니다 (0) | 2026.09.13 |
| 클로드 코드에 «다시 고쳐봐» 대신 «설명해봐»를 넣으면 턴이 34% 줄었습니다 (0) | 2026.09.12 |
