Claude Code Skills 실습 가이드

Goofi Talk 프로젝트 기반 핸즈온 튜토리얼.
개념 이해 → 직접 파일 작성 → 실행 확인 순서로 진행합니다.

---

스킬이란?

/스킬명을 입력하면 실행되는 나만의 슬래시 커맨드입니다.

사용자가 /review 라고 입력
     ↓
Claude Code가 SKILL.md 파일을 읽음
     ↓
파일 안의 프롬프트를 Claude에게 전달
     ↓
Claude가 실행

파일 구조

.claude/skills/스킬이름/
└── SKILL.md    ← 이 파일 하나가 슬래시 커맨드가 됨

예전 방식 vs 지금 방식

예전:  .claude/commands/이름.md       ← 아직 동작하지만 구식
지금:  .claude/skills/이름/SKILL.md   ← 권장 방식 (이 가이드에서 사용)

---

실습 1: 가장 간단한 스킬

만드는 법

Step 1. 폴더 만들기

mkdir -p .claude/skills/hello

Step 2. .claude/skills/hello/SKILL.md 파일 만들고 아래 내용 작성

---
description: 인사 테스트 스킬
---
안녕하세요! 현재 프로젝트의 구조를 간단히 설명해주세요.

Step 3. Claude Code 입력창에서 /hello 입력 후 실행

파일 구조 설명

---
description: 인사 테스트 스킬   ← 자동완성 목록에 표시되는 설명
---
안녕하세요! ...                 ← Claude에게 실제로 전달되는 프롬프트

description 없이 프롬프트만 써도 동작합니다. 다만 자동완성에서 설명이 안 보입니다.

확인해보기

• /he 까지만 쳐도 자동완성에 나타나는가?
• 스킬 목록(system-reminder)에 hello: 인사 테스트 스킬이 보이는가?

---

실습 2: $ARGUMENTS — 사용자 입력 받기

개념

$ARGUMENTS는 스킬 이름 뒤에 입력한 텍스트로 자동 교체됩니다.

/explain use-chat-search.ts 라고 입력하면

SKILL.md 안의 $ARGUMENTS → "use-chat-search.ts" 로 교체됨

만드는 법

Step 1. 폴더 만들기

mkdir -p .claude/skills/explain

Step 2. .claude/skills/explain/SKILL.md 작성

---
description: 지정한 파일을 초보자도 이해할 수 있게 설명
argument-hint: [파일경로]
---
다음 파일을 읽고 초보자도 이해할 수 있게 설명해주세요: $ARGUMENTS

설명 형식:
1. 이 파일의 역할 (한 줄 요약)
2. 주요 함수/변수 목록과 각각의 역할
3. 다른 파일과의 관계

Step 3. 테스트

/explain src/chatbot/hooks/use-chat-search.ts
/explain src/lib/ai-client.ts

확인해보기

• Claude가 받은 프롬프트 상단에 $ARGUMENTS 대신 파일 경로가 들어가 있는가?
• /explain만 입력하면 어떻게 되는가? (직접 확인!)

심화: 인자를 여러 개 받으려면?

공백으로 구분해서 $0, $1로 받을 수 있습니다.

/compare fileA.ts fileB.ts 입력하면

$0 = "fileA.ts"
$1 = "fileB.ts"
$ARGUMENTS = "fileA.ts fileB.ts"  (전체)

도전 과제

두 파일을 비교하는 /compare 스킬 만들어보기

mkdir -p .claude/skills/compare

.claude/skills/compare/SKILL.md 안에서 $0과 $1을 사용해서 각 파일을 구분하여 비교하는 프롬프트 작성

---

실습 3: !명령어 — 자동으로 정보 가져오기

개념

스킬은 결국 Claude에게 보내는 메시지입니다.

!`명령어` 없이 /status를 실행하면 Claude는 이 메시지를 받습니다:

현재 프로젝트 상태를 분석해주세요.

git 상태가 뭔지 모르니까 Claude가 직접 도구를 호출해서 알아내야 합니다. 시간도 걸리고 토큰도 씁니다.

!`명령어`를 SKILL.md에 써두면, 스킬 실행 시 Claude Code가 미리 명령어를 실행하고 결과를 메시지에 끼워넣어서 Claude에게 보냅니다:

