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
...

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

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

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

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

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

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

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

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

"어디서든 사용하는 범용 스킬"은 개인용으로, "이 프로젝트에 특화된 절차"는 프로젝트 내에 두는 방식으로 나누면 정리하기 쉽습니다. 프로젝트 내에 두고 리포지토리(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