Claude Code 커스텀 스킬 만드는 법 (실제로 작동하는 예제와 함께)

이 글은 Claude Code CLI를 기준으로 해요. 스킬은 빠르게 발전하는 기능이라 일부 세부 사항은 바뀔 수 있고, 출처는 끝에 밝혀 둘게요.

Claude Code의 커스텀 스킬이란? (간단한 정의)

커스텀 스킬은 지침을 묶은 패키지, 즉 폴더와 SKILL.md 파일로, 반복되는 워크플로를 원하는 방식 그대로 Claude Code가 수행하도록 가르치는 거예요. "이 블로그 글을 표준 X로 포맷하고, 목차를 넣고, 메타를 써 줘…" 같은 긴 프롬프트를 매번 다시 입력하는 대신, 그 레시피를 한 번만 스킬로 패키징해요. 그다음부터 Claude Code는 언제 써야 할지 알아차리고 당신의 단계를 따라요.

초보자는 스킬을 다른 두 가지와 자주 헷갈리니, 빠르게 구분해 둘게요.

• 스킬 - 컨텍스트가 당신의 description과 일치할 때 Claude Code가 자동으로 호출하는 지식이나 워크플로예요. 명령어는 전혀 입력하지 않아요.
• 슬래시 명령어 - 당신이 일부러 입력하는 단축키예요(예: /commit). 자세한 내용은 Claude Code의 슬래시 명령어를 보세요.
• 서브에이전트 - 무거운 작업을 자기만의 별도 컨텍스트에서 실행하는 "보조 어시스턴트"예요. 서브에이전트 가이드를 보세요.

네 가지 개념이 여전히 뒤섞여 헷갈린다면, skills vs subagents vs hooks vs MCP 글에서 더 꼼꼼하게 정리해 두었어요. 그리고 스킬이 근본적으로 무엇인지 아직 명확하지 않다면, 먼저 Claude Code 스킬이 무엇인지를 읽고, 그다음 여기로 돌아와 실제로 하나 만들어 보세요. 이 글은 Claude Code CLI에서 실제로 스킬을 동작시키는 것에만 100% 집중해요.

스킬은 어떻게 동작하나요? (프로그레시브 디스클로저)

이 원리를 이해하면 처음부터 스킬을 제대로 쓸 수 있어요. Claude Code는 모든 스킬의 전체 내용을 컨텍스트에 밀어 넣지 않아요. 그러면 토큰을 낭비하고 노이즈가 늘어나니까요. 대신 프로그레시브 디스클로저(필요할 때 로드)를 세 개의 계층에 걸쳐 사용해요.

• 1계층 - 항상 상주: Claude Code는 각 스킬의 name과 description만 컨텍스트에 유지해요. 어떤 스킬이 있고 무엇을 위한 것인지 알려 주는 "이정표"예요.
• 2계층 - 일치할 때 로드: 대화 컨텍스트가 description과 일치할 때에만 SKILL.md의 본문이 컨텍스트로 읽혀요.
• 3계층 - 필요할 때 로드: reference.md나 scripts/ 같은 보조 파일은 Claude가 실제로 필요로 할 때에만 열려요.

가장 중요한 결론은 이거예요. description이 바로 자동 호출 스위치예요. description에 사용자가 실제로 말할 컨텍스트 키워드가 없으면, 본문을 아무리 잘 써 두어도 Claude Code는 스킬 본문을 열어 읽는 일이 결코 없어요. "실행이 안 되는" 스킬 대부분이 내용이 아니라 description 줄에서 실패하는 이유가 이거예요.

설정: 스킬이 사는 곳 (개인용 vs 프로젝트용)

여기가 대부분의 영어 튜토리얼이 건너뛰는 부분이에요. 그들은 claude.ai 웹 앱 이야기를 하니까요. Claude Code CLI에서는 스킬이 파일 시스템에 존재하고, 목적에 따라 둘 곳이 두 군데 있어요.

