"Claude Code Skills 사용 방법 : 기본 개념 및 기초 사용방법 정리 (반복되는 프롬프트를 스킬로 변환 해보자)

안녕! 갓대희다.

오늘은 Claude Code 사용자라면 꼭 알아야 할 "Claude Skills" 빌딩 가이드에 대해 알아보려 한다.

예전에 스킬에 대해 글을 작성한 지 오래되었고, Skills도 계속 변경되는데 현재 시점(2026.02월)에서의 활용 방법에 대해 다시 한번 정리하고 넘어가려 한다.

( 클로드 스킬이 처음 나왔을 시기에 작성했던 글도 참고 )

클로드 스킬(Claude Skills) 사용방법 - Docs,Pptx,Xlsx 스킬 활용 + Custom Skill 등록 해보기

Claude Code기준 Skills와 Plugins의 차이점 이해하기 : 언제 무엇을 사용할까?

Claude를 사용하다 보면 자주 반복하는 프롬프트 패턴이 있기 마련이다. 매번 같은 지시를 다시 입력하는 대신, 이를 Skill로 패키징하여 재사용할 수 있다. 이 가이드는 Skills를 구축하는 방법을 다룬다.

목차

1. Claude Skills란 무엇인가
   • Skills의 정의와 목적
   • Model-invoked vs User-invoked 
   • 자동 설치 및 도구 노출
2. SKILL.md 파일 구조 상세
   • YAML Frontmatter (프론트 매터) 
   • 자동 트리거 (Auto-triggers) 동작 방식 
   • allowed-tools: 도구 접근 제어 
3. 첫 스킬 10분 완성
   • Step-by-step 튜토리얼
   • 실시간 테스트 방법
4. 디렉토리 구조 가이드
   • 개인 vs 프로젝트 스킬
   • 저장 위치 추천
5. 스킬 테스트 & 디버깅
   • 자동 호출 테스트
   • 흔한 문제 & 해결법
6. 스킬 테스트 전략 및 반복 개발
   • 테스트 피라미드 접근법
   • MVP 접근법
   • 테스트 우선 개발 (Test-First)
   • 반복적 개발 워크플로우
7. Skills vs Plugins vs Slash Commands 선택 가이드
   • 의사결정 트리
   • 상황별 추천
8. Skill 구조 이해하기
   • 작성 프롬프트 (Composition Prompt)
   • 공급자 프롬프트 (Provider Prompt)
9. 작성 프롬프트: 3단계 구조
   • 목적 (Purpose)
   • 명세 (Specification)
   • 리팩터링 (Refinement)
10. 공급자 프롬프트의 핵심
    • 도구 활용 가이드
    • discovery 메커니즘
    • 설치 방법 안내
11. 작성 가이드라인
12. 실전 레시피
13. 고급 패턴과 베스트 프랙티스
14. 스킬 배포와 공유
    • 배포 채널 비교
    • 시맨틱 버전 관리
    • 스킬 공유 구조
15. 초급자를 위한 실전 예시
16. 트러블슈팅 및 FAQ
17. 참고 자료

Claude Skills 빌 가이드
Claude Skills는 자주 사용하는 프롬프트와 도구를 패키징하여 재사용 가능한 기능이다. SKILL.md 파일 형식으로 구성되며 YAML frontmatter와 Markdown 본문으로 작성한다. 이 글에서는 기본 개념부터 실전 레시피까지 단계별로 안내한다.

 

1. Claude Skills란 무엇인가

Claude Skills는 Claude 사용자가 자주 사용하는 프롬프트 패턴과 도구를 패키징한 재사용 가능한 단위이다.

쉽게 말해, "이런 상황에서는 이렇게 대답해"라는 규칙을 미리 정의해두는 것과 같다.

핵심: Model-invoked vs User-invoked

Skill의 가장 큰 특징은 자동 호출이다. 사용자가 명령어를 입력하지 않아도, Claude가 스스로 "아, 이건 커밋 메시지 만들어달라는 거구나!"라고 이해하고 자동으로 commit-helper 스킬을 활성화한다.

특징	Skills (Model-invoked)	Slash Commands (User-invoked)
호출 주체	Claude (Model) 의도를 자동으로 파악	사용자 (User) 명시적으로 입력
사용 방법	"커밋해줘" → 자동 호출	/commit-helper
핵심 메커니즘	description 필드의 의미적 분석	명령어 이름 매칭

실제 동작 예시:
사용자: "커밋 메시지 만들어줘"
↓
Claude: "description을 분석하니... 'commit', '커밋', '커밋 메시지' 키워드가 있네! commit-helper 스킬 자동 활성화!"
↓
결과: 커밋 메시지 생성 시작 (사용자가 /skill commit-helper 입력할 필요 없음)

 

Skills의 정의와 목적

Claude를 사용하다 보면 반복적으로 사용하는 패턴이 있다:

• 코드 리뷰할 때마다 같은 체크리스트를 설명한다
• 문서를 작성할 때마다 동일한 포맷을 요청한다
• 특정 도구 사용 방법을 매번 설명한다

Skills는 이런 반복되는 상호작용 패턴을 캡슐화하여, 매번 긴 프롬프트를 입력하지 않아도 되게 해준다.

