첫 번째 Skill 만들기

첫 번째 Skill 만들기

핵심 요약

• Skill은 frontmatter에 메타데이터(이름, 설명)가 있고 그 아래에 지침이 있는 SKILL.md 파일을 포함하는 디렉터리입니다
• Claude는 시작 시 Skill 이름과 설명만 로드한 다음, 시맨틱 매칭을 사용하여 들어오는 요청을 해당 설명과 매칭합니다
• 매칭이 이루어지면 이름, 설명, 지침만 있는 Skill은 묻지 않고 전체가 로드됩니다. Skill이 도구를 사전 승인하거나 훅을 추가하는 경우, Claude Code가 먼저 승인을 요청할 수 있습니다
• 이름 충돌 시 우선순위: Enterprise → Personal → Project. 플러그인 Skill은 네임스페이스가 지정되므로 동일한 이름의 Skill과 함께 로드됩니다
• Skill을 업데이트하려면 해당 SKILL.md를 편집하세요. 제거하려면 해당 디렉터리를 삭제하세요. Claude Code는 재시작 없이 현재 세션에서 변경 사항을 인식합니다. 이번 세션에서 ~/.claude/skills가 새로 생긴 경우, 각 변경 후 /reload-skills를 실행하세요

처음부터 Skill을 만드는 과정을 살펴본 다음, Claude Code가 실제로 내부에서 Skill을 로드하고 매칭하는 방식을 알아보겠습니다.

Skill 만들기

일관된 형식으로 PR 설명을 작성하는 방법을 Claude에게 가르치는 개인용 Skill을 만들어 보겠습니다. 개인용 Skill이므로 홈 디렉터리에 위치하며 모든 프로젝트에서 작동합니다.

먼저, skills 폴더 안에 Skill용 디렉터리를 만듭니다. 디렉터리 이름은 Skill 이름과 일치해야 합니다:

그런 다음 해당 디렉터리 안에 SKILL.md 파일을 만듭니다. 이 파일은 frontmatter 대시로 구분된 두 부분으로 구성됩니다:

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

When writing a PR description:

1. Run `git diff main...HEAD` to see all changes on this branch
2. Write a description following this format:

## What
One sentence explaining what this PR does.

## Why
Brief context on why this change is needed

## Changes
- Bullet points of specific changes made
- Group related changes together
- Mention any files deleted or renamed

name은 Skill을 식별합니다. description은 Claude에게 언제 이 Skill을 사용할지 알려줍니다 — 이것이 매칭 기준입니다. 두 번째 대시 세트 이후의 모든 내용은 Skill이 활성화될 때 Claude가 따르는 지침입니다.



Skill 테스트하기

Claude Code는 Skill 디렉터리를 감시하므로, 새 Skill은 재시작 없이 현재 세션에서 바로 사용할 수 있습니다. 세션이 시작될 때 ~/.claude/skills가 존재하지 않았다면 Claude Code가 아직 이를 감시하지 않으므로, 지금 /reload-skills를 실행하고 이후 변경할 때마다 다시 실행하세요. 사용 가능한 Skill 목록을 확인하여 Skill이 사용 가능한지 확인할 수 있습니다.



Skill이 목록에 표시되어야 합니다. 테스트하려면 브랜치에서 변경 사항을 만들고 "내 변경 사항에 대한 PR 설명을 작성해줘"와 같이 말해 보세요. Claude는 PR 설명 Skill을 사용하고 있음을 표시하고, diff를 확인한 다음, 템플릿에 따라 설명을 작성합니다 — 매번 동일한 형식으로요.

Skill 매칭 작동 방식

Claude Code가 시작되면 여러 위치를 스캔하여 Skill을 찾지만, 전체 내용이 아니라 이름과 설명만 로드합니다. 이는 중요한 세부 사항입니다.

요청을 보내면 Claude는 메시지를 사용 가능한 모든 Skill의 설명과 비교합니다. 예를 들어 "이 함수가 무엇을 하는지 설명해줘"는 의도가 겹치기 때문에 "시각적 다이어그램으로 코드 설명"이라고 설명된 Skill과 매칭됩니다.

매칭이 발견되면 Claude는 전체 SKILL.md 파일을 읽고 그 지침을 따릅니다. 이름, 설명, 지침만 있는 Skill(예: pr-description)은 묻지 않고 로드됩니다. Skill이 도구를 사전 승인하거나 훅을 추가하는 경우, 권한 모드에 따라 Claude Code가 먼저 승인을 요청할 수 있습니다. 위의 영상과 아래 이미지는 Claude Code v2.1.19에서 pr-description 같은 Skill에 대해 제거된 승인 단계를 보여줍니다.



Skill 우선순위

개인 Skill 중 하나와 이름이 같은 Skill이 있는 저장소를 클론하면 어느 쪽이 우선할까요? 명확한 우선순위가 있습니다:

1. Enterprise — 관리형 설정, 최우선순위
2. Personal — 홈 디렉터리(~/.claude/skills)
3. Project — 저장소 내부의 .claude/skills 디렉터리

이를 통해 조직은 엔터프라이즈 Skill을 통해 표준을 강제하면서도 개인별 맞춤화를 허용할 수 있습니다. 회사에 엔터프라이즈 "code-review" Skill이 있고 동일한 이름으로 개인용 "code-review" Skill을 만들면, 엔터프라이즈 버전이 우선합니다. 설치된 플러그인의 Skill은 이 순서 밖에 있습니다. 이들은 /plugin-name:skill-name으로 네임스페이스가 지정되므로, 플러그인 Skill과 동일한 이름의 다른 Skill이 모두 로드됩니다.

충돌을 피하려면 설명적인 이름을 사용하세요. 단순히 "review"가 아니라 "frontend-review"나 "backend-review" 같은 이름을 사용하세요.

Skill 업데이트 및 제거

Skill을 업데이트하려면 해당 SKILL.md 파일을 편집하세요. 제거하려면 해당 디렉터리를 삭제하세요. Claude Code는 현재 세션에서 변경 사항을 인식하므로 재시작할 필요가 없습니다. 이번 세션에서 ~/.claude/skills가 새로 생겨서 이전에 /reload-skills를 실행했다면, 각 변경 후 다시 실행하세요.

레슨 되돌아보기

• 지금 당장 Skill로 전환할 수 있는 일상 워크플로우의 작업은 무엇인가요? 설명은 어떤 모습일까요?
• 우선순위 계층 구조가 팀의 Skill 관리 전략에 어떤 영향을 미칠 수 있을까요? 개인용 Skill과 프로젝트 수준 Skill 중 어느 쪽에 더 의존하시겠습니까?

다음 단계

다음 레슨에서는 메타데이터 필드, allowed-tools를 사용한 도구 사전 승인, 그리고 점진적 공개와 다중 파일 구성을 사용하여 더 큰 Skill을 구조화하는 방법 등 고급 구성 옵션에 대해 배웁니다.