현재 프로젝트 상태를 분석해주세요.

Git 상태:
 M .claude/agents/react-supabase-fullstack.md
?? .claude/skills/

최근 커밋:
51d26c5 style: 랜딩 페이지...

현재 브랜치:
main

git 결과가 이미 메시지 안에 들어있으니 Claude가 도구 호출 없이 바로 분석합니다.

!`command` 없이:
  /status 실행 → Claude → "git 상태가 뭐죠?" → 도구 호출 → 결과 확인 → 분석
                           (토큰 소비)          (시간 소비)

!`command` 있으면:
  /status 실행 → Claude Code가 미리 실행 → 결과 포함된 메시지 → Claude → 바로 분석

빠르고, 토큰 절약, 불필요한 도구 호출 없음.

꼭 써야 하는 건 아닙니다. Claude가 알아서 도구를 쓰게 해도 됩니다. 다만 스킬 실행마다 항상 자동으로 포함시키고 싶은 정보가 있을 때 씁니다.

만드는 법

Step 1. 폴더 만들기

mkdir -p .claude/skills/status

Step 2. .claude/skills/status/SKILL.md 작성

---
description: 프로젝트 현재 상태 요약
---
현재 프로젝트 상태를 분석해주세요.

## Git 상태
!`git status --short`

## 최근 커밋 3개
!`git log --oneline -3`

## 현재 브랜치
!`git branch --show-current`

위 정보를 바탕으로:
1. 작업 중인 것이 무엇인지
2. 커밋되지 않은 변경사항이 있는지
3. 다음에 할 일을 추천해주세요

Step 3. /status 실행

확인해보기

스킬 실행 후 Claude가 받은 프롬프트를 보면:

• !git status --short`` 자리에 실제 git 결과가 들어있는가?
• Claude가 별도로 git 명령을 실행하지 않고 바로 분석하는가?

도전 과제

!`명령어`를 활용한 /review 스킬 만들어보기:

mkdir -p .claude/skills/review

SKILL.md 안에서:

• !`git diff` — 수정된 내용 자동 삽입
• !`git diff --cached` — staged 내용 자동 삽입
• $ARGUMENTS — 추가 리뷰 포인트 입력 받기
• 프로젝트 컨벤션 체크 항목 포함 (sanitizeHtml 누락, Zustand 전체 구독 등)

---

실습 4: frontmatter 고급 옵션

개념

SKILL.md 상단의 --- 안에 다양한 설정을 넣을 수 있습니다.

---
name: 스킬명
description: 설명
argument-hint: [인자1] [인자2]
disable-model-invocation: true   # Claude가 자동으로 호출 못하게 차단
user-invocable: false            # 사용자가 직접 호출 못하게 차단
allowed-tools: Read, Grep, Glob  # 사용 가능한 도구 제한
model: opus                      # 이 스킬에서만 다른 모델 사용
context: fork                    # 서브에이전트에서 실행 (실습 5)
agent: Explore                   # 서브에이전트 타입 (실습 5)
paths: "src/**/*.ts"             # 특정 파일 작업 시 자동 활성화
---

이번 실습에서는 호출 제어와 도구 제한을 체험합니다.

직접 해보기 A: 호출 제어 (deploy)

배포처럼 위험한 작업은 Claude가 자동으로 실행하면 안 됩니다.
disable-model-invocation: true를 쓰면 사용자가 직접 /deploy를 입력해야만 실행됩니다.

Step 1. 폴더 만들기

mkdir -p .claude/skills/deploy

Step 2. .claude/skills/deploy/SKILL.md 작성

---
description: 운영 서버 배포 (빌드 검증 포함)
disable-model-invocation: true
---
운영 서버 배포를 진행합니다.

## 현재 상태
!`git status --short`
!`git branch --show-current`

## 절차
1. 커밋 안 된 변경사항이 있으면 경고하고 중단
2. main 브랜치가 아니면 경고
3. npm run build 실행하여 빌드 검증
4. 성공 시 ./deploy.sh 실행 여부를 사용자에게 확인

Step 3. 두 가지 비교해보기

• /deploy 직접 입력 → 실행됨
• Claude에게 "배포해줘"라고 말하기 → 이 스킬을 자동 호출하는가?