CLAUDE.md와의 차이점

CLAUDE.md는 프로젝트 규칙과 지침을 저장하는 정적 파일이다. 반면 Skills는 동적이고 상황에 맞춰 호출될 수 있다. 사용자가 /skill my-skill 명령어로 필요할 때만 활성화할 수 있다.

 

자동 설치 및 도구 노출

Skills의 가장 큰 장점은 자동 설치와 도구 자동 노출 기능이다.

기능	설명	예시
자동 설치	사용자가 /skill 호출 시 자동으로 설치	/skill code-review → 자동 설치
도구 자동 노출	Skill에 포함된 도구를 Claude가 자동 인식	파일 읽기 도구가 자동으로 사용 가능
on-demand 호출	필요할 때만 활성화	특정 작업 시에만 skill 사용

Skills 핵심 기능

• 패키징: 프롬프트와 도구를 하나로 묶기
• 자동 설치: 사용자가 호출하면 자동으로 설치
• 도구 노출: Claude가 관련 도구를 자동 인식
• 재사용성: 여러 세션에서 반복 사용

 

2. SKILL.md 파일 구조 상세

Skill 파일은 YAML Frontmatter와 Markdown 본문으로 구성된다. 가장 중요한 것은 description 필드dlek.

 

2.1 YAML Frontmatter (프론트 매터)

프론트 매터는 파일 맨 위에 ---로 감싸진 YAML 형식의 메타데이터다. 이 부분이 자동 트리거의 핵심이다.

// SKILL.md 기본 구조

---
# 필수 필드
name: my-skill                    # 스킬 식별자 (영어, 소문자, 하이픈 권장)
description: "..."                # 가장 중요하다! 자동 트리거 결정

# 선택 필드
allowed-tools:                    # 도구 접근 제한 (보안용)
  - "Read"
  - "Write"
  - "Bash"
---

 

description 필드: 자동 트리거의 핵심

description은 Claude가 사용자 의도를 파악하여 자동으로 스킬을 활성화하는 데 사용된다. 50-200자 권장

# 실제 예시: commit-helper 스킬 description: Use this skill when user mentions "commit", "커밋", "커밋 메시지", "git commit" or wants to create a commit message for generating structured commit messages following project conventions (Korean/English, with/without body).

좋은 description 구조:

1. 핵심 기능: 무엇을 하는가?
2. 사용 시기: 언제 사용하는가?
3. 명시적 키워드: "Keywords: ..." 형식
4. 다국어 지원: 영어 + 한국어 키워드 혼용

 

2.2 자동 트리거 (Auto-triggers) 동작 방식

Claude는 다음 세 가지 방식으로 사용자 의도를 파악한다:

방식	설명	예시
의미적 분석	전체 문맥을 이해하여 의도 파악	"기능을 계획해줘" → planner-skill
키워드 매칭	description의 명시적 키워드	"커밋" → commit-helper
다국어 지원	한국어 + 영어 혼용 지원	"바이브 코딩", "vibe coding"

실제 자동 트리거 예시

planner-skill 스킬

description: "Creates phase-based plans with quality gates... Keywords: plan, planning, phases, breakdown, strategy, roadmap, organize, structure, outline."

자동 호출되는 경우:

• "이 기능을 계획해줘"
• "로드맵 작성 도와줘"
• "태스크를 단계별로 분리하고 싶어"

바이브 코딩 스킬 (한국어 지원)

description: "바이브 코딩 AI 컨설턴트 - 코딩 경험 없는 초보자를 위한 1:1 기획 가이드... Keywords: 바이브코딩, vibe coding, 기획, planning, MVP, 초보자, beginner, 아이디어"

자동 호출되는 경우:

• "바이브 코딩으로 기획 도와줘"
• "초보자를 위한 기획 가이드"
• "아이디어를 MVP로 구체화하고 싶어"

 

2.3 allowed-tools: 도구 접근 제어

allowed-tools는 스킬이 사용할 수 있는 도구를 제한한다. 선택적 필드이지만, 보안이 필요한 경우 권장된다.

// 실제 shadcn-ui 스킬 예시

---
name: shadcn-ui
description: "Expert guidance for integrating shadcn/ui..."
allowed-tools:
  - "shadcn*:*"       # 와일드카드: shadcn로 시작하는 모든 도구
  - "mcp_shadcn*"     # MCP 서버의 shadcn 관련 도구
  - "Read"            # 기본 도구들
  - "Write"
  - "Bash"
  - "web_fetch"
---

패턴	의미	예시
"shadcn*:*"	와일드카드: shadcn로 시작하는 모든 도구	shadcn:add, shadcn:init 등
"mcp_*"	모든 MCP 서버 도구	mcp_memory, mcp_sequential 등
"Read"	특정 기본 도구	Read 도구만 허용

 

3. 스킬 만들어 보기

이제 실제로 스킬을 만들어보자.

목표: "안녕" 스킬 만들기

사용자가 "안녕"이라고 하면 한국어로, "hello"라고 하면 영어로 인사하는 간단한 스킬이다.

Step 1: 디렉토리 생성

// 터미널에서 실행