간단한 규칙은 이래요. 나 자신의 워크플로는 ~/.claude/skills/에, 팀이나 프로젝트 전체의 규약은 저장소 안 .claude/skills/에 둔 다음 git에 커밋해 모두가 받도록 해요.

유일한 전제 조건은 Claude Code가 설치되어 있어야 한다는 것뿐이에요(아직이라면 Claude Code 설치 가이드를 보세요). 기존 스킬은 Claude Code 세션에서 직접 물어보거나(예: "지금 가진 스킬을 나열해 줘" 프롬프트) ~/.claude/skills/ 폴더를 열어 확인할 수 있어요. 새 스킬을 만든 뒤에는 스캔되도록 재시작하는 걸 잊지 마세요.

커스텀 Claude Code 스킬을 5단계로 만드는 방법

전체 워크플로예요. 처음부터 끝까지 하나의 예시, 즉 가공되지 않은 Markdown 블로그 글을 정리하는 blog-formatter 스킬을 쓸 거라 그리기 쉬울 거예요. 다만 이 접근법은 어떤 워크플로에도 적용돼요.

1단계 - 반복 가능한 워크플로를 하나 고르기

손으로 한 번도 안 해 본 것을 위해 스킬을 쓰려고 서두르지 마세요. 실용적인 팁: 먼저 Claude Code와 손으로 몇 번 해 보고, 원하는 결과가 정확히 나오게 된 다음에야 그 프롬프트/워크플로를 스킬로 결정화하세요. 좋은 스킬은 검증된 과정의 결정체이지 추측이 아니에요.

시작하기 좋은 후보 몇 가지예요. 블로그 글을 내 표준으로 포맷하기, 프로젝트 규약에 맞춘 커밋 메시지 생성하기, 기존 템플릿으로 유닛 테스트 작성하기, API 문서 리뷰하기 등이에요. 적어도 일주일에 한 번은 하는 일을 고르세요. 거기서 ROI가 드러나요.

2단계 - 폴더 트리 + SKILL.md 파일 만들기

최소한의 스킬에는 폴더와 SKILL.md 파일 하나면 충분해요. 보조 파일은 필요할 때 추가해요. 전체 폴더 트리는 이렇게 생겼어요.

~/.claude/skills/
 blog-formatter/
 SKILL.md # required - the main instructions
 reference.md # optional - long details, loaded on demand
 scripts/
 format.py # optional - a bundled script

터미널에서 폴더를 만들어요.

mkdir -p ~/.claude/skills/blog-formatter
cd ~/.claude/skills/blog-formatter

폴더 이름은 스킬이 무엇을 하는지 짧고 명확하게 나타내는 kebab-case로 지어요(blog-formatter, commit-msg). 작은 스킬이라면 SKILL.md 하나로 충분해요. 본문이 길어지기 시작할 때에만 reference.md나 scripts/로 분리하세요.

3단계 - YAML 프런트매터 작성하기 (name + description)

SKILL.md를 열어요. 맨 위에 두 개의 --- 줄 사이에 YAML 프런트매터 블록이 있고, 필수 필드 두 개 name과 description이 들어가요. 여기가 스킬이 자동 호출될지 아닐지를 결정하는 부분이니 신중히 쓰세요.

좋은 description의 공식: 무엇을 하는지 + 언제 쓰는지 + 트리거 키워드로, 사용자가 실제로 입 밖으로 말할 단어를 넣어요. 비교해 볼게요.

왼쪽은 모호하고 컨텍스트가 없어서 Claude는 언제 불러야 할지 전혀 몰라요. 오른쪽은 무엇을, 언제, 그리고 사용자가 입력하기 쉬운 정확한 표현까지 짚어 줘요. description은 새 동료에게 "이럴 때 저한테 오세요"라고 말해 준다는 마음으로 쓰세요.

4단계 - 지침 본문 작성하기

프런트매터 바로 아래가 Markdown 본문으로, 스킬이 호출될 때 Claude Code가 읽고 따르는 워크플로예요. 좋은 본문에는 다음을 담으면 좋아요.