핵심 차이:

설정	사용자 /deploy	Claude "배포해줘" 자동 호출
기본값	O	O
disable-model-invocation: true	O	X
user-invocable: false	X	O

직접 해보기 B: 도구 제한 (safe-check)

allowed-tools에 없는 도구는 사용 못합니다. 검사 스킬이 실수로 코드를 수정하는 걸 막을 때 유용합니다.

Step 1. 폴더 만들기

mkdir -p .claude/skills/safe-check

Step 2. .claude/skills/safe-check/SKILL.md 작성

---
description: 코드 읽기만 하는 안전한 검사 (수정 불가)
allowed-tools: Read, Grep, Glob
---
다음 경로의 코드를 검사해주세요: $ARGUMENTS

검사 항목:
1. sanitizeHtml() 누락 여부
2. Zustand 스토어 전체 구독 여부
3. await가 붙은 분석 로깅 여부

코드를 수정하지 말고 문제점만 보고해주세요.

Step 3. 테스트

/safe-check src/chatbot/

확인해보기

• allowed-tools에 Edit, Write가 없으므로 Claude가 코드 수정을 시도하지 않는가?
• Read, Grep, Glob만으로 검사하는가?

---

실습 5: context: fork — 서브에이전트에서 실행

개념

context: fork를 쓰면 스킬이 별도의 에이전트에서 실행됩니다.

fork 없음 (기본):
  현재 대화 → 스킬 실행 → 파일 읽기, 분석 내용이 모두 대화에 쌓임

fork 있음:
  현재 대화 → 결과 요약만 받음
       └── 별도 에이전트 → 파일 읽기, 분석을 내부에서 처리

파일을 많이 읽는 분석 작업에서 현재 대화의 컨텍스트를 아끼고 싶을 때 씁니다.

만드는 법

Step 1. 폴더 만들기

mkdir -p .claude/skills/deep-analyze

Step 2. .claude/skills/deep-analyze/SKILL.md 작성

---
description: 지정한 파일을 서브에이전트에서 심층 분석
argument-hint: [파일경로]
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---
다음 코드를 심층 분석해주세요: $ARGUMENTS

## 분석 항목
1. 파일의 역할과 책임
2. 의존성 관계 (import/export 추적)
3. 핵심 함수의 실행 흐름
4. 잠재적 문제점이나 개선 포인트

Step 3. 테스트

/deep-analyze src/chatbot/hooks/use-chat-search.ts

비교 실험

1. 위 스킬 실행 → 터미널에 서브에이전트 표시 확인
2. SKILL.md에서 context: fork 줄 삭제 후 다시 실행
3. 차이 비교:

	fork 있음	fork 없음
파일 읽기 내용	대화에 안 보임	대화에 다 보임
결과	요약만 돌아옴	전체 과정 포함
대화 컨텍스트 소비	적음	많음

agent 타입 선택 기준

agent 값	특성	언제 쓰나
Explore	읽기 전용, 빠름	코드 분석, 파일 탐색
Plan	설계 중심	구현 방향 결정
general-purpose	제한 없음	코드 수정 포함 작업

---

실습 6: 멀티파일 스킬

개념

SKILL.md 하나로만 쓰면 파일이 너무 길어질 수 있습니다.
같은 폴더에 보조 파일을 두고 SKILL.md에서 참조하면 Claude가 필요할 때 읽어옵니다.

.claude/skills/faq-add/
├── SKILL.md        ← "reference.md 보고 작업해" 라고만 씀
├── reference.md    ← 규칙과 수정 대상 파일 목록
└── examples.md     ← 실제 예시

만드는 법

Step 1. 폴더 만들기

mkdir -p .claude/skills/faq-add

Step 2. 파일 3개 작성

.claude/skills/faq-add/SKILL.md

---
description: FAQ 카테고리 추가 (4개 파일 동시 수정)
argument-hint: [카테고리명] [slug]
---
새로운 FAQ 카테고리를 추가합니다: $ARGUMENTS

## 현재 상태 확인
!`cat src/data/faq/index.ts`
!`head -12 src/data/keywords.ts`

reference.md의 규칙에 따라 4개 파일을 수정해주세요.
examples.md에 실제 예시가 있습니다.