# 개인 스킬 디렉토리 생성
mkdir -p ~/.claude/skills/hello-skill

# 생성 확인
ls -la ~/.claude/skills/

 

Step 2: SKILL.md 파일 생성 (7분)

VS Code나 텍스트 편집기로 파일을 만들자.

// ~/.claude/skills/hello-skill/SKILL.md

---
name: hello-skill
description: "Greets users appropriately. 한국어로 '안녕', 'hello'라고 하면 자동으로 인사한다. Use when user says 안녕, hello, hi, greeting. Keywords: 안녕, hello, hi, greeting, 인사, hello-skill."
---

# Hello Skill

## 자동 호출 트리거
안녕, hello, hi, greeting, 인사

## 작동 방식

### 한국어 감지
사용자가 "안녕"이라고 하면:
- "안녕! 반갑다. 오늘도 좋은 하루 되길!"

### 영어 감지
사용자가 "hello", "hi"라고 하면:
- "Hello! Nice to meet you. Have a great day!"

### 기타 언어
그 외의 언어로는:
- "Hello! / 안녕!" (이중 인사)

저장 확인

~/.claude/skills/hello-skill/SKILL.md

이 경로에 파일이 저장되었는가?

 

Step 3: 테스트 (2분)

Claude Code에서 다음과 같이 입력해보자.

// Claude Code 대화창에서

사용자: 안녕

Claude: 안녕! 반갑다. 오늘도 좋은 하루 되길!
        (hello-skill이 자동으로 활성화됨)

동작하지 않나요?

다음을 확인해보세요:

1. 파일 경로가 정확한가요? (~/.claude/skills/hello-skill/SKILL.md)
2. 파일 이름이 SKILL.md인가요? (대문자 필수)
3. YAML 형식이 올바른가요? (---로 감싸져 있나요?)
4. Claude Code를 재시작했나요?

 

4. 디렉토리 구조 가이드

스킬을 어디에 둘지 혼동스러울 수 있다. 명확히 정리해보자.

두 가지 저장 위치

위치	경로	사용 범위	추천 용도
개인 (Global)	~/.claude/skills/	모든 프로젝트에서 사용 가능	개인용 스킬, 범용적 도구
프로젝트 (Local)	.claude/skills/	해당 프로젝트에서만 사용	프로젝트 특화 스킬

 

실제 디렉토리 구조

# 실제 예시 (개인 스킬)
~/.claude/skills/
├── commit-helper/              # 커밋 메시지 생성
│   └── SKILL.md
├── feature-planner/             # 기능 계획
│   ├── SKILL.md
├── code-review-assistant/       # 코드 리뷰
│   └── SKILL.md
└── my-custom-skill/             # 나만의 스킬
    └── SKILL.md

# 프로젝트 스킬
/my-project/
├── .claude/
│   └── skills/
│       └── project-specific/    # 이 프로젝트만의 스킬
│           └── SKILL.md
├── src/
└── README.md

추천 저장 위치

• 범용 스킬 (commit-helper, 코드 리뷰 등): ~/.claude/skills/
• 프로젝트 스킬 (프로젝트별 컨벤션, 도메인 지식): .claude/skills/
• 팀 공유 스킬: Git으로 관리하거나 팀 내부 공유 폴더 사용

 

5. 스킬 테스트 & 디버깅

스킬이 제대로 작동하는지 확인하는 방법이다.

 

5.1 자동 호출 테스트

description에 명시한 키워드로 테스트해보자:

// 테스트 예시: commit-helper 스킬

# 테스트 1: 직접 언급
"커밋해줘" → commit-helper 스킬이 자동 활성화되어야 함

# 테스트 2: 키워드 포함
"커밋 메시지 만들어줘" → commit-helper 스킬이 자동 활성화되어야 함

# 테스트 3: 영어 혼용
"create commit message" → commit-helper 스킬이 자동 활성화되어야 함

 

5.2 수동 호출 테스트

명시적으로 스킬을 호출해서 테스트할 수도 있다.

// 스킬 명시적 호출

# 스킬 명시적 호출
/skill commit-helper

# 스킬 목록 확인
/skill list

ex) 그냥 편하게 명시적으로 스킬이름을 지정해두었다면, 자연어로 요청해도 가능하다. 

 - Skill(commit-helper) 가 호출된것을 볼 수 있다.

 

5.3 흔한 문제 & 해결법

문제	증상	해결법
파일 못 찾음	"Skill not found"	경로 확인: ~/.claude/skills/스킬이름/SKILL.md
자동 호출 안 됨	키워드로 반응 없음	description이 50자 이상인지 확인
YAML 에러	파싱 오류	---로 감싸져 있는지, 들여쓰기 확인
잘못된 스킬 활성화	다른 스킬이 활성화됨	description을 더 구체적으로 수정

디버깅 팁

1. 간단한 description으로 시작: 복잡한 스킬은 간단하게 시작해서 점진적으로 확장
2. 로그 확인: Claude Code의 로그에서 스킬 로딩 메시지 확인
3. 다른 스킬 비활성화: 충돌을 피하기 위해 일시적으로 다른 스킬 제거
4. 재시작: 스킬 파일 수정 후 Claude Code 재시작

 

