AI 네이티브 전략 · Claude Code · GitHub Copilot 교육 상담 →
MW모던웹연구소
EN
전체 목차
챕터 02

첫 스킬 만들기

학습목표

  • 예상 학습 시간: 20 분

  • 이 수업을 마치면 다음을 할 수 있습니다.

    • 프론트매터 구조를 갖춘 스킬을 처음부터 만들기
    • Claude Code에서 스킬이 정상적으로 로드되는지 테스트하고 검증하기
    • Claude Code가 사용자의 요청을 사용 가능한 스킬과 매칭하는 방식을 설명하기
    • 스킬 우선순위(Enterprise, Personal, Project, Plugins) 계층을 설명하기

첫 번째 스킬 만들기

(4분)

이 영상에서는 스킬을 처음부터 만들어 봅니다. 예시론 다양한 코딩 프로젝트에서 쓸 수 있는 개인용 PR 설명(PR description) 스킬이 나옵니다. 예시를 통해 우리는 SKILL.md 파일을 어떻게 구성하는지와 제대로 로드되었는지 확인하는 방법을 배웁니다. 또한 Claude Code가 스킬을 발견하고 사용자의 요청과 매칭하는 내부 동작을 단계별로 확인합니다. 나아가 스킬 간 이름이 충돌할 때 어떤 스킬이 '이기는지' 결정하는 우선순위(Enterprise → Personal → Project → Plugins)도 함께 배웁니다.

핵심 요약

  • 스킬은 메타데이터(name, description)가 들어있는 프론트매터와, 그 아래의 실제 지시사항으로 구성된 SKILL.md 파일을 포함한 디렉터리(폴더)입니다.
  • Claude Code는 시작할 때 스킬의 이름과 설명만 먼저 로드한 뒤, 사용자의 요청을 설명과 의미 기반(semantic)으로 매칭합니다.
  • Claude가 스킬 본문을 컨텍스트로 가져오기 전에 확인(confirmation) 프롬프트가 한 번 표시됩니다.
  • 이름이 같은 스킬이 여러 위치에 존재하면 우선순위는 Enterprise → Personal → Project → Plugins입니다.
  • 스킬을 수정하려면 SKILL.md를 편집하면 됩니다. 스킬을 제거하려면 해당 디렉터리를 삭제하면 됩니다. 스킬 변경 사항은 Claude Code를 반드시 재시작해야 적용됩니다.

이제 스킬을 직접 만들어 보고, 그 다음 Claude Code가 스킬을 어떤 방식으로 로드하고 매칭하는지 내부 동작을 살펴보겠습니다.

스킬 만들기

이 레슨에서는 Claude에게 "PR 설명을 항상 같은 형식으로 작성하도록" 가르치는 개인 스킬을 만듭니다. 개인 스킬은 홈 디렉터리에 저장되므로, 여러 프로젝트에서 동일하게 사용할 수 있습니다.

먼저 스킬 디렉터리(pr-description)를 ~/.claude/skills 아래에 만듭니다. 디렉터리 이름은 스킬 이름과 일치하는 것이 좋습니다.

  1. MacOS 기준
mkdir -p ~/.claude/skills/pr-description
  1. Windows에서는 아래 경로에 개인 스킬을 만듭니다.
mkdir -p C:/Users/<your-user>/.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.
---

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: pr-description
description: Pull Request 설명을 작성합니다. PR을 만들거나, PR을 작성하거나, PR에 대한 변경 사항을 요약해 달라고 요청받을 때 사용하세요.
---

PR 설명을 작성할 때:

1. `git diff main...HEAD`를 실행해 이 브랜치에서 변경된 내용을 확인합니다.
2. 아래 형식을 따라 설명을 작성합니다:

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

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

## Changes
- 구체적으로 어떤 변경을 했는지 불릿으로 나열
- 관련된 변경은 묶어서 정리
- 삭제/이름 변경된 파일이 있다면 언급
  • name: 스킬을 식별하는 이름입니다.
  • description: Claude가 '언제 이 스킬을 써야 하는지' 판단하는 기준입니다(매칭 기준).
  • 두 번째 --- 아래: 스킬이 활성화되었을 때 Claude가 따라야 하는 실제 지시사항입니다.