.claude/skills/faq-add/reference.md

# FAQ 카테고리 추가 규칙

## 수정해야 하는 4개 파일

1. `src/data/faq/{slug}.ts` — 카테고리 데이터 파일 생성
2. `src/data/faq/index.ts` — import + faqData 배열 + export 추가
3. `src/data/keywords.ts` — categoryKeywords + subCategoryKeywords 추가
4. `src/chatbot/utils/get-category-icon.tsx` — 아이콘 매핑 추가

## 작성 규칙
- 카테고리 id: 영어 kebab-case
- label: 한국어
- 키워드: 한국어 검색어 배열
- 아이콘: lucide-react에서 선택
- 타입 정의 참고: `src/data/faq/types.ts`

.claude/skills/faq-add/examples.md

# 카테고리 추가 예시

## /faq-add 교육비 tuition 실행 예시

### src/data/faq/tuition.ts
기존 파일(enrollment.ts 등) 구조를 참고해서 생성

### src/data/faq/index.ts
import { tuitionCategory } from "./tuition"
faqData 배열에 tuitionCategory 추가
하단 export에 tuitionCategory 추가

### src/data/keywords.ts
categoryKeywords에 tuition: ["교육비", "비용", "수강료"] 추가

### src/chatbot/utils/get-category-icon.tsx
Coins 아이콘 import 후 icons 객체에 tuition 매핑 추가

Step 3. 테스트

/faq-add 시험정보 exam

확인해보기

• Claude가 reference.md를 읽고 4개 파일을 모두 수정하는가?
• SKILL.md 하나만 쓸 때보다 결과가 더 정확한가?

---

실습 7: 글로벌 스킬

개념

지금까지 만든 스킬은 모두 이 프로젝트에서만 사용 가능합니다.
~/.claude/skills/에 만들면 모든 프로젝트에서 사용할 수 있습니다.

~/.claude/skills/이름/SKILL.md    ← 어디서든 사용 가능
.claude/skills/이름/SKILL.md      ← 이 프로젝트에서만 사용

같은 이름이면 프로젝트 스킬이 우선합니다.

만드는 법

Step 1. 글로벌 폴더 만들기

mkdir -p ~/.claude/skills/summarize

Step 2. ~/.claude/skills/summarize/SKILL.md 작성

---
description: 현재 프로젝트 요약 (어떤 프로젝트든 사용 가능)
---
이 프로젝트를 분석하고 간단히 요약해주세요.

## 프로젝트 정보
!`cat package.json 2>/dev/null | head -10 || echo "package.json 없음"`

## 디렉토리 구조
!`ls src/ 2>/dev/null || ls`

## 요약 형식
1. 프로젝트 이름과 용도
2. 사용 중인 주요 기술 스택
3. 디렉토리 구조 간략 설명

2>/dev/null은 명령어가 실패해도(파일이 없어도) 에러 메시지 없이 넘어가도록 하는 설정입니다.

Step 3. 여러 프로젝트에서 /summarize 실행 → 어디서든 동작하는지 확인

---

치트시트

frontmatter 옵션 전체

옵션	예시 값	설명
description	"파일 설명 스킬"	자동완성 설명
argument-hint	[파일경로]	입력 힌트
disable-model-invocation	true	사용자만 호출 가능
user-invocable	false	Claude만 호출 가능
allowed-tools	Read, Grep, Glob	사용 가능 도구 제한
model	opus	모델 오버라이드
context	fork	서브에이전트 실행
agent	Explore	서브에이전트 타입
paths	"src/**/*.ts"	자동 활성화 경로

변수

변수	동작	예시
$ARGUMENTS	입력 전체를 삽입	/cmd 전체 텍스트
$0, $1	공백 기준 개별 인자	/cmd arg0 arg1
!`command`	셸 명령 결과를 삽입 (전처리)	!`git diff`
${CLAUDE_SKILL_DIR}	스킬 폴더 경로	보조 스크립트 경로

---

다음 단계

스킬을 익혔다면:

• Agents — 스킬보다 복잡한 전문 에이전트 작성 (.claude/agents/)
• Hooks — 이벤트 기반 자동화 (코드 저장 시 자동 검사 등)
• Output Styles — 응답 스타일 커스터마이징