6. 스킬 테스트 전략 및 반복 개발

스킬을 개발할 때 체계적인 테스팅 전략과 반복적 개발 방법론을 적용하면 품질이 높고 유지보수가 쉬운 스킬을 만들 수 있다.

 

6.1 테스트 피라미드 접근법

스킬 테스트는 테스트 피라미드 방식으로 구성하는 것이 효과적이다.
기본 단위에서 시작하여 점진적으로 통합 및 사용자 수준 테스트로 확장해 나간다.

테스트 레벨	목적	실행 빈도
단위 테스트	개별 스킬 단계 검증	코드 변경 시마다
통합 테스트	스킬 간 상호작용 검증	커밋 시마다
UAT	실제 사용자 시나리오 검증	릴리스 전

 

6.2 MVP 접근법 (Minimum Viable Product)

스킬 개발 시 MVP 접근법을 사용하여 빠르게 피드백을 받고 반복한다. 완벽한 스킬을 만드는 대신, 핵심 기능만 먼저 구현하고 점진적으로 개선한다.

MVP 단계	목표	기간	성공 기준
v0.1	기본 기능 검증	1-2시간	핵심 단계가 실행됨
v0.5	오류 처리 추가	하루	일반적인 오류를 처리함
v1.0	문서화와 테스트	2-3일	팀원들이 사용 가능
v2.0+	고급 기능 추가	지속적	사용자 피드백 반영

 

6.3 테스트 우선 개발 (Test-First)

스킬을 구현하기 전에 테스트를 먼저 작성하는 방식이다. 이 방식은 스킬의 요구사항을 명확히 하고, 구현 시 실수를 방지하며, 리팩토링을 안전하게 만든다.

// 테스트 우선 개발 프로세스

1. 요구사항 정의
   └─ "배포 스킬은 빌드 실패 시 자동으로 롤백해야 한다"

2. 실패하는 테스트 작성
   └─ build_fail_rollback_test.yaml 작성
   └─ 테스트 실행 (당연히 실패)

3. 최소한의 구현
   └─ 롤백 로직만 구현
   └─ 테스트 통과 확인

4. 리팩토링
   └─ 코드 개선
   └─ 테스트 여전히 통과

5. 반복
   └─ 다음 요구사항으로 이동

 

6.4 반복적 개발 워크플로우

스킬 개발은 한 번에 완성하는 것이 아니라, 짧은 주기로 반복하며 개선한다. 각 반복에서 사용자 피드백을 수집하고 스킬을 발전시킨다.

반복 단계	활동	산출물	다음 단계 진입 조건
Plan	다음 기능 계획	이슈 목록	우선순위 합의
Develop	기능 구현	작동하는 코드	단위 테스트 통과
Test	테스트 수행	테스트 결과	모든 테스트 통과
Deploy	배포 및 모니터링	배포된 버전	치명적 버그 없음
Feedback	사용자 피드백 수집	개선점 목록	다음 반복 계획

흔한 실수 피하기

• 과잉 엔지니어링: MVP에서 완벽을 기하려 하지 마라
• 테스트 건너뛰기: "시간이 없어서"는 변명이 아니다
• 피드백 무시: 사용자가 원하지 않는 기능을 만들지 마라
• 너무 긴 반복: 2주 이상의 반복은 피드백이 늦어진다

테스트 우선 개발의 이점

• 명확한 요구사항: 테스트가 곧 문서가 된다
• 빠른 피드백: 구현 전에 설계 오류를 발견한다
• 안전한 리팩토링: 테스트가 안전망이 된다
• 자신 있는 배포: 모든 테스트 통과 = 배포 준비 완료

 

7. Skills vs Plugins vs Slash Commands 선택 가이드

언제 무엇을 사용할지 혼동스러울 수 있다. 의사결정 트리를 참고하자!.

의사결정 트리

시작
  │
  ├─ 다른 사람과 공유해야 하나요?
  │   ├─ 예 → Plugin (마켓플레이스 배포)
  │   └─ 아니오 → 계속
  │
  ├─ 복잡한 다기능이 필요한가요?
  │   ├─ 예 (Commands + Agents + Skills + MCP) → Plugin
  │   └─ 아니오 → 계속
  │
  ├─ 자동 호출이 필요한가요?
  │   ├─ 예 (사용자 의도 파악) → Skill
  │   └─ 아니오 → 계속
  │
  └─ 빠른 실행이 필요한가요?
      ├─ 예 (/명령어 입력) → Slash Command
      └─ 아니오 → SKILL.md 파일에 지침 작성

 

상황별 추천 선택

상황	추천	이유
커밋 메시지 생성	Skill	"커밋해줘"로 자동 호출
팀 표준 작업 환경	Plugin	여러 컴포넌트 번들, 팀 공유
간단한 설정 변경	Slash Command	/set-theme, /toggle-feature
코드 리뷰 자동화	Skill	"리뷰해줘"로 자동 호출
외부 API와 통합	Plugin	MCP 서버 + Hooks + Skill 번들

 

8. Skill 구조 이해하기

Claude Skill은 두 가지 핵심 프롬프트로 구성된다:

