[공식문서읽기] Claude Code Skills 가이드 - AI 코딩 어시스턴트 확장하기

Claude Code Skills는 AI 코딩 어시스턴트인 Claude Code의 기능을 확장하는 강력한 시스템입니다. SKILL.md 파일에 지시사항을 작성하면 Claude가 이를 도구로 활용하며, 상황에 맞게 자동으로 적용하거나 /skill-name 형태로 직접 호출할 수 있습니다.

ai로 생성한 이미지로, 내용과 관련이 없을 수 있습니다.

---

Skills와 Slash Commands의 통합

2026년 현재 Claude Code에서는 Skills와 Slash Commands가 하나의 통합된 시스템으로 운영됩니다. 기존에 .claude/commands/review.md에 있던 파일과 .claude/skills/review/SKILL.md에 있는 스킬 모두 /review로 동작합니다.

기존 .claude/commands/ 파일들도 계속 작동하지만, Skills는 추가적인 기능을 제공합니다:

• 지원 파일을 위한 디렉토리 구조
• 호출 제어를 위한 frontmatter
• 상황에 맞는 자동 로딩

ai로 생성한 이미지로, 내용과 관련이 없을 수 있습니다.

SKILL.md 파일 구조

모든 스킬은 두 부분으로 구성된 SKILL.md 파일이 필요합니다:

1. YAML Frontmatter

--- 마커 사이에 작성하며, Claude에게 스킬을 언제 사용할지 알려줍니다.

2. Markdown 본문

스킬이 호출되었을 때 Claude가 따르는 지시사항입니다.

기본 예제

---
name: explain-code
description: 코드를 시각적 다이어그램과 비유로 설명합니다. 코드 작동 방식을 설명하거나 "이게 어떻게 동작해?"라고 물을 때 사용합니다.
---

코드를 설명할 때 항상 다음을 포함하세요:

1. **비유로 시작**: 코드를 일상생활의 무언가와 비교
2. **다이어그램 그리기**: ASCII 아트로 흐름, 구조, 관계 표시
3. **코드 워크스루**: 단계별로 무슨 일이 일어나는지 설명
4. **주의점 강조**: 흔한 실수나 오해는 무엇인가?

---

Frontmatter 필드 레퍼런스

필드	필수 여부	설명
name	선택	스킬 표시 이름. 생략 시 디렉토리 이름 사용
description	권장	스킬의 기능과 사용 시점. Claude가 자동 적용 판단에 활용
argument-hint	선택	자동완성 시 표시되는 인자 힌트 (예: [issue-number])
disable-model-invocation	선택	true 설정 시 Claude 자동 로딩 방지. 수동 호출만 허용
user-invocable	선택	false 설정 시 / 메뉴에서 숨김. 백그라운드 지식용
allowed-tools	선택	스킬 활성화 시 Claude가 승인 없이 사용할 수 있는 도구
model	선택	스킬 활성화 시 사용할 모델
context	선택	fork 설정 시 분리된 서브에이전트 컨텍스트에서 실행
agent	선택	context: fork 사용 시 서브에이전트 유형 지정

---

스킬 저장 위치

스킬을 어디에 저장하느냐에 따라 사용 범위가 결정됩니다:

위치	경로	적용 범위
Enterprise	관리 설정 참조	조직 전체 사용자
Personal	~/.claude/skills/<skill-name>/SKILL.md	모든 개인 프로젝트
Project	.claude/skills/<skill-name>/SKILL.md	해당 프로젝트만
Plugin	<plugin>/skills/<skill-name>/SKILL.md	플러그인 활성화된 곳

동일한 이름의 스킬이 여러 레벨에 있으면 우선순위가 높은 것이 적용됩니다: enterprise > personal > project

---

스킬 디렉토리 구조

my-skill/
├── SKILL.md           # 메인 지시사항 (필수)
├── template.md        # Claude가 채울 템플릿
├── examples/
│   └── sample.md      # 예상 출력 형식 예제
└── scripts/
    └── validate.sh    # Claude가 실행할 수 있는 스크립트

---

호출 제어하기

기본적으로 사용자와 Claude 모두 스킬을 호출할 수 있습니다. 두 가지 frontmatter 필드로 제한할 수 있습니다:

사용자만 호출 가능

---
name: deploy
description: 프로덕션에 애플리케이션 배포
disable-model-invocation: true
---

배포, 커밋, 메시지 전송 등 부작용이 있는 워크플로우에 사용합니다.

Claude만 호출 가능

---
name: legacy-system-context
description: 레거시 시스템 작동 방식 설명
user-invocable: false
---