• 목적 - 이 스킬이 어떤 문제를 푸는지.
• 언제 쓰는지 - 컨텍스트를 다시 말하기(description을 보강해요).
• 물어봐야 할 입력 - 정보가 없을 때 사용자에게 무엇을 물을지.
• 단계 - 명확하고 번호가 매겨진 절차.
• 출력 기준 - 올바른 결과가 어떤 모습인지.
• 피해야 할 실수 + 입력/출력 예시.

황금률: 간결함이 핵심이에요. 부풀려진 본문은 컨텍스트를 낭비하고 Claude의 주의를 흐트러뜨려요. 지침이 길어지면(조회 표, 많은 예시) reference.md로 분리하고 본문에서 그것을 가리키세요. 프로그레시브 디스클로저 덕분에 보조 파일은 필요할 때만 로드돼요.

5단계 - 스킬 다시 로드 & 테스트하기

Claude Code는 시작할 때 스킬 폴더를 스캔하므로, SKILL.md를 만들거나 편집한 뒤에는 재시작이 필요해요. /exit를 입력하고 Claude Code 세션을 다시 열어요. 그런 다음 description에 맞는 자연스러운 프롬프트로 테스트해요. 예를 들면 "draft.md의 블로그 글을 포맷해 줘."처럼요. 잘 썼다면 Claude Code가 그것을 알아차리고 blog-formatter 스킬을 호출해요. 올바른 스킬이 쓰였는지 확인하고(어떤 스킬이 호출됐는지 Claude가 대개 알려 줘요), 그다음 결과가 4단계에서 정한 기준을 충족하는지 확인하세요.

완전한 커스텀 스킬 예시 (복붙해서 실행)

제가 실제로 쓰고 사용해 온 완전한 SKILL.md예요. 그대로 ~/.claude/skills/commit-msg/SKILL.md에 복사하고, 재시작한 뒤, 바로 시도해 보세요.

---
name: commit-msg
description: Generate a Conventional Commits message from the currently staged changes. Use when the user says "write a commit", "commit message", "make a commit message", or right before committing code.
---

# Generate a Conventional Commits message

## Purpose
Read the staged diff and write a short, standards-compliant commit message.

## When to use
When the user is about to commit or asks for a commit message.

## Inputs to ask for
If nothing is staged, run `git diff --staged` to see the changes.
If it's still empty, ask the user: "Have you run `git add` yet?"

## Steps
1. Run `git diff --staged` to read the changes.
2. Determine the type: feat / fix / docs / refactor / test / chore.
3. Determine the scope (the main module/folder changed).
4. Write the subject line: `type(scope): short description` - max 72 chars, present tense.
5. If the change is complex, add 1-3 bullet points in the body explaining "why".

## Output standard
- Subject ≤ 72 chars, no trailing period.
- Description is clear and matches what was actually done.
- Do NOT invent changes that aren't in the diff.

## Mistakes to avoid
- Don't use the wrong type (adding a feature but labeling it `fix`).
- Don't write vague messages like "update code", "misc fixes".

## Example
Input diff: add an email validation function in `src/auth/`.
Output:
feat(auth): add email format validation on signup

실제 결과: 일단 로드되면, 그냥 "write a commit"이라고 입력하기만 하면 Claude Code가 git diff --staged를 실행하고, 올바르게 분류하고, 규약을 지킨 메시지를 돌려줘요. 매번 규약을 다시 말할 필요가 없어요.

관찰된 한계 하나(솔직히): 차이(diff)가 거대하거나 여러 종류의 변경이 섞여 있으면, 합쳐진 메시지가 가장 알맞지는 않은 type을 고를 때가 있어요. 그럴 때는 역시 커밋을 나누거나 직접 손봐야 해요. 이 스킬은 90%의 경우를 잡아 주지만, 당신의 판단을 통째로 대신하지는 않아요.