• 작성 프롬프트 (Composition Prompt): Claude에게 skill을 작성하도록 지시
• 공급자 프롬프트 (Provider Prompt): 설치 방법과 discovery를 담당

 

작성 프롬프트 (SKILL.md)

작성 프롬프트는 SKILL.md 파일로 작성된다. 이는 Claude에게 skill을 작성하도록 지시하는 프롬프트다.

SKILL.md 구조

참고: 이 가이드의 "Purpose, Specification, Refinement" 3단계 구조는
PDF "The Complete Guide to Building Skill for Claude"에서 제안하는 프롬프트 작성 방법론이다.
Anthropic의 공식 문서에서는 SKILL.md 파일 구조를 사용한다.

// 작성 프롬프트의 기본 구조

당신은 skill 작성 전문가다.

다음 요구사항에 맞는 skill을 작성하라:

1. 이 skill은 무엇인가? (Purpose)
2. 어떻게 동작하는가? (Specification)
3. 왜 이렇게 작성했는가? (Refinement)

 

공급자 프롬프트 (Agent 정의)

공급자 프롬프트는 skill이 설치되는 방법과 도구 discovery를 담당한다.

공식 용어 참고

참고: "Provider Prompt"는 PDF에서 사용하는 용어다.
Anthropic 공식 문서에서는 Agent 정의 (.md 파일)를 사용한다.
이 가이드에서는 PDF의 용어를 따르되, 공식 용어와의 차이를 명시한다.

// 공급자 프롬프트의 기본 구조

이 skill을 설치하려면:

1. 설치 방법: [설치 단계]
2. 도구 discovery: [도구 목록 확인 방법]
3. 사용 방법: [사용 예시]

핵심 원칙: 도구 활용 유도

공급자 프롬프트의 핵심은 Claude가 도구를 적극적으로 활용하도록 유도하는 것이다. 단, tool은 필수 요소가 아니다. 많은 skill이 도구 없이 프롬프트 지침만으로 작동할 수 있다. 도구가 필요한 경우에는 allowed-tools로 명시적으로 제한할 수 있다.

 

9. 작성 프롬프트: 3단계 구조

작성 프롬프트는 목적, 명세, 리팩터링의 3단계로 구조화된다.

 

Step 1: 목적 (Purpose)

"이 skill은 무엇을 합니까?"를 명확히 정의한다.

// 목적 정의 예시

// Good: 명확한 목적
"이 skill은 코드 리뷰를 수행한다.
보안 취약점, 성능 문제, 코드 스타일을 검사한다."

// Bad: 모호한 목적
"이 skill은 코드를 봅니다."

 

Step 2: 명세 (Specification)

"어떻게 동작합니까?"를 구체적으로 정의한다. 도구 정의가 포함된다.

// 명세 정의 예시

다음 도구를 제공한다:

1. review_code(file_path): 코드를 검사하고 보고서 생성
2. check_security(file_path): 보안 취약점 스캔
3. suggest_improvements(file_path): 개선사항 제안

각 도구는 분석 결과를 구조화된 JSON으로 반환한다.

 

Step 3: 리팩터링 (Refinement)

"왜 이렇게 작성했는가?"를 설명한다. 작성 이유와 설계 결정을 포함한다.

// 리팩터링 예시

설계 결정:
- 도구를 3개로 분할: 단일 책임 원칙 준수
- JSON 반환: 구조화된 데이터 처리 용이
- 개별 검사 함수: 재사용성과 테스트 용이성

이 구조는 다른 skill에서도 재사용할 수 있다.

3단계 구조의 장점

이 구조는 Claude에게 다음을 보장한다:
- 무엇을 만들어야 하는지 명확히 이해
- 어떻게 구현할지 구체적 가이드
- 왜 이렇게 설계했는지 맥락 이해

 

10. 공급자 프롬프트의 핵심

공급자 프롬프트는 skill이 실제로 사용되도록 만드는 핵심이다.

 

도구 활용 가이드

skill에 도구가 필요한 경우, Claude가 도구를 호출하도록 유도해야 한다. 단, 도구는 선택적 요소다.

// SKILL.md 예시 (도구 포함)

// Good: 도구 호출 유도
"코드를 검사하려면 먼저 read_file 도구를 호출하여
파일 내용을 읽어야 한다."

// Bad: 설명만 함
"코드를 검사할 때는 파일 내용을 확인하라."

구분	도구 호출 유도 (Good)	설명만 (Bad)
파일 읽기	"read_file 도구를 호출하라"	"파일을 읽어보세요"
파일 쓰기	"write_file 도구로 저장하라"	"파일에 내용을 저장하라"
검색	"search 도구를 사용하라"	"내용을 찾아보세요"

 

discovery 메커니즘

discovery는 공급자에게 "어떤 도구를 제공합니까?"라고 묻는 과정이다.

// discovery 구현 예시

사용자: "이 skill은 무엇인가?"
공급자: "이 skill은 다음 도구를 제공한다:
- read_file: 파일 내용 읽기
- write_file: 파일에 내용 쓰기
- search_files: 파일 검색

어떤 도구를 사용하겠는가?"

 

설치 방법 안내

사용자가 skill을 쉽게 설치할 수 있도록 명확한 가이드를 제공해야 한다.

