SKILL.md 작성법 — Claude Code를 나만의 전문가로 만드는 방법

Claude Code 입문

Claude Code를 쓰다 보면 매번 같은 지시를 반복하는 순간이 옵니다. "마크다운으로 정리해줘", "테스트 코드도 함께 작성해줘" 같은 요청을 매번 타이핑하는 건 비효율적이에요. 이 문제를 해결하는 기능이 바로 스킬(Skill)입니다. 한 번 만들어두면 슬래시 명령어 한 줄로 언제든 전문가 수준의 결과물을 뽑아낼 수 있어요.

📌 3줄 요약

• 스킬은 .claude/skills/ 폴더에 SKILL.md를 만들어 Claude Code에 전문 능력을 추가하는 기능이다.
• 실행 조건·단계·references 폴더를 구성하면, 슬래시 명령어 하나로 일관된 결과물을 만들 수 있다.
• .claude/ 폴더를 Git에 커밋하면 팀 전체가 동일한 기준으로 작업할 수 있다.

📑 목차

• 1. Skill이란 — Claude Code에 전문 능력을 추가하는 방법
• 2. SKILL.md 파일 구조와 작성 규칙
• 3. 스킬 호출과 references 폴더 활용법
• 4. 실전 예시 — 코드 리뷰 스킬 만들기

Skill이란 — Claude Code에 전문 능력을 추가하는 방법

Claude Code를 쓰다 보면 매번 같은 지시를 반복하는 순간이 옵니다. "마크다운으로 정리해줘", "테스트 코드도 함께 작성해줘" 같은 요청을 매번 타이핑하는 건 비효율적이에요. 특히 팀 프로젝트에서 여러 사람이 각자 다른 방식으로 지시를 내리면, 결과물의 품질이 들쭉날쭉해지는 문제도 생깁니다.

이 문제를 해결하는 기능이 바로 스킬(Skill)이에요. 스킬은 .claude/skills/ 폴더 안에 SKILL.md 파일을 만들어서, Claude Code에 특정 분야의 전문 지식을 미리 심어두는 기능입니다. 한 번 만들어두면 슬래시 명령어 한 줄로 언제든 불러올 수 있어서, 매번 긴 프롬프트를 작성할 필요가 없어요. Claude Code가 SKILL.md를 읽는 순간 해당 분야의 전문가처럼 동작하기 때문에, 응답의 일관성도 크게 올라갑니다.

🔍 CLAUDE.md vs SKILL.md
CLAUDE.md가 프로젝트 전반의 규칙을 정하는 파일이라면, SKILL.md는 특정 작업에 특화된 지시서라고 보면 돼요. 예를 들어 "블로그 글 작성 스킬", "코드 리뷰 스킬", "API 문서 생성 스킬"처럼 용도별로 나눌 수 있습니다. CLAUDE.md에 모든 규칙을 한꺼번에 넣으면 파일이 길어져서 Claude Code가 핵심을 놓칠 수 있는데, 스킬로 분리하면 필요한 규칙만 정확히 로드돼요.

💬 제가 직접 써보니, CLAUDE.md 하나에 모든 규칙을 넣었을 때보다 스킬을 분리한 뒤 응답 품질이 눈에 띄게 좋아졌어요. 특히 글쓰기처럼 세부 규칙이 많은 작업에서 효과가 컸습니다. 다만 스킬을 너무 많이 만들면 어떤 스킬이 어떤 역할인지 관리가 어려워지니, 처음에는 2~3개로 시작하는 것을 추천드려요.

 

SKILL.md 파일 구조와 작성 규칙

스킬 파일의 위치는 .claude/skills/스킬이름/SKILL.md 경로예요. 폴더 이름이 곧 스킬 이름이 되므로, 영문 소문자와 하이픈(-)으로 짧게 짓는 것이 좋습니다. 예를 들어 blog-writer, code-review, api-docs처럼 역할이 한눈에 보이는 이름이 이상적이에요.

⚠️ 폴더 이름에 공백이나 한글을 넣으면 경로 인식에서 문제가 생길 수 있으니 반드시 영문으로 작성해 주세요.

SKILL.md 안에는 크게 세 가지를 적어요.

1

이 스킬이 언제 활성화되는지 실행 조건을 명시합니다. 슬래시 명령어로 호출할 때만 활성화할 수도 있고, 특정 키워드가 포함된 요청에 자동 반응하도록 설정할 수도 있어요.

2

Claude Code가 수행해야 할 구체적인 단계를 순서대로 나열합니다.

3

참조할 파일이 있다면 references/ 폴더에 넣고 경로를 안내해요.

 

실제 파일 예시를 보겠습니다. 아래처럼 작성하면 /blog-writer라는 슬래시 명령어로 스킬을 호출할 수 있어요.

# blog-writer 스킬

## 설명
블로그 초안을 작성하는 스킬입니다.

## 실행 조건
사용자가 /blog-writer를 호출하거나 블로그 글 작성을 요청할 때 활성화됩니다.

## 단계
1. references/writing_rules.md를 읽고 규칙을 파악합니다.
2. 주제에 맞는 소제목 4개를 설계합니다.
3. 각 소제목별 본문을 작성합니다.
4. output/ 폴더에 마크다운 파일로 저장합니다.

💬 제가 직접 여러 스킬을 만들어 보니, "단계" 부분이 핵심이었어요. 단계를 모호하게 쓰면 Claude Code가 자의적으로 해석하므로, 가능한 한 구체적인 동작으로 기술하는 것이 중요합니다.