스킬이 발동하지 않을 때 테스트 & 디버그

완성된 스킬을 Claude Code가 "무시하는" 일은 아주 흔해요. 스킬이 발동을 거부할 때 제가 순서대로 훑는 체크리스트예요.

1. YAML 구문 오류. --- 누락, 잘못된 들여쓰기, 프런트매터의 엉뚱한 문자 하나면 스킬 전체가 조용히 건너뛰어져요. 프런트매터 블록부터 확인하세요.
2. 모호한 description / 컨텍스트 키워드 누락. 이게 1순위 원인이에요. 프롬프트에 description과 겹치는 표현이 하나도 없으면 스킬은 호출되지 않아요. 실제 사용자가 말할 정확한 단어를 넣으세요.
3. Claude Code를 재시작하지 않음. 스킬 폴더는 시작할 때만 스캔돼요. 편집한 뒤에는 /exit하고 다시 열어야 해요.
4. 이름 중복 또는 잘못된 경로. name이 같은 스킬이 둘 있거나, SKILL.md가 잘못된 폴더에 있으면(대소문자 불일치, 잘못된 계층) 로드되지 않아요.
5. 본문이 너무 길어 노이즈가 됨. 부풀려진 본문은 Claude가 절차를 따르기 어렵게 만들어요. 다듬고, 넘치는 부분은 reference.md로 옮기세요.

빠른 진단 팁: 수동 호출을 강제해서 문제를 분리하세요. 직접 이렇게 프롬프트해요. "blog-formatter 스킬을 써서 이걸 해 줘." 강제 호출이 잘 되면 버그는 description에 있어요(자동 호출이 안 되는 거죠). 강제 호출도 실패하면 버그는 YAML이나 경로에 있어요.

스킬 공유 & 배포하기

좋은 스킬을 썼다면 공유해야 해요. 그리고 이건 영어 튜토리얼이 거의 다루지 않는 부분이에요. 간단한 것부터 좀 더 다듬어진 것까지 세 가지 방법이 있어요.

1. 팀 전체를 위해 저장소에 커밋하기. 스킬을 프로젝트 안 .claude/skills/에 두고 git commit하세요. 저장소를 클론한 사람은 누구나 곧바로 그 스킬을 얻어요. 팀에서 프로세스를 표준화하는 가장 빠른 방법이에요.
2. 커뮤니티를 위해 GitHub에 푸시하기. 스킬 저장소를 만들면 다른 사람이 그것을 클론하거나 스킬 폴더를 자기 ~/.claude/skills/로 복사할 수 있어요. 각 스킬이 무엇을 하는지 설명하는 README를 넣으세요.
3. 플러그인으로 패키징하기. 관련 스킬이 여러 개라면 하나의 플러그인으로 묶어 배포를 더 깔끔하게 할 수 있어요(Claude Code 플러그인에 관한 별도의 글이 있어요).

보너스: 스킬은 열린 표준(Markdown + YAML 프런트매터)을 쓰기 때문에, Claude Code용으로 쓴 SKILL.md는 Cursor나 Copilot 같은 다른 도구에서도 그대로 재사용하거나 쉽게 변환할 수 있는 경우가 많아요. 한 번 쓰면 여러 곳에서 쓰는 거죠.

직접 쓰기 싫다고요? 108개 이상의 기성 스킬을 쓰세요

직접 스킬을 쓰는 것 자체가 배울 가치가 있는 능력이에요. 당신의 정확한 워크플로에 맞게 다듬을 완전한 통제권을 주니까요. Claude Code를 진지하게 쓰는 모든 분께 권해요. 하지만 하나하나 직접 만들지 않고 지금 당장 실전에서 쓸 수 있는 스킬 세트가 필요하다면, Engineer Kit은 60개 이상의 기성 스킬을 제공해요(프런트엔드, 백엔드, 데이터베이스, DevOps, 코드 리뷰). 고려할 만한 지름길이에요.