// 설치 방법 예시

설치 방법:
1. 이 프롬프트를 복사한다
2. Claude Code에서 /skill install 을 입력한다
3. 프롬프트를 붙여넣는다
4. 설치가 완료되면 자동으로 도구가 사용 가능하다

 

11. 작성 가이드라인

효과적인 skill을 작성하기 위한 핵심 가이드라인이다.

가이드라인	설명	예시
작은 도구로 분해	하나의 도구는 하나의 일만	read_file + write_file 분리
명확한 이름	도구 이름은 동사로 시작	analyze_code (good), code (bad)
명확한 목적	도구가 무엇을 하는지 명시	"보안 취약점을 스캔한다"
도구 우선	설명보다 도구 호출을 먼저	"read_file 도구를 호출하라"

핵심 가이드라인 요약

• 작은 도구: 단일 책임 원칙
• 명확한 이름: 동사 + 명사
• 명확한 목적: 한 문장으로 설명 가능
• 도구 우선: 설명보다 도구 호출 먼저

 

12. 실전 레시피

자주 사용되는 skill 패턴과 레시피다.

 

레시피 1: 파일 조작

파일을 읽고, 쓰고, 수정하는 기본적인 skill이다.

// 파일 조작 skill 예시

도구:
- read_file(path): 파일 내용 읽기
- write_file(path, content): 파일에 내용 쓰기
- edit_file(path, old_text, new_text): 파일 내용 편집

사용 예시:
1. read_file 도구로 config.yaml 읽기
2. edit_file 도구로 설정 수정
3. write_file 도구로 변경사항 저장

 

레시피 2: MCP 서버 관리

MCP(Model Context Protocol) 서버를 관리하는 skill이다.

// MCP 서버 관리 skill 예시

도구:
- list_mcp_servers(): 설치된 MCP 서버 목록
- add_mcp_server(name, config): MCP 서버 추가
- remove_mcp_server(name): MCP 서버 제거
- test_mcp_server(name): 서버 연결 테스트

사용 예시:
1. list_mcp_servers 도구로 현재 서버 확인
2. add_mcp_server 도구로 새 서버 추가
3. test_mcp_server 도구로 연결 확인

 

레시피 3: 파일 검색

코드베이스에서 파일을 검색하는 skill이다.

// 파일 검색 skill 예시

도구:
- search_files(query, path): 파일 내용 검색
- find_files(pattern, path): 파일 이름으로 검색
- grep_files(regex, path): 정규식으로 검색

사용 예시:
1. search_files 도구로 "TODO" 문자열 검색
2. find_files 도구로 "*.test.ts" 파일 찾기
3. grep_files 도구로 함수 정의 패턴 찾기

 

레시피 4: 코드 베이스 탐색

대규모 코드베이스를 탐색하는 skill이다.

// 코드베이스 탐색 skill 예시

도구:
- explore_directory(path): 디렉토리 구조 탐색
- analyze_imports(file_path): import 의존성 분석
- find_usages(symbol, path): 심볼 사용처 찾기
- get_call_graph(file_path): 함수 호출 그래프 생성

사용 예시:
1. explore_directory 도구로 프로젝트 구조 파악
2. analyze_imports 도구로 의존성 확인
3. find_usages 도구로 함수 사용처 추적

팁

• 레시피를 조합하여 더 복잡한 skill 만들기
• 각 도구는 독립적으로 테스트 가능하도록 설계
• 명확한 사용 예시를 항상 포함

 

13. 고급 패턴과 베스트 프랙티스

더 복잡한 skill을 작성하기 위한 고급 패턴이다.

 

패턴 1: 도구 체이닝

여러 도구를 순차적으로 호출하는 패턴이다.

// 도구 체이닝 예시

// 체이닝 순서:
1. read_file 도구로 파일 읽기
2. analyze_code 도구로 분석
3. generate_report 도구로 보고서 생성
4. write_file 도구로 보고서 저장

각 도구의 출력이 다음 도구의 입력이 된다.

 

패턴 2: 조건부 도구 호출

상황에 따라 다른 도구를 호출하는 패턴이다.

// 조건부 도구 호출 예시

// 파일 확장자에 따른 조건부 호출:
if (file.endswith('.ts')) {
    analyze_typescript_file 도구 호출
} else if (file.endswith('.py')) {
    analyze_python_file 도구 호출
} else {
    generic_file_analysis 도구 호출
}

 

베스트 프랙티스

베스트 프랙티스	설명	이유
도구 최소화	필수적인 도구만 포함	복잡성 감소
명확한 에러 처리	에러 메시지 구체화	디버깅 용이
문서화	각 도구의 사용 예시 포함	사용성 향상
테스트 가능성	각 도구를 독립적으로 테스트 가능	신뢰성 향상

 

멀티 에이전트 패턴 (Multi-Agent Pattern)

복잡한 작업을 여러 전문화된 스킬로 분할하고, 각각이 특정 역할을 수행하게 하는 패턴이다.

멀티 에이전트 패턴 사용 시기

