Claude Code — 첫 번째 Skills 만들기

🛠️ Claude Code — 첫 번째 Skills 만들기

SKILL.md 작성부터 매칭 원리, 우선순위까지

📌 이 글의 핵심 요약

• Skills는 디렉토리 + SKILL.md 파일 하나로 만들 수 있습니다.
• Claude는 시작 시 이름과 설명만 로드하고, 요청과 매칭될 때만 전체 내용을 불러옵니다.
• 이름이 충돌할 경우 Enterprise → Personal → Project → Plugins 순으로 우선순위가 결정됩니다.
• 변경사항은 항상 Claude Code 재시작 후 반영됩니다.

1. 스킬의 구조

스킬은 단순합니다. 디렉토리 하나와 그 안의 SKILL.md 파일이 전부입니다. 디렉토리 이름이 곧 스킬 이름이 됩니다.

~/.claude/skills/
└── pr-description/ ← 스킬 이름 = 디렉토리 이름
    └── SKILL.md ← 지시 파일

SKILL.md 파일은 frontmatter와 본문, 두 부분으로 구성됩니다.

구성 요소	위치	역할
name	frontmatter	스킬의 고유 식별자
description	frontmatter	Claude가 언제 이 스킬을 쓸지 판단하는 기준 (핵심!)
본문	두 번째 --- 아래	스킬 활성화 시 Claude가 실제로 따르는 지시 내용

---

2. 첫 번째 스킬 직접 만들기

PR 설명을 일관된 형식으로 작성해주는 개인 스킬을 만들어 보겠습니다. 개인 스킬은 홈 디렉토리에 저장되므로 모든 프로젝트에서 사용할 수 있습니다.

1

스킬 디렉토리 생성

디렉토리 이름이 스킬 이름이 됩니다. -p 옵션으로 상위 폴더도 함께 생성합니다.

2

SKILL.md 파일 작성

frontmatter에 name과 description을 작성하고, 그 아래에 실제 지시 내용을 마크다운으로 작성합니다.

3

Claude Code 재시작

스킬은 시작 시 로드되므로, 새로 만든 스킬을 인식시키려면 세션을 재시작해야 합니다.

Step 1 — 디렉토리 생성

Terminal

# 스킬 디렉토리 생성 (-p: 상위 디렉토리도 함께 생성)
mkdir -p ~/.claude/skills/pr-description

Step 2 — SKILL.md 작성

~/.claude/skills/pr-description/SKILL.md

---
name: pr-description
description: Writes pull request descriptions.
             Use when creating a PR, writing a PR,
             or when the user asks to summarize
             changes for a pull request.
---

PR 작성 시 아래 순서로 진행하세요:

1. `git diff main...HEAD` 실행하여 변경 사항 확인

2. 아래 형식으로 작성:

## What
한 문장으로 이 PR이 무엇을 하는지 설명

## Why
왜 이 변경이 필요한지 간단한 배경

## Changes
- 구체적인 변경 사항을 불릿 포인트로
- 관련 변경은 그룹으로 묶기
- 삭제되거나 이름이 바뀐 파일 언급

description은 Claude가 스킬을 사용할 타이밍을 결정하는 핵심입니다. "Use when..." 패턴으로 작성하면 매칭 정확도가 높아집니다.

---

3. 스킬 매칭이 작동하는 원리

Claude Code는 시작 시 스킬 폴더를 스캔하지만, 처음에는 이름(name)과 설명(description)만 메모리에 올립니다. 전체 지시 내용은 아직 로드하지 않습니다. 덕분에 스킬이 많아도 컨텍스트 윈도우를 낭비하지 않습니다.

사용자가 요청을 입력하면 Claude는 의미 기반(Semantic Matching)으로 description과 비교합니다. 정확히 같은 단어가 아니어도 의미가 겹치면 매칭됩니다.

사용자 요청 "이번 브랜치 PR 설명 작성해줘" →

pr-description Use when creating a PR, writing a PR... ✓ 매칭

code-review Use when reviewing PRs for quality... ✗ 미매칭

commit-msg Use when writing a commit message... ✗ 미매칭

결과 pr-description 스킬 전체 내용 로드 여부 확인 프롬프트 표시

매칭이 발생하면 Claude는 스킬 전체 내용을 로드할지 사용자에게 확인합니다. 이 단계를 통해 어떤 컨텍스트가 추가되는지 항상 인지할 수 있습니다.

⚡

시작 시 로드

name + description만 로드.
컨텍스트 윈도우 절약.

🎯

의미 기반 매칭

정확한 단어 일치 불필요.
요청 의도로 스킬 탐색.

🔔

확인 프롬프트

전체 내용 로드 전
사용자에게 알림.

📋

지시 실행

확인 후 SKILL.md 전체를
읽고 작업 수행.

---

4. 스킬 우선순위 (이름 충돌 시)

저장소를 클론했을 때 팀의 프로젝트 스킬과 내 개인 스킬의 이름이 겹친다면 어떻게 될까요? 명확한 우선순위 규칙이 있습니다.

1순위

Enterprise — 조직 관리자가 설정한 스킬. 항상 최우선 적용됩니다.

2순위

Personal — ~/.claude/skills 의 개인 스킬. Enterprise 다음으로 적용됩니다.

3순위

Project — 저장소 내 .claude/skills 의 팀 공유 스킬.

4순위

Plugins — 설치된 플러그인 스킬. 가장 낮은 우선순위.

회사에 code-review Enterprise 스킬이 있다면, 개인이 같은 이름으로 만든 스킬은 무시됩니다. 팀 표준은 강제하면서 개인 커스터마이징도 허용하는 유연한 구조입니다.

충돌 예방을 위해 구체적인 이름을 사용하세요.
review ❌  →  frontend-review, backend-review ✅

---

5. 스킬 수정 · 삭제

작업	방법	비고
수정	SKILL.md 파일 직접 편집	재시작 필요
삭제	스킬 디렉토리 전체 삭제	재시작 필요
비활성화	디렉토리명 앞에 _ 추가 (예: _pr-description)	파일 보존하며 임시 비활성화

스킬 생성, 수정, 삭제 후에는 반드시 Claude Code를 재시작해야 변경사항이 반영됩니다. 재시작 없이는 이전 상태가 그대로 유지됩니다.

---

6. 좋은 description 작성 팁

스킬이 올바르게 트리거되려면 description을 잘 작성하는 것이 핵심입니다.

좋은 description 예시

# ✅ 좋은 예 — "Use when..." 패턴으로 상황을 명시
description: Writes commit messages in conventional format.
             Use when writing a commit, staging changes,
             or summarizing what changed in this commit.

# ❌ 나쁜 예 — 너무 짧고 모호함
description: commit helper

✅ 포함할 것

"Use when..." 트리거 패턴
구체적인 사용 상황 2–3가지
관련 동의어 포함

❌ 피할 것

단어 1–2개짜리 설명
지나치게 넓은 범위
다른 스킬과 겹치는 description

핵심 원칙 ✨

Claude에게 같은 내용을 반복 설명하고 있다면
그건 스킬로 만들어야 한다는 신호입니다.

SKILL.md 한 번 작성 → 영원히 자동 적용 🚀