Claude Academy
로그인

Creating your first skill

강의 210분
이 레슨에서이 레슨을 마치면
  • 올바른 frontmatter 구조로 처음부터 스킬 생성하기
  • 스킬이 Claude Code에서 올바르게 로드되는지 테스트하고 확인하기
  • Claude Code가 들어오는 요청을 사용 가능한 스킬과 매칭하는 방식 설명하기
  • 스킬 우선순위 계층 구조(Enterprise, Personal, Project, Plugins) 설명하기
Sign in to save your progressYou can keep reading without an account, but completed lessons won't be saved.
Sign in

Creating your first skill

첫 번째 스킬 만들기 · 4 min

이 영상에서는 처음부터 스킬을 만드는 과정을 살펴봅니다 — 모든 프로젝트에서 작동하는 개인용 PR 설명 스킬입니다. SKILL.md 파일을 구조화하는 방법, 테스트하는 방법, 그리고 Claude Code가 스킬을 발견하고 요청에 매칭하는 방식을 정확히 확인할 수 있습니다. 이 영상에서는 이름이 충돌할 때 어떤 스킬이 우선하는지를 결정하는 우선순위 계층 구조도 다룹니다.

한국어 대본
  • 00:00자, 스킬을 만들어 보겠습니다. 이 스킬은 시각적 다이어그램과 비유를 사용해 코드를 설명하는 방식을 Claude에게 가르칩니다.
  • 00:11그런 다음 Claude가 이를 사용할 때 내부적으로 어떤 일이 일어나는지 살펴보겠습니다.
  • 00:16먼저 스킬용 디렉터리를 만들어 보겠습니다.
  • 00:21개인 스킬을 만들 것이므로 여러 프로젝트에서 사용할 수 있도록 두겠습니다.
  • 00:25따라서 홈 디렉터리에 저장합니다.
  • 00:27스킬 디렉터리 안에 스킬 이름으로 디렉터리를 만들고 있다는 점을
  • 00:30고려하세요. 이제 스킬을 만드세요. 이름은 스킬을 식별합니다. 설명은 Claude에게
  • 00:42언제 사용할지를 알려 줍니다. 이것이 매칭 기준입니다. 그리고 두 번째 대시 뒤의 모든 내용은
  • 00:48Claude가 따르는 지침입니다. Claude Code는 시작할 때 스킬을 불러오므로 세션을 다시 시작하세요.
  • 00:55그런 다음 사용 가능한지 확인하세요. 목록에 PR description이 표시되어야 합니다.
  • 01:04이제 테스트해 보세요. 브랜치에서 몇 가지를 변경한 다음, ‘변경 사항에 대한 PR description을 작성해 줘’라고 말하세요.
  • 01:11그러면 Claude가 PR description 스킬을 사용하고 있음을 보여 줍니다.
  • 01:16그런 다음 diff를 확인하고 템플릿에 따라 설명을 작성합니다.
  • 01:21매번 형식이 같습니다.
  • 01:24Claude Code가 시작되면 스킬을 찾기 위해 네 곳을 검색합니다.
  • 01:27엔터프라이즈 경로, 개인 Claude Skills, 프로젝트의 Claude Skills, 그리고 설치된 플러그인입니다.
  • 01:33각 스킬의 이름과 설명만 불러오고 전체 내용은 불러오지 않습니다.
  • 01:38이 내용은 뒤에서 중요합니다.
  • 01:39요청을 보내면 Claude가 스킬 설명과 비교합니다.
  • 01:43“이 함수가 무엇을 하는지 설명해 줘”라는 요청은 ‘시각적 다이어그램으로 코드를 설명’하는 스킬과 일치합니다.
  • 01:48의도가 겹치기 때문입니다.
  • 01:50그러면 스킬을 불러올지 확인해 달라고 묻습니다. 이 확인 단계는 Claude가 어떤
  • 01:55컨텍스트를 사용하는지 알 수 있게 합니다. 확인하면 Claude가 전체 파일을 읽고 그
  • 02:01지침을 따릅니다. 이제 Git 저장소를 복제했는데 이름이 같은 스킬도 있다고 가정해 보겠습니다.
  • 02:06그렇다면 어느 쪽이 우선합니까? 우선순위는 다음과 같습니다. 가장 높은 것은 관리 설정에 있는 엔터프라이즈 스킬입니다.
  • 02:13두 번째는 루트 디렉터리 구성에 있는 개인 스킬입니다. 지금 만드는 방식이 여기에 해당합니다. 세 번째는
  • 02:18저장소 안의 `.claude` 디렉터리에 있는 프로젝트 스킬입니다.
  • 02:23가장 낮은 것은 온라인에서 받은 플러그인을 저장하는 플러그인입니다. 이렇게 하면
  • 02:29조직이 표준을 적용하면서도 서로 다른 이름의 스킬을 통해 개인별 맞춤 설정을 허용할 수 있습니다.
  • 02:34스킬 이름을 사용할 수 있습니다. 회사에 엔터프라이즈 코드 리뷰 스킬이 있는데 개인 코드
  • 02:40리뷰 스킬을 만들면 엔터프라이즈 버전이 우선합니다. 충돌을 피하려면 설명적인
  • 02:46이름을 사용하세요. review 대신 frontend PR review나 security review를 사용하세요. 스킬을 업데이트하려면 해당
  • 02:54skill.md 파일을 편집하세요. 간단합니다. 삭제하려면 해당 디렉터리를 삭제하세요. 변경 후 Claude Code를 다시 시작해야
  • 03:02변경 사항이 적용됩니다. 스킬을 만든다는 것은 skill.md 파일이 들어 있는 디렉터리를 만드는 것이며, 이 파일에는
  • 03:10메타데이터와 지침이 들어 있습니다.
  • 03:13Claude는 시작할 때 스킬 이름과 설명을 불러오고, 들어오는 요청을
  • 03:19그 설명과 비교한 뒤 전체 내용을 불러오기 전에 확인을 요청합니다.
  • 03:24이름 충돌을 처리하는 우선순위 규칙입니다.
  • 03:27엔터프라이즈가 개인을 우선하고, 개인이 프로젝트를 우선하며, 프로젝트가 플러그인을 우선합니다.
  • 03:32skill.mv 파일을 편집해 스킬을 업데이트하고, 변경 사항을 적용하려면 Claude Code를 다시 시작하세요.
  • 03:40이제