• 작업이 독립적: 서로 다른 모듈/서비스를 병렬로 처리
• 전문 분야 필요: 각 부분에 특화된 지식이 필요
• 확장성 요구: 에이전트를 쉽게 추가/제거해야 할 때

재귀 패턴 (Recursive Pattern)

스킬이 자기 자신을 호출하여 문제를 더 작은 하위 문제로 분할하고 해결하는 패턴이다. 주로 복잡한 디렉터리 구조, 중첩된 설정 처리에 사용된다.

 

상태 유지 패턴 (Stateful Pattern)

스킬 실행 간에 상태를 유지하여, 이전 실행의 결과를 참조하거나 점진적으로 작업을 수행하는 패턴이다. 장기 실행 작업, 점진적 롤아웃에 적합하다.

 

스트리밍 패턴 (Streaming Pattern)

대량의 데이터를 처리할 때 결과를 기다리지 않고, 실시간으로 결과를 스트리밍하여 사용자에게 즉각적인 피드백을 제공하는 패턴이다.

 

안티패턴 (Anti-Patterns)

피해야 할 일반적인 실수들과 그 해결책이다.

안티패턴	문제	대안
God Skill	모든 것을 하나의 스킬에 구현	단일 책임 스킬로 분할
Silent Failures	오류가 조용히 무시됨	명시적 에러 처리
No Validation	입력 검증 없음	파라미터 검증

안티패턴 감지 체크리스트

• 스킬이 10개 이상의 단계를 가지고 있는가?
• 환경별로 다른 버전의 스킬이 있는가?
• 오류 발생 시 원인을 파악하기 어려운가?
• 다른 프로젝트에서 재사용하기 어려운가?

위 질문 중 하나라도 "예"라면 리팩토링을 고려하세요.

 

14. 스킬 배포와 공유

스킬을 개발한 후에는 팀원들과 공유하거나 커뮤니티에 공개할 수 있다.

 

배포 채널 비교

배포 채널	적합한 경우	장점
Git 저장소	팀 내부 공유, 오픈소스	버전 관리, 협업 용이
로컬 파일	개인용, 빠른 테스트	간단함, 즉시 사용 가능
팀 공유 스킬	소규모 팀	Git으로 관리하거나 내부 공유 폴더 사용

 

시맨틱 버전 관리 (Semantic Versioning)

스킬 버전은 시맨틱 버전 관리(SemVer)를 따른다. 형식: MAJOR.MINOR.PATCH

버전 변화	의미	예시
1.0.0 → 2.0.0	호환되지 않는 변경	파라미터 형식 변경
1.0.0 → 1.1.0	하위 호환 기능 추가	--verbose 플래그 추가
1.0.0 → 1.0.1	하위 호환 버그 수정	오타 수정

 

스킬 공유 구조

my-shared-skill/
├── skill.md                 # 스킬 정의 (필수)
├── README.md                # 사용자 문서 (권장)
├── CHANGELOG.md             # 변경 이력 (권장)
├── LICENSE                  # 라이선스 (권장)
├── examples/                # 사용 예시
│   ├── basic-usage.md
│   └── advanced-usage.md
└── tests/                   # 테스트
    └── test-skill.md

커뮤니티 스킬 성공 요소

• 명확한 문서화: 설치부터 고급 사용법까지
• 빠른 응답: 이슈와 PR에 신속하게 대응
• 개방적 태도: 기여를 환영하고 격려
• 지속적 개선: 피드백을 반영하여 발전

 

15. 초급자를 위한 실전 예시

예시 1: 간단한 TODO 관리 스킬

"TODO 찾아줘", "할 일 정리해줘" 같은 요청에 자동으로 응답하는 스킬이다.

// todo-finder/SKILL.md

---
name: todo-finder
description: "Find and organize TODO comments in codebase. Use when user asks to find TODOs, organize tasks, or list pending items. Keywords: TODO, todo, 할일, 정리, 찾기, organize tasks."
---

# TODO Finder

## Purpose
코드베이스에서 TODO 주석을 찾아서 정리해 드린다.

## How It Works

### Step 1: TODO 검색
Grep 도구로 다음 패턴을 검색한다:
- `TODO:`
- `FIXME:`
- `HACK:`

### Step 2: 결과 정리
파일별로 그룹화하여 보고서를 생성한다.

## Example
사용자: "TODO 찾아줘"
→ 이 스킬이 자동으로 활성화되어 TODO 목록을 정리한다.

 

예시 2: 한국어 코드 리뷰 스킬

한국어로 코드 리뷰를 요청할 때 자동으로 활성화되는 스킬이다.

// korean-code-review/SKILL.md

---
name: korean-code-review
description: "한국어로 코드 리뷰를 제공한다. 코드 품질, 성능, 보안을 검사하고 개선 제안을 드린다. Use when user asks for code review, 리뷰, 코드 검토, 개선점. Keywords: 리뷰, review, 코드 검사, 코드 품질, 개선 제안, code review."
allowed-tools:
  - "Read"
  - "Grep"
  - "Glob"
---

# 한국어 코드 리뷰

## 자동 호출 트리거
리뷰, review, 코드 검토, 코드 리뷰, 개선점 찾아줘

## Instructions

### 1. 파일 읽기
먼저 Read 도구로 파일을 읽습니다.