백그라운드 지식으로 Claude가 필요할 때 참조하되, 사용자가 직접 호출할 필요 없는 경우에 사용합니다.

---

인자 전달하기

$ARGUMENTS 플레이스홀더로 인자를 받을 수 있습니다:

---
name: fix-issue
description: GitHub 이슈 수정
disable-model-invocation: true
---

GitHub 이슈 $ARGUMENTS를 코딩 표준에 따라 수정하세요.

1. 이슈 설명 읽기
2. 요구사항 이해
3. 수정 구현
4. 테스트 작성
5. 커밋 생성

/fix-issue 123 실행 시 Claude는 "GitHub 이슈 123을 코딩 표준에 따라 수정하세요..."를 받습니다.

개별 인자 접근

---
name: migrate-component
description: 컴포넌트를 한 프레임워크에서 다른 프레임워크로 마이그레이션
---

$0 컴포넌트를 $1에서 $2로 마이그레이션하세요.

/migrate-component SearchBar React Vue 실행 시 각각 대체됩니다.

동적 컨텍스트 주입

!`command` 문법으로 스킬 내용이 Claude에게 전달되기 전에 셸 명령을 실행할 수 있습니다:

---
name: pr-summary
description: Pull Request 변경사항 요약
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull Request 컨텍스트
- PR diff: !`gh pr diff`
- PR 코멘트: !`gh pr view --comments`
- 변경된 파일: !`gh pr diff --name-only`

## 할 일
이 Pull Request를 요약하세요...

이 스킬이 실행되면:

1. 각 !`command`가 즉시 실행됨
2. 출력이 스킬 내용의 플레이스홀더를 대체
3. Claude는 실제 PR 데이터가 포함된 최종 프롬프트를 받음

---

서브에이전트에서 실행하기

context: fork를 frontmatter에 추가하면 스킬이 분리된 환경에서 실행됩니다:

---
name: deep-research
description: 주제를 철저히 조사
context: fork
agent: Explore
---

$ARGUMENTS를 철저히 조사하세요:

1. Glob과 Grep으로 관련 파일 찾기
2. 코드 읽고 분석
3. 특정 파일 참조와 함께 발견사항 요약

이 방식으로 대화 히스토리와 분리된 환경에서 집중적인 작업을 수행할 수 있습니다.

---

도구 접근 제한

allowed-tools 필드로 스킬 활성화 시 사용 가능한 도구를 제한할 수 있습니다:

---
name: safe-reader
description: 변경 없이 파일만 읽기
allowed-tools: Read, Grep, Glob
---

이렇게 하면 읽기 전용 모드로 탐색만 가능하고 수정은 불가능합니다.

---

스킬 문자 예산

스킬 설명은 컨텍스트에 로드되어 Claude가 무엇이 가능한지 알 수 있습니다. 많은 스킬이 있으면 문자 예산을 초과할 수 있습니다:

• 예산은 컨텍스트 윈도우의 2%로 동적 확장
• 폴백 값은 16,000자
• /context 명령으로 제외된 스킬 경고 확인 가능
• SLASH_COMMAND_TOOL_CHAR_BUDGET 환경변수로 제한 재정의 가능

---

베스트 프랙티스

1. description을 명확하게 작성

description은 스킬의 주요 트리거 메커니즘입니다. 스킬이 무엇을 하는지와 언제 사용할지 모두 포함하세요.

2. SKILL.md는 500줄 이하로 유지

상세한 참조 자료는 별도 파일로 분리하세요.

3. 부작용 있는 스킬은 수동 호출로

disable-model-invocation: true를 사용해 배포, 삭제, 전송 등의 작업은 사용자가 명시적으로 호출하도록 합니다.

4. YAML 포맷 주의

• 일관된 들여쓰기 사용 (탭 아닌 스페이스 2칸)
• 필드 이름에 특수문자 피하기
• --- 마커로 frontmatter 감싸기

---

마무리

Claude Code Skills는 반복적인 워크플로우를 자동화하고 Claude의 기능을 프로젝트에 맞게 확장하는 강력한 도구입니다. 간단한 코딩 컨벤션부터 복잡한 배포 파이프라인까지, Skills를 통해 AI 어시스턴트를 팀의 요구에 맞게 커스터마이징할 수 있습니다.

Skills는 Agent Skills 오픈 스탠다드를 따르므로 여러 AI 도구에서 호환됩니다.

---

이 글은 Claude Code를 활용하여 작성되었습니다.

참고: https://code.claude.com/docs/ko/skills