[What are skills?] 스킬이란 무엇일까?

🤖 Claude Code Agent Skills 완전 정복

Anthropic Academy 강의 정리

📌 이 글의 핵심 요약

• Skills는 Claude Code가 자동으로 찾아 사용하는 마크다운 지시 파일입니다.
• 매번 같은 내용을 반복 설명하지 않고, 한 번 작성 → 자동 적용이 가능합니다.
• 개인/프로젝트/엔터프라이즈 단위로 관리하며 팀 전체에 공유할 수 있습니다.

1. Skills란 무엇인가?

PR 리뷰 기준, 커밋 메시지 형식, 팀 코딩 표준… 매번 Claude에게 설명하고 계신가요? Skills는 이 반복을 끝내줍니다.

Skills는 SKILL.md 파일 하나로 구성되며, Claude는 사용자의 요청을 보고 자동으로 알맞은 스킬을 찾아 적용합니다. 별도로 호출하거나 매번 붙여넣을 필요가 없습니다.

---
name: pr-review
description: Reviews pull requests for code quality.
             Use when reviewing PRs or checking code changes.
---

# 이 아래에 실제 지시 내용 작성
- 변수명이 명확한지 확인
- 불필요한 console.log 제거 여부 확인
- PR 설명이 충분한지 확인
...

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

---

2. Skills 저장 위치

종류	위치	특징
개인 스킬	~/.claude/skills	모든 프로젝트에서 사용 가능. 커밋 스타일, 코드 설명 방식 등 개인 습관 저장.
프로젝트 스킬	.claude/skills (저장소 내)	저장소를 클론한 팀원 모두가 자동 공유. 팀 표준, 브랜드 가이드라인 등에 적합.

Windows 사용자는 개인 스킬을 C:/Users/<사용자명>/.claude/skills 에 저장하세요.

---

3. Skills가 활성화되는 과정

Claude Code는 시작 시 스킬 폴더를 스캔하지만, 처음에는 이름과 설명만 불러옵니다. 컨텍스트 윈도우를 효율적으로 유지하기 위함입니다.

1

Claude Code 시작4곳의 스킬 폴더 스캔

2

name + description만 로드전체 내용은 아직 불러오지 않음

3

사용자 요청 입력예: "PR 설명 작성해줘"

4

의미 기반 매칭 (Semantic Matching)요청과 description을 비교해 관련 스킬 탐색

5

사용자 확인 프롬프트어떤 스킬을 로드할지 사용자에게 알림

6

SKILL.md 전체 내용 로드 및 실행지시에 따라 작업 수행

---

4. CLAUDE.md / Skills / Slash Commands 비교

방식	동작 방식	적합한 용도
CLAUDE.md	매 대화마다 항상 로드	TypeScript strict 모드처럼 항상 적용되어야 하는 설정
Skills	요청과 일치할 때 자동 로드	PR 리뷰, 커밋 메시지 등 특정 상황에만 필요한 전문 지식
Slash Commands	사용자가 직접 타이핑해야 실행	명시적으로 호출이 필요한 작업

Skills의 핵심 장점은 필요할 때만 로드된다는 것입니다. PR 리뷰 체크리스트가 디버깅 중에는 컨텍스트를 차지하지 않습니다.

---

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

동일한 이름의 스킬이 여러 곳에 있을 경우 아래 순서로 우선순위가 결정됩니다.

1순위

Enterprise — 조직 관리자가 설정한 스킬. 최고 우선순위.

2순위

Personal — ~/.claude/skills 에 저장된 개인 스킬.

3순위

Project — 저장소 내 .claude/skills 에 있는 팀 공유 스킬.

4순위

Plugins — 설치된 플러그인 스킬. 최저 우선순위.

충돌을 예방하려면 구체적인 이름을 사용하세요. review ❌ → frontend-review ✅

---

6. 스킬 생성 · 수정 · 삭제

스킬 생성 (예: PR 설명 스킬)

# 1. 스킬 디렉토리 생성
mkdir -p ~/.claude/skills/pr-description

# 2. SKILL.md 파일 작성

---
name: pr-description
description: Writes pull request descriptions.
             Use when creating a PR or summarizing changes.
---

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

1. `git diff main...HEAD` 실행하여 변경 사항 확인
2. 아래 형식으로 작성:

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

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

## Changes
- 구체적인 변경 사항을 불릿 포인트로
- 관련 변경은 그룹으로 묶기

작업	방법
생성	디렉토리 생성 후 SKILL.md 작성
수정	SKILL.md 파일 직접 편집
삭제	스킬 디렉토리 전체 삭제

변경사항을 반영하려면 항상 Claude Code를 재시작해야 합니다.

---

7. Skills를 사용하면 좋은 경우

특정 작업에만 필요한 전문적이고 반복적인 지식을 담기에 적합합니다.

활용 예시	스킬 설명 예시
팀 코드 리뷰 기준	"Use when reviewing PRs or checking code quality"
커밋 메시지 형식	"Use when writing a commit message or summarizing changes"
브랜드 가이드라인	"Use when creating marketing copy or brand assets"
문서 템플릿	"Use when writing technical documentation or API docs"
디버깅 체크리스트	"Use when debugging React or investigating frontend errors"

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

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