지름길을 택하세요: AgentKit 기성 스킬 번들 — 현재 $149(기존 $198)은 Claude Code용 108개 이상의 스킬을 묶어, 파일을 하나하나 쓰는 대신 바로 쓸 수 있어요. 솔직히 말하면: 전문적인 부분을 커스터마이즈하려면 (이 글에서처럼) 스킬 작성법은 역시 알아 두어야 해요. 키트는 반복적인 밑작업을 맡아 줘요.

자주 묻는 질문 (FAQ)

스킬은 서브에이전트와 어떻게 다른가요?

스킬은 컨텍스트가 일치할 때 Claude Code가 현재 컨텍스트로 불러오는 지침 패키지로, 같은 세션 안에서 동작해요. 서브에이전트는 무거운 작업을 자기만의 별도 컨텍스트에서 독립적으로 실행하는 보조 어시스턴트예요. 가볍고 반복되는 일은 스킬로, 격리가 필요한 큰 일은 서브에이전트로 보내요.

SKILL.md는 어디에 두나요?

모든 프로젝트에서 쓰고 싶으면(개인용) ~/.claude/skills/<name>/SKILL.md에, 커밋해서 팀과 공유하고 싶으면(프로젝트용) 저장소 안 .claude/skills/<name>/SKILL.md에 두세요. 각 스킬은 SKILL.md 파일을 담은 자기만의 폴더예요.

왜 제 스킬이 자동으로 실행되지 않나요?

대개 description이 모호하고, 프롬프트에서 실제로 말하는 키워드가 빠져서예요. 아울러 확인하세요. YAML 프런트매터에 구문 오류가 없는지, Claude Code를 재시작했는지, 폴더 경로가 올바른지.

스킬을 만들거나 편집한 뒤 재시작이 필요한가요?

네. Claude Code는 스킬 폴더를 시작할 때만 스캔하므로, SKILL.md를 만들거나 편집한 뒤에는 스킬이 로드되도록 /exit하고 세션을 다시 열어야 해요.

Claude Code용으로 쓴 스킬을 claude.ai에서도 쓸 수 있나요?

스킬 표준(Markdown + YAML 프런트매터)은 열려 있어서 내용은 대개 재사용할 수 있어요. 다만 로드 방식은 달라요. Claude Code는 로컬 파일 폴더(~/.claude/skills/)를 쓰지만, claude.ai 웹 앱은 나름의 방식으로 로드해요. SKILL.md 파일을 재사용 가능한 자산으로 여기세요. 어디서나 그대로 똑같이 꽂아 쓰는 것은 아니에요.

바로 쓸 수 있는 기성 스킬이 있나요?

있어요. 맨바닥에서 시작하기 싫다면 AgentKit 같은 키트가 여러 영역에 걸쳐 Claude Code용 108개 이상의 스킬을 묶어 줘요. 커스터마이즈를 위해 직접 쓰는 법은 알아 두어야 하지만, 키트는 반복적인 밑작업을 덜어 줘요.

결론 + 다음 단계

커스텀 스킬은 프롬프트를 반복하지 않고도 당신의 정확한 기준으로 동작하도록 Claude Code를 "가르치는" 가장 효과적인 방법이에요. 작게 시작하세요. 매주 하는 워크플로 하나를 골라 SKILL.md로 결정화하고, 정말 명확한 description을 쓰고, 테스트하고, 반복하세요. 기초를 확실히 다지려면 다음으로 Claude Code 스킬이 무엇인지를 읽고, 의도적인 단축키와 스킬을 짝지으려면 Claude Code의 슬래시 명령어를 읽어 보세요. 그리고 하나하나 쓰는 대신 지금 당장 실전용 스킬 세트가 필요하다면, 기성 키트를 고려해 보세요(아래 상자 참고).

출처: Claude Code Docs - Skills(Anthropic, 2026 업데이트), SKILL.md 구조와 로딩 원리에 관해. 스킬은 발전 중인 기능이라 버전 간에 세부가 바뀔 수 있어요.