💡 "적절히 작성합니다" 대신 "references/writing_rules.md의 규칙을 따라 3000자 이상으로 작성합니다"처럼 수치와 조건을 명시하는 게 좋아요. 이렇게 구체적으로 적으면 스킬을 호출할 때마다 동일한 품질의 결과물을 기대할 수 있습니다.

스킬 호출과 references 폴더 활용법

스킬을 만들었으면 호출해봐야 해요. Claude Code 터미널에서 /스킬이름을 입력하면 해당 SKILL.md가 자동으로 로드됩니다. 별도의 설정이나 등록 과정 없이, 파일만 올바른 경로에 있으면 바로 인식돼요.

예를 들어 /blog-writer를 입력하면, Claude Code가 SKILL.md의 단계를 순서대로 실행합니다. 이때 references 폴더에 넣어둔 파일도 함께 참조해요. 스킬이 활성화되면 Claude Code가 먼저 SKILL.md를 읽고, 그 안에 언급된 references 파일들을 순서대로 확인하는 과정을 거칩니다. 이 과정이 자동으로 이루어지기 때문에, 사용자는 슬래시 명령어 하나만 입력하면 되는 거예요.

 

references 폴더에는 규칙 문서, 템플릿, 예시 파일 등을 넣을 수 있어요. 규칙 문서에는 글쓰기 톤앤매너, 코딩 컨벤션 같은 기준을 적고, 템플릿에는 결과물의 뼈대를 미리 만들어 둡니다. 예시 파일은 Claude Code에게 "이런 수준의 결과물을 만들어줘"라고 알려주는 역할을 해요. 폴더 구조는 다음과 같습니다.

.claude/skills/blog-writer/
├── SKILL.md
└── references/
    ├── writing_rules.md
    ├── title_rules.md
    └── template.md

스킬이 제대로 동작하지 않는 경우, 대부분 두 가지 원인이에요. SKILL.md의 경로가 틀렸거나, references 파일 경로를 SKILL.md 안에서 잘못 참조한 경우입니다.

💬 경로 문제로 헤맨 경험이 있는데, SKILL.md 안에서 references를 참조할 때는 references/파일명.md처럼 상대 경로를 쓰는 것이 안전해요. 절대 경로를 쓰면 다른 환경에서 깨질 수 있으니 주의가 필요합니다. 경로가 맞는데도 동작하지 않는다면, 파일 이름에 대문자나 특수문자가 섞여 있지 않은지도 확인해 보세요.

실전 예시 — 코드 리뷰 스킬 만들기

실제로 자주 쓰이는 코드 리뷰 스킬을 만들어 보겠습니다. .claude/skills/code-review/SKILL.md 파일을 생성해요. 코드 리뷰는 점검 항목이 명확하기 때문에 스킬로 만들기에 특히 적합한 작업이에요. 사람마다 리뷰 기준이 다른 문제도 스킬 하나로 통일할 수 있습니다.

# code-review 스킬

## 설명
변경된 코드를 검토하고 개선점을 제안하는 스킬입니다.

## 실행 조건
사용자가 /code-review를 호출할 때 활성화됩니다.

## 단계
1. git diff로 변경된 파일 목록을 확인합니다.
2. 각 파일의 변경 내용을 읽습니다.
3. references/review_checklist.md 기준으로 검토합니다.
4. 파일별로 문제점과 개선 제안을 정리합니다.
5. 심각도(높음/중간/낮음)를 표기합니다.

이 스킬에 맞는 체크리스트 파일도 함께 만들어야 해요. references/review_checklist.md에 보안 취약점, 에러 처리 누락, 네이밍 규칙 위반 등 점검 항목을 나열하면 됩니다. 체크리스트를 잘 만들어두면 주니어 개발자도 시니어 수준의 리뷰 기준을 적용할 수 있어요.

💡 항목이 너무 많으면 리뷰 시간이 길어지니, 팀에서 가장 자주 발생하는 실수 위주로 10~15개 정도가 적당합니다.

 

스킬의 진짜 가치는 팀원 모두가 동일한 기준으로 작업할 수 있다는 점이에요. .claude/ 폴더를 Git에 커밋하면, 레포지토리를 클론한 누구나 같은 스킬을 사용할 수 있습니다. 새로 합류한 팀원이 프로젝트의 코딩 컨벤션을 모르더라도, 스킬을 실행하면 자동으로 기준에 맞춰 작업할 수 있어요. 이렇게 스킬을 코드와 함께 버전 관리하면, 규칙이 바뀔 때도 한 곳만 수정하면 전체 팀에 반영됩니다.

💬 제가 직접 코드 리뷰 스킬을 운영해보니, 사람이 놓치기 쉬운 네이밍 불일치나 미사용 import를 잡아주는 데 특히 유용했어요. 반면 비즈니스 로직의 타당성 판단은 스킬만으로 어렵기 때문에, 자동 검토와 사람의 최종 확인을 병행하는 것이 좋습니다. 스킬이 잡아준 기계적 오류를 먼저 수정하고, 사람은 설계와 로직에 집중하는 방식으로 역할을 나누면 리뷰 효율이 크게 올라가요.

✍️ 마치며

스킬은 한번 만들어두면 반복 지시 없이 일관된 결과물을 만들어주는 강력한 도구예요. CLAUDE.md가 프로젝트의 헌법이라면, SKILL.md는 각 부서의 업무 매뉴얼이라고 생각하면 됩니다. 지금 바로 .claude/skills/ 폴더를 만들고, 가장 자주 반복하는 작업 하나를 스킬로 만들어 보세요. 한 번 경험하면 "왜 진작 안 만들었지?" 싶을 만큼 편리함을 느끼실 거예요.