스킬 테스트하기

Claude Code는 시작할 때 스킬을 스캔해 로드하므로, 새 스킬을 만든 뒤에는 세션을 재시작해야 합니다. 재시작 후, '사용 가능한 스킬 목록'에서 방금 만든 스킬이 보이는지 확인합니다.

목록에 스킬이 보이면, 브랜치에서 변경을 만든 뒤 아래처럼 요청해 테스트해 볼 수 있습니다.

  • "내 변경 사항으로 PR 설명 작성해줘"
  • "이 브랜치 변경을 요약해서 PR description으로 써줘"

Claude는 PR 설명 스킬을 사용한다고 표시하고, diff를 확인한 뒤, 미리 정의한 템플릿 형식에 맞춰 PR 설명을 작성해 줍니다. 즉, 매번 같은 포맷으로 결과를 얻을 수 있습니다.

스킬 매칭은 어떻게 동작하나요?

Claude Code는 시작 시점에 네 개의 위치(아래 '스킬 우선순위' 섹션 참고)를 스캔해 스킬을 찾지만, 이때는 SKILL.md의 전체 본문을 다 읽지 않고 name과 description만 먼저 읽어 둡니다. 이 점이 중요합니다.

사용자가 요청을 보내면, Claude는 그 요청을 모든 스킬의 description과 비교해 가장 적합한 스킬을 찾습니다. 예를 들어, "이 함수가 뭘 하는지 설명해줘"라는 요청은 "코드를 시각적 다이어그램으로 설명한다" 같은 description을 가진 스킬과 의미가 겹치면 매칭될 수 있습니다.

매칭이 되면 Claude는 해당 스킬을 컨텍스트로 로드하기 전에 확인 프롬프트를 띄웁니다. 사용자가 확인하면, Claude는 SKILL.md의 본문을 읽고 그 지시사항을 그대로 따릅니다.

스킬 우선순위

저장소를 클론했더니 프로젝트 안에도 같은 이름의 스킬이 있고, 내 개인 스킬에도 같은 이름의 스킬이 있다면 무엇이 적용될까요? 이름 충돌(name conflict)이 발생할 때는 아래 우선순위를 따릅니다.

  1. Enterprise — 조직에서 관리하는 설정(가장 높은 우선순위)
  2. Personal — 홈 디렉터리의 개인 스킬(~/.claude/skills 또는 C:/Users/<your-user>/.claude/skills)
  3. Project — 저장소 내부의 프로젝트 스킬(.claude/skills)
  4. Plugins — 설치된 플러그인 스킬(가장 낮은 우선순위)

이 우선순위 덕분에 조직은 엔터프라이즈 스킬로 표준을 강제할 수 있고, 개인은 개인 스킬로 커스터마이징할 수 있습니다. 예를 들어 회사가 code-review 엔터프라이즈 스킬을 제공하고, 개인이 같은 이름의 스킬을 만들어도 엔터프라이즈 버전이 우선합니다.

충돌을 피하려면, 스킬 이름을 더 구체적으로 짓는 것이 좋습니다. 예를 들어 review 대신 frontend-review, backend-review처럼 목적을 드러내는 이름을 사용하세요.

스킬 수정 및 제거

  • 스킬을 수정하려면: 해당 스킬 디렉터리의 SKILL.md를 편집합니다.
  • 스킬을 제거하려면: 스킬 디렉터리를 삭제합니다.

어떤 변경이든 적용되려면 Claude Code를 재시작해야 합니다.

학습 후 돌아보기

  • 오늘 당장 스킬로 만들 수 있는, 반복되는 업무는 무엇인가요? 그 스킬의 description은 어떻게 적으면 좋을까요?
  • 스킬 우선순위 계층은 팀의 스킬 관리 방식에 어떤 영향을 줄까요? 개인 스킬과 프로젝트 스킬 중 무엇에 더 의존하게 될까요?

이 글은 모던웹연구소 (www.modernweblabs.com)에서 처음 발행되었습니다. © 모던웹연구소. 무단 전재 및 재배포를 금합니다.

공유