### 2. 검사 항목
- 코드 스타일
- 성능 이슈
- 보안 취약점
- 네이밍 규칙

### 3. 리뷰 작성
한국어로 구체적인 개선 제안을 제공한다.

초급자 팁: description 작성 순서

1. 핵심 기능을 한 문장으로 요약: "TODO를 찾고 정리한다"
2. 사용 시기를 구체적으로: "코드베이스에서 TODO를 검색할 때"
3. 키워드를 영어+한국어로: "Keywords: TODO, todo, 할일"
4. 문맥을 추가: "Use when user asks to find TODOs..."

주의: description이 너무 짧으면 자동 호출이 안 될 수 있다. 50자 이상 권장한다.

 

16. 트러블슈팅 및 FAQ

자주 묻는 문제

Q1: 스킬이 자동으로 호출되지 않아요

가장 흔한 문제다! description 필드를 확인해보자.

나쁜 예 (너무 짧음)

description: "A skill for planning"

문제: "plan"이라는 단어만으로는 의도 파악이 어렵다.

좋은 예 (구체적)

description: "Creates phase-based feature plans with quality gates. Use when planning features, organizing work, breaking down tasks, creating roadmaps. Keywords: plan, planning, phases, breakdown, strategy, roadmap."

장점: 핵심 기능 + 사용 시기 + 명시적 키워드 포함

해결방법:

• description이 50자 이상인지 확인
• 명시적 키워드 포함 (Keywords: ...)
• 한국어 + 영어 키워드 혼용
• Use when...로 사용 시기 명시

 

Q2: 스킬이 의도치 않게 자동 호출돼요

description이 너무 일반적이면, 관련 없는 요청에도 호출될 수 있다.

주의: 너무 일반적인 키워드

description: "Use this skill for code help, analysis, review, or improvements"

문제: "code", "help" 같은 일반적인 단어는 거의 모든 요청에 매칭된다!

해결방법:

• 구체적인 키워드 사용 (예: "conventional commit" 대신 "commit")
• Use when...로 구체적 상황 명시
• "사용하지 말아야 할 경우" 섹션 추가

 

Q3: 한국어 키워드가 작동하지 않아요

실제로는 잘 작동한다! 다만, description에 한국어 키워드를 명시해야 한다. (오래전 예전 버전의 경우 한글 스킬이 잘 트리거 되지 않긴 하였다.)

다국어 스킬 예시

description: "Use when user mentions 'commit', '커밋', '커밋 메시지', 'git commit' or wants to create a commit message..."

이렇게 하면 다음 모두가 자동 호출된다:

• "커밋해줘"
• "commit message 만들어줘"
• "커밋 메시지 생성"

 

Q4: allowed-tools를 꼭 써야 하나요?

아니요, 선택적이다. 기본적으로 스킬은 모든 도구에 접근할 수 있다.

상황	allowed-tools 필요 여부
간단한 프롬프트 스킬	불필요
파일 읽기/쓰기 스킬	불필요
외부 API 호출 스킬	권장
MCP 서버 사용 스킬	권장

 

Q5: Model-invoked가 정확히 뭔가요?

Claude 모델이 스스로 호출한다는 뜻이다. 사용자가 /skill 명령어를 입력할 필요가 없다.

내부 동작 과정

1. 사용자가 요청: "커밋 메시지 만들어줘"
2. Claude가 모든 스킬의 description을 분석
3. 의미적 유사도 계산 (Semantic Similarity)
4. 가장 적합한 스킬 선택: commit-helper
5. 자동 활성화!

이 모든 과정이 0.1초 이내에 자동으로 일어난다!

일반적인 문제

• 스킬이 너무 많으면 의도치 않은 스킬이 활성화될 수 있음
• description이 모호하면 잘못된 스킬이 선택될 수 있음
• 명확하지 않은 목적은 잘못된 결과를 초래할 수 있음

해결방법:

• 도구를 더 작은 단위로 분해
• 각 도구가 하나의 일만 하도록 재구성
• 명세 섹션에서 도구의 역할을 명확히 정의

일반적인 문제

• 도구 호출이 없는 skill은 설명만 하는 경향이 있음
• 너무 많은 도구는 Claude를 혼란스럽게 할 수 있음
• 명확하지 않은 목적은 잘못된 결과를 초래할 수 있음

 

17. 참고 자료

자료	링크
원본 PDF	The Complete Guide to Building Skill for Claude
Claude Code 문서	Anthropic 공식 문서
작성일 기준	2025년 2월 25일

마무리

Claude Skills는 반복되는 프롬프트 패턴을 효과적으로 패키징하는 강력한 방법이다. 이 가이드에서는 자동 트리거 시스템과 Model-invoked 호출 방식의 핵심을 설명했다.

가장 중요한 것은 description 필드다. 잘 작성된 description은 Claude가 사용자 의도를 정확히 파악하여 적절한 스킬을 자동으로 활성화하게 만든다.

초급자를 위한 핵심 요약:

• description은 50-200자로 구체적으로 작성
• 한국어 + 영어 키워드를 모두 포함
• Use when...로 사용 시기를 명시
• Keywords:로 명시적 키워드 목록 제공