Claude Code의 커스텀 스킬(Skills) 만드는 법 — 「매번 하는 지시」를 재사용 가능한 부품으로 만들기

Claude Code를 사용하다 보면, 「또 이 지시를 입력해야 하나」라는 상황이 늘어나지 않나요?

• 매번 거의 동일한 절차를 그때마다 문장으로 설명하고 있다
• 리뷰 관점이나 절차를 기억해 내며 매번 작성하고 있다
• 같은 노하우를 다른 프로젝트에서도 사용하고 싶은데, 재사용하지 못하고 있다

이러한 「반복되는 지시」는 **커스텀 스킬(Skills)**로서 부품화할 수 있습니다. 한 번 만들어 두면 매번 처음부터 쓰지 않고 호출할 수 있습니다. 이 기사에서는 자작 스킬을 만드는 방법을 최소 구성부터 정리합니다.

주의: 스킬의 사양(SKILL.md의 프런트매터(Frontmatter) 항목, 위치 등)은 변경될 수 있습니다. 본 기사는 집필 시점(2026년 6월)의 공식 문서를 참조하고 있으나, 작성 시에는 가지고 계신 최신 문서를 확인해 주세요.

스킬은 SKILL.md라는 하나의 파일에 "언제 사용하는가 (description)"와 "무엇을 하는가 (지시 본문)"를 작성한 것입니다. Claude는 이 description을 보고, "지금 이 작업은 그 스킬을 사용할 상황이다"라고 판단하여 불러옵니다.

디렉터리 구조는 심플하며, 스킬 이름의 폴더 안에 SKILL.md를 두기만 하면 됩니다. 공식 문서의 예시입니다.

.claude/skills/processing-pdfs/
└── SKILL.md

폴더 이름(processing-pdfs)이 스킬의 이름이 됩니다.

SKILL.md는 두 부분으로 구성되어 있습니다.

• YAML 프런트매터 (YAML Frontmatter) (---로 감쌈): 언제 사용하는지를 나타내는 description
• 본문 (Markdown): 실제로 Claude가 따를 지시

공식 문서의 예시(변경 사항 요약 스킬)입니다.

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
...

여기서 중요한 점이 2가지 있습니다.

• description: "무엇을 하는가"뿐만 아니라 "언제 사용하는가 (Use when ...)"까지 작성한다. 이것이 스킬 자동 선택의 정밀도를 좌우합니다.
• `!git diff HEAD``: 백틱(Backtick)에 느낌표를 붙인 표기법으로, 커맨드(Command)의 실행 결과를 스킬에 포함할 수 있다. 위의 예시에서는 차이점(diff)을 가져온 뒤 요약하게 하고 있습니다.

공식 문서에는 description 이외에도 몇 가지 항목이 있습니다 (집필 시점 기준).

---
name: my-skill
description: What this skill does
...

항목	역할
name	스킬 이름
description	무엇을 하는가·언제 사용하는가
disable-model-invocation	Claude의 자동 선택을 무효화한다 (명시적 호출만 가능하게 함)
allowed-tools	해당 스킬 내에서 사용할 수 있는 툴(Tool)을 제한한다

allowed-tools를 좁히면, 예를 들어 "읽기만 가능하고 쓰기는 하지 못하게 하는" 리뷰 전용 스킬처럼, 안전한 범위 내에서 동작하는 스킬을 만들 수 있습니다.

실제로 하나 만드는 흐름은 다음과 같습니다.

스킬을 만드는 순서
├─ ① .claude/skills/<스킬명>/ 폴더를 만든다
├─ ② 그 안에 SKILL.md를 둔다
...

첫 번째 스킬은 자신이 가장 자주 반복하는 지시를 선택하는 것을 추천합니다. "커밋 메시지를 작성하게 하기", "차이점을 리뷰하게 하기" 등 빈도가 높을수록 효과를 실감할 수 있습니다.

스킬이 제대로 자동 선택되지 않는 원인의 대부분은 description이 모호하기 때문입니다. 요령은 "무엇을 하는가"에 더해 "어떤 때 사용하는가"를 구체적으로 적는 것입니다.

좋은 예:
"차이점을 리뷰하여 리스크를 지적한다.
사용자가 변경 사항을 확인하고 싶을 때, 커밋 메시지가 필요할 때,
...

"Use when ... (~할 때 사용)" 패턴으로 트리거가 되는 상황을 나열하면, 적절한 타이밍에 불러와지기 쉬워집니다.

스킬은 놓는 위치에 따라 적용 범위가 달라집니다.

위치	적용 범위
~/.claude/skills/	모든 프로젝트에서 사용 가능 (개인용)
프로젝트 내의 .claude/skills/	해당 프로젝트로 한정 (팀 공유 가능)

"어디서든 사용하는 범용 스킬"은 개인용으로, "이 프로젝트에 특화된 절차"는 프로젝트 내에 두는 방식으로 나누면 정리하기 쉽습니다. 프로젝트 내에 두고 리포지토리(Repository)에 포함하면 팀원들과 동일한 스킬을 공유할 수 있습니다.

• 스킬은 SKILL.md 파일 하나로 만들 수 있습니다 (프런트매터(Frontmatter)의 description + 본문)
• description에는 "무엇을 하는가"뿐만 아니라 "언제 사용하는가"를 적는 것이 핵심입니다.
• ! ... 표기법으로 명령(Command) 결과를 가져올 수 있으며, allowed-tools로 사용할 수 있는 도구(Tool)를 제한할 수 있습니다.
• 위치(개인용 / 프로젝트용)에 따라 적용 범위를 구분하여 사용할 수 있습니다.

우선 본인이 가장 자주 반복하는 지시 사항을 하나만 스킬로 만들어 보세요. description을 정성스럽게 작성하는 것만으로도, 매번 입력하던 지시 사항이 "필요할 때 자동으로 호출되는 부품"으로 변합니다.

스킬을 작성할 때는 잘 만들어진 실례가 있으면 형태를 파악하기 쉽습니다. 제가 실제로 사용하고 있는 스킬을 무료로 공개하고 있습니다.

무료 스타터 (GitHub · CC BY 4.0):

CLAUDE.md 설계 · 계획 우선 개발 (PIV) · AI 커밋 전략 · 애자일(Agile) 프롬프트 설계의 4가지 스킬이 일본어와 영어로 포함되어 있습니다. 스킬 작성법의 실례로서 내용을 읽어보고, 자신만의 스킬을 만드는 데 참고할 수 있습니다. 우선 무료 리포지토리부터 시도해 보세요.

최신 팁은 X에서도 발신하고 있습니다: @k___n___t_1125