클로드 코드 스킬 만들기는 폴더 하나와 파일 하나로 시작합니다. 순서는 이렇습니다. 매번 같은 말로 시키는 작업 하나를 고르고, ~/.claude/skills/스킬이름/SKILL.md 파일을 만든 뒤, 맨 위에 이름과 설명을 적고, 그 아래에 해야 할 일을 순서대로 적습니다. 그러고 나서 /스킬이름으로 불러 보면 끝입니다. 이 글은 이 순서를 공식 문서로 확인하고, 제 작업 폴더에 실제로 들어 있는 스킬 두 개를 예로 풀어 씁니다.
저는 코드를 직접 짜는 사람이 아니라 AI에게 일을 맡기는 쪽입니다. 그래서 이 글의 "만들기"는 SKILL.md라는 문서 파일을 쓰는 일이고, 프로그래밍 지식은 필요하지 않습니다. 다만 아래 사례는 파일에 적힌 내용만 옮겼고, 파일에 없는 사정은 추측해서 적지 않았습니다.
스킬이 무엇인지 한 줄로
스킬은 "반복해서 시키는 일의 설명서"를 폴더로 묶어 둔 것입니다. 공식 문서는 모든 스킬에 SKILL.md 파일이 필요하고, 이 파일이 두 부분으로 이뤄진다고 설명합니다. 맨 위 --- 사이의 설정 부분(언제 쓸지)과 그 아래 본문(클로드가 따를 지시)입니다. 설정 부분은 파일의 첫 줄이 ---일 때만 설정으로 읽힙니다.
평소 대화에서는 스킬마다 설명 부분만 미리 올라와 있고, 본문은 그 스킬이 불릴 때 비로소 읽힙니다. 스킬을 여러 개 만들어 두어도 대화가 무거워지지 않는 이유입니다.
어디에 만드나: 위치에 따라 쓰이는 범위가 다릅니다
| 위치 | 경로 | 쓰이는 범위 |
|---|---|---|
| 개인 | ~/.claude/skills/<이름>/SKILL.md | 이 컴퓨터의 모든 프로젝트 |
| 프로젝트 | .claude/skills/<이름>/SKILL.md | 그 프로젝트 폴더에서 연 세션 |
| 하위 폴더 | <하위폴더>/.claude/skills/<이름>/SKILL.md | 그 하위 폴더 안에서 작업할 때 |
| 플러그인 | <플러그인>/skills/<이름>/SKILL.md | /플러그인이름:스킬이름으로 호출 |
같은 이름이 개인과 프로젝트에 둘 다 있으면 개인이 이긴다고 문서에 적혀 있습니다. 혼자 쓰는 작업 순서는 개인 위치에, 팀이 같이 쓸 것은 프로젝트 위치에 두는 식으로 나누면 됩니다. 폴더 이름을 synced나 anthropic-skills로 짓는 것은 예약된 이름이라 피해야 합니다.
만드는 순서 여섯 단계
1. 반복 작업 하나만 고릅니다. 최근 일주일 동안 같은 설명을 두 번 이상 붙여 넣은 작업이면 후보입니다. 처음에는 작게 시작하세요.
2. 폴더를 만듭니다. 이름은 소문자·숫자·하이픈으로 짓습니다. 이름 규칙은 API용 스킬 작성 안내에 "소문자, 숫자, 하이픈만, 64자 이하"로 나와 있습니다. 이름만 보고 무슨 일인지 알 수 있게 blog-image-directive처럼 짓는 편이 낫습니다.
3. SKILL.md 맨 위에 이름과 설명을 적습니다. 이름은 생략하면 폴더 이름이 쓰입니다. 설명은 "권장" 항목이고 사실상 가장 중요합니다. 아래 별도 절에서 다룹니다.
4. 본문에 순서를 적습니다. 클로드가 이미 아는 일반 설명은 빼고, 내 작업에서만 필요한 기준·순서·금지를 적습니다. 본문은 500줄 안쪽으로 유지하라는 안내가 있고, 길어지면 참고 파일을 따로 두고 SKILL.md에서 가리키게 합니다.
5. 불러 봅니다. /스킬이름을 대화 첫머리에 쓰면 바로 실행됩니다. 설명에 맞는 말을 해서 자동으로 불리는지도 따로 확인합니다.
6. 고칩니다. 스킬 폴더는 감시되고 있어서, 세션 중에 파일을 고치면 재시작 없이 반영된다고 문서에 나옵니다. 단, 세션을 시작할 때 아예 없던 최상위 skills 폴더를 새로 만든 경우에는 /reload-skills를 한 번 실행해야 합니다.
제 작업 폴더에 있는 스킬 두 개
실제로 제 컴퓨터의 개인 스킬 폴더에는 블로그 작업용 스킬이 여러 개 있습니다. 그중 두 개의 SKILL.md에 적힌 내용을 그대로 옮겨 보겠습니다.
| 구분 | 문체 기준 스킬 | 이미지 문구 스킬 |
|---|---|---|
| 폴더 이름 | korean-writing-voice | blog-image-directive |
| 하는 일 | 한국어 글이 AI 글 같다는 소리를 안 듣게 문체를 맞춤 | 블로그 원고 속 이미지 지시문을 같은 문구가 두 번 나오지 않게 씀 |
| 파일 구성 | SKILL.md 하나 | SKILL.md 하나 |
| 본문 크기 | 약 6KB | 약 6KB |
| 설명 문장의 끝 | "…쓰거나 고칠 때 쓴다" | "…넣을 때 반드시 따른다" |
둘 다 파일이 하나뿐이고 6KB 안팎입니다. 거창한 시스템이 아니라 "한 번 겪은 실수를 다시 겪지 않기 위한 메모"가 스킬이 된 모양입니다.
### 사례 1. 문체 스킬: 감이 아니라 숫자로 적은 기준
문체 스킬은 "AI 글 같아, 말투가 이상하다"는 지적을 받은 날(2026년 9월 10일)의 기록으로 시작합니다. 감으로 고치지 않고 상위 블로거 글 448편, 문장 1,704개를 재서 기준을 잡았다고 적혀 있습니다. 파일 안 비교표에서 눈에 띄는 대목은 이렇습니다.
- "습니다·입니다"로 끝나는 문장이 사람 글에서는 16%인데, 당시 제 글은 거의 100%였습니다.
- 문장 길이의 중앙값은 둘 다 20자로 같았습니다. 차이는 분포였습니다. 75% 지점이 사람 글은 39자, 제 글은 25자였고, 90% 지점은 59자 대 28자였습니다.
- 굵은 글씨는 사람 글이 8개 안팎, 제 글은 30개가 넘었습니다.
이 파일에는 "정정"도 남아 있습니다. 다음 날(9월 11일) 처음 적었던 "명사로 끊기 32%"가 틀렸다고 고쳐 적었습니다. 그 칸의 대부분이 블로거가 문장 중간에서 줄을 바꾼 조각과 해시태그 줄이었기 때문이라는 설명입니다. 스킬 파일은 한 번 쓰고 끝나는 문서가 아니라 틀린 곳을 고쳐 나가는 문서라는 점을 보여 주는 대목입니다.
본문 끝에는 쓴 원고의 문장 비율을 재 보는 작은 점검 코드가 붙어 있고, 목표가 숫자로 적혀 있습니다. "습니다" 비율 목표 16%, 25%가 넘으면 손보기, 굵게 8개 안팎 같은 식입니다. 클로드에게 "자연스럽게 써 줘"라고 시키는 대신, 잴 수 있는 기준을 스킬에 넣어 둔 것입니다.
### 사례 2. 이미지 문구 스킬: 한 번 겪은 실수를 맨 앞에
이미지 스킬은 맨 앞에 "가장 중요한 규칙"을 둡니다. 글자가 들어갈 자리보다 문구가 모자라면 모델이 앞 문구를 복사해서 채운다는 것입니다. 2026년 9월 5일 실측으로 만 18~34세가 말풍선과 체크 라벨에 두 번 나온 사례가 적혀 있습니다. 그래서 썸네일에는 문구 4개(헤드라인 둘, 말풍선, 체크 라벨)를 처음부터 주라는 표가 들어 있습니다.
다음에는 썸네일 큰 글씨를 "누가 / 뭘 얼마나" 두 줄로 쓰라는 규칙과, 나쁜 예·좋은 예 짝 표가 이어집니다. 250만원만 쓰면 누가 받는지 알 수 없으니 쉬었음 청년 / 250만원으로 쓰라는 식입니다. 빼도 되는 말(최대, 약, 이상, 까지)과 빼면 안 되는 말(대상, 숫자, 단위)도 나뉘어 있습니다.
두 사례의 공통점은 실수 → 숫자 또는 실제 사례 → 규칙 순서로 쓰여 있다는 점입니다. 공식 작성 안내가 권하는 방식과 같습니다. 안내는 평가 항목부터 만들고 클로드가 실제로 막히는 곳을 보고 최소한의 지시만 적으라고 하며, 상상한 요구사항을 문서로 쓰지 말라고 합니다.
설명 문장이 스킬을 부릅니다
스킬이 자동으로 불리느냐는 설명 문장에 달려 있습니다. 공식 자료에서 확인한 규칙을 정리합니다.
- 클로드는 설명(과 when_to_use)만 보고 이 스킬을 쓸지 정합니다. 둘을 합친 글자는 목록에서 1,536자에서 잘리니, 핵심 용도를 앞에 둡니다. API용 안내는 설명을 1,024자 이하로, 비어 있지 않게 쓰라고 합니다.
- 무엇을 하는지와 언제 쓰는지를 같이 적습니다. 안내의 좋은 예는 "PDF 파일에서 글자와 표를 뽑는다. PDF나 서식, 문서 추출을 말할 때 쓴다"처럼 두 가지를 모두 담습니다.
- 막연한 설명(문서를 돕는다, 데이터를 처리한다)은 피하라고 합니다. 100개가 넘는 스킬 중에서 고르는 기준이 되기 때문입니다.
- 설명은 시스템 안내문에 들어가므로 "내가 도와줄 수 있어요"가 아니라 3인칭("~한다")으로 쓰라고 합니다. 위 두 스킬의 설명도 "~할 때 쓴다", "~반드시 따른다"로 끝납니다.
설명이 길어질수록 좋은 것은 아닙니다. 이름과 설명 두 줄만 대화에 미리 올라와 있으니, 본문에 적을 내용을 설명에 몰아넣지 않는 편이 낫습니다.
안 불릴 때 확인표
| 증상 | 확인할 곳 | 근거 |
|---|---|---|
/이름으로도 안 보임 | SKILL.md의 첫 줄이 ---인지, 폴더 이름과 경로가 맞는지 | 첫 줄이 ---가 아니면 전체가 본문으로 처리됨 |
| 방금 만든 폴더인데 반영 안 됨 | 세션 시작 때 최상위 skills 폴더가 없었다면 /reload-skills | 새 최상위 폴더는 재탐색이 필요함 |
| 자동으로는 안 불리고 직접 부를 때만 됨 | 설명에 "언제 쓰는지"가 있는지, disable-model-invocation: true가 켜져 있지 않은지 | 켜져 있으면 클로드가 자동으로 못 불러 설명도 대화에 올라오지 않음 |
| 이름이 같은 스킬이 두 곳에 있음 | 개인과 프로젝트에 같은 이름이 있는지 | 같은 이름이면 개인이 프로젝트보다 우선 |
| 엉뚱한 때 자주 불림 | 설명이 너무 넓은지 | 설명이 선택 기준이므로 범위를 좁힘 |
| 설정 부분을 고쳤는데 달라지지 않음 | 파일 수정 감시는 SKILL.md 텍스트만 대상 | 플러그인의 훅 등은 별도 재로드가 필요함 |
만든 뒤 시험하는 방법
공식 문서가 안내하는 확인 방법은 두 가지입니다. 설명에 맞는 말을 해서 자동으로 불리는지 보고, /스킬이름으로 직접 불러 봅니다. 효과를 재려면 새 세션에서 스킬을 켠 채 한 번, 끈 채 한 번 같은 일을 시켜 비교하라고 합니다. 개인·프로젝트 스킬은 설정에서 skillOverrides를 "off"로 두면 끌 수 있습니다.
작성 안내는 여기에 한 가지를 더합니다. 스킬을 만들 때 쓰는 클로드와, 만든 스킬을 실제 일에 쓰는 새 클로드를 나눠서 보라는 것입니다. 새 클로드가 어디서 막히는지 보고, 그 내용을 들고 와서 스킬을 고치는 순환입니다. 처음부터 완벽하게 쓰려 하지 말고, 쓰면서 막힌 곳만 보태라는 이야기입니다.
첫 스킬을 오늘 만들어 보는 순서
1. 이번 주에 같은 지시를 두 번 이상 붙여 넣은 작업을 하나 적습니다.
2. 그 작업에서 "항상 틀리는 부분" 두세 가지를 적습니다. 이것이 본문의 핵심입니다.
3. 폴더 ~/.claude/skills/내작업-이름/을 만들고 SKILL.md를 씁니다. 설명에는 무엇을 하는지와 언제 쓰는지를 한 문장씩 넣습니다.
4. 클로드 코드에서 /내작업-이름으로 불러 보고, 결과가 틀린 곳을 본문에 한 줄씩 보탭니다.
5. 일주일 뒤 자동으로 불렸는지, 엉뚱할 때 불리지는 않았는지 확인하고 설명을 다듬습니다.
정리
스킬 만들기는 반복하는 작업 하나를 폴더와 SKILL.md로 옮기는 일이고, 성패는 본문 분량보다 설명 문장에서 갈립니다. 위치는 개인 ~/.claude/skills/가 기본이고, 이름은 소문자·숫자·하이픈, 설명은 "무엇을, 언제"를 앞에 둡니다. 제 스킬 두 개가 보여 주듯 처음부터 큰 체계를 만들 필요는 없습니다. 한 번 겪은 실수와 실제 숫자를 파일 하나에 적어 두고, 틀린 곳이 보이면 그때그때 고치면 됩니다.
이 글은 공식 문서를 기준으로 한 순서 정리이고, 제 스킬 사례는 스킬 파일에 적힌 내용만 옮긴 것입니다. 스킬을 어떤 과정으로 만들었는지, 자동 호출이 얼마나 잘 되는지는 기록이 없어 적지 않았습니다.
설정 항목과 동작은 클로드 코드 버전에 따라 바뀔 수 있으니 직접 만들기 전에 공식 문서를 한 번 열어 보세요. 앱에서 스킬을 켜는 방법은 클로드 스킬 설치방법, 켜기 전에 확인할 코드 실행 설정과 순서에 따로 정리해 두었습니다.