Watch on YouTube

Key takeaways

  • 스킬은 frontmatter에 메타데이터(이름, 설명)가 있고 그 아래에 지침이 있는 SKILL.md 파일을 포함하는 디렉터리입니다
  • Claude는 시작 시 스킬 이름과 설명만 로드한 다음, 시맨틱 매칭을 사용하여 들어오는 요청을 해당 설명과 매칭합니다
  • Claude가 전체 스킬 콘텐츠를 컨텍스트에 로드하기 전에 확인 프롬프트가 표시됩니다
  • 이름 충돌 시 우선순위: Enterprise → Personal → Project → Plugins
  • 스킬을 업데이트하려면 해당 SKILL.md를 편집하세요. 제거하려면 해당 디렉터리를 삭제하세요. 변경 사항이 적용되려면 항상 Claude Code를 재시작하세요

처음부터 스킬을 만드는 과정을 살펴본 다음, Claude Code가 실제로 스킬을 로드하고 매칭하는 방식을 내부적으로 살펴보겠습니다.

Creating a Skill

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

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

mkdir -p ~/.claude/skills/pr-description

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

markdown
---
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은 스킬을 식별합니다. description은 Claude에게 언제 이 스킬을 사용해야 하는지 알려줍니다 — 이것이 매칭 기준입니다. 두 번째 대시 세트 이후의 모든 내용은 스킬이 활성화될 때 Claude가 따르는 지침입니다.

Testing Your Skill

Claude Code는 시작 시 스킬을 로드하므로, 스킬을 만든 후에는 세션을 재시작하세요. 사용 가능한 스킬 목록을 확인하여 스킬이 사용 가능한지 확인할 수 있습니다.

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

How Skill Matching Works

Claude Code가 시작되면 네 곳의 위치에서 스킬을 검색하지만 이름과 설명만 로드합니다 — 전체 콘텐츠는 로드하지 않습니다. 이는 중요한 세부 사항입니다.

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

매칭이 발견되면 Claude는 스킬 로드를 확인해 달라고 요청합니다. 이 확인 단계는 Claude가 어떤 컨텍스트를 가져오는지 사용자가 인지할 수 있게 해줍니다. 확인 후, Claude는 전체 SKILL.md 파일을 읽고 그 지침을 따릅니다.

Skill Priority

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

  1. Enterprise — 관리형 설정, 최고 우선순위
  2. Personal — 홈 디렉터리(~/.claude/skills)
  3. Project — 저장소 내부의 .claude/skills 디렉터리
  4. Plugins — 설치된 플러그인, 최저 우선순위

이를 통해 조직은 엔터프라이즈 스킬을 통해 표준을 강제하면서도 개별 사용자 정의를 허용할 수 있습니다. 회사에 엔터프라이즈 "code-review" 스킬이 있고 동일한 이름으로 개인용 "code-review" 스킬을 만들면, 엔터프라이즈 버전이 우선합니다.

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

Updating and Removing Skills

스킬을 업데이트하려면 해당 SKILL.md 파일을 편집하세요. 제거하려면 해당 디렉터리를 삭제하세요. 변경 사항이 적용되려면 변경 후 Claude Code를 재시작하세요.

Lesson reflection

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

What's next

다음 레슨에서는 메타데이터 필드, allowed-tools를 사용한 도구 제한, 그리고 점진적 공개(progressive disclosure)와 다중 파일 구성을 사용하여 더 큰 스킬을 구조화하는 방법을 포함한 고급 구성 옵션에 대해 배웁니다.