Claude Code Agent Skills 완벽 가이드

안녕하세요! 오늘은 Claude Code의 강력한 기능인 Agent Skills에 대해 알아보겠습니다.

개발하다보면 반복적으로 같은 프롬프트를 입력하거나, 팀원들과 특정 워크플로우를 공유하고 싶을 때가 있죠? Agent Skills가 바로 이런 문제를 해결해줍니다.

이 영상 하나면 Skills를 만들고, 테스트하고, 팀과 공유하는 방법까지 모두 배울 수 있습니다. 시작해볼까요?

---

1부: Agent Skills란?

Agent Skills의 정의

Agent Skills는 전문 지식을 발견 가능한 기능으로 패키징하는 시스템입니다.

쉽게 말해, 여러분의 노하우와 워크플로우를 Claude가 자동으로 인식하고 사용할 수 있는 형태로 만드는 거죠.

구성 요소

Skills는 크게 두 가지로 구성됩니다:

1. SKILL.md 파일 - Claude가 읽는 지침 파일입니다. 이게 핵심이에요.
2. 지원 파일 (선택사항) - 스크립트, 템플릿, 예제 파일 등을 추가할 수 있습니다.

일반 명령과의 차이점

여기서 중요한 포인트! Skills는 모델 호출 방식입니다.

슬래시 명령처럼 /command를 직접 입력하는 게 아니라, Claude가 여러분의 요청을 분석해서 자율적으로 적절한 Skill을 선택합니다.

예를 들어, "PDF 양식을 작성해줘"라고 하면 Claude가 알아서 PDF 관련 Skill을 찾아서 사용하는 거죠.

---

2부: 왜 Skills를 사용해야 할까?

핵심 이점 4가지

첫째, 워크플로우 확장 특정 작업에 대한 Claude의 능력을 확장할 수 있습니다. 회사만의 특별한 프로세스도 Skills로 만들 수 있어요.

둘째, 전문 지식 공유 Git을 통해 팀 전체에서 노하우를 공유합니다. 시니어 개발자의 지식을 주니어도 바로 활용할 수 있죠.

셋째, 프롬프팅 감소 매번 같은 설명을 반복할 필요가 없습니다. 한 번 만들어두면 계속 재사용할 수 있어요.

넷째, 복잡한 작업 수행 여러 Skills를 조합해서 복잡한 워크플로우를 자동화할 수 있습니다.

---

3부: Skills 저장 위치 

Skills는 세 가지 위치에 저장할 수 있습니다.

1. 개인 Skills

경로: ~/.claude/skills/

• 모든 프로젝트에서 사용 가능합니다
• 개인 워크플로우나 선호도를 저장하세요
• 실험적인 Skills를 테스트하기에도 좋습니다

사용 예시:

mkdir -p ~/.claude/skills/my-skill

2. 프로젝트 Skills

경로: .claude/skills/ (프로젝트 루트)

• 팀과 공유 가능합니다
• Git으로 버전 관리가 됩니다
• 프로젝트별 전문 지식을 담습니다

사용 예시:

mkdir -p .claude/skills/team-workflow

3. 플러그인 Skills

• Claude Code 플러그인을 통해 배포됩니다
• 설치하면 자동으로 사용 가능합니다
• 가장 전문적인 배포 방법입니다

---

4부: SKILL.md 작성하기

이제 실제로 Skill을 만들어볼까요?

기본 구조

SKILL.md 파일은 YAML frontmatter와 Markdown 콘텐츠로 구성됩니다.

---
name: pdf-form-filler
description: "PDF 양식을 자동으로 작성합니다. 사용자가 'PDF 양식', 'PDF 작성', '양식 채우기'를 언급할 때 사용하세요"
---

# PDF 양식 자동 작성

이 Skill은 PDF 양식을 자동으로 작성합니다.

## 사용 방법

1. PDF 파일을 열어서 필드를 확인합니다
2. 사용자가 제공한 데이터로 각 필드를 채웁니다
3. 완성된 PDF를 저장합니다

## 예제

...

Description 필드가 핵심!

Description은 Claude가 Skill을 발견하는 데 가장 중요한 부분입니다.

좋은 예:

description: "PDF 양식 작성. 'PDF 양식', 'PDF 작성', '양식 채우기'를 언급할 때 사용"

나쁜 예:

description: "문서 처리"  # 너무 모호함!

작성 팁

1. 무엇을 하는지 명확히 작성
2. 언제 사용할지 구체적으로 명시
3. 사용자가 언급할 핵심 키워드를 포함

---

5부: 지원 파일 추가하기

SKILL.md만으로도 충분하지만, 더 강력하게 만들 수 있습니다.

디렉터리 구조

my-skill/
├── SKILL.md
├── scripts/
│   ├── helper.py
│   └── process.sh
├── templates/
│   └── template.json
└── examples/
    └── example-output.txt

스크립트 추가

Python, Shell 등 어떤 스크립트든 추가할 수 있습니다:

# scripts/helper.py
def process_data(input_data):
    # 데이터 처리 로직
    return processed_data

SKILL.md에서 이렇게 참조:

## 사용 방법

`scripts/helper.py`를 사용하여 데이터를 처리합니다:

\`\`\`bash
python scripts/helper.py input.json
\`\`\`

---

6부: allowed-tools로 도구 제한하기

보안이나 안전을 위해 Skill이 사용할 수 있는 도구를 제한할 수 있습니다.

사용 예시

---
name: read-only-analysis
description: "데이터 분석 (읽기 전용)"
allowed-tools:
  - bash_tool
  - view
  - web_search
---

이렇게 하면 str_replace나 create_file 같은 파일 수정 도구는 사용할 수 없습니다.

활용 사례

• 읽기 전용 Skills - 파일 수정 방지
• 데이터 분석만 - 쓰기 작업 제한
• 보안에 민감한 워크플로우 - 필요한 도구만 허용

---

7부: 테스트와 디버깅

Skill을 만들었다면 제대로 작동하는지 테스트해야겠죠?

테스트 방법

1. 설명과 일치하는 질문하기

Description에 "PDF 양식"이라고 했다면:

"이 PDF 양식을 작성해줘"

1. Skill이 활성화되는지 확인

Claude가 해당 Skill을 사용하는지 대화에서 확인합니다.

흔한 문제와 해결법

문제 1: Claude가 Skill을 사용하지 않음

원인: Description이 너무 모호함

나쁜 예:

description: "데이터 도구"

좋은 예:

description: "CSV 파일 분석. 'CSV', '엑셀', '데이터 분석'을 언급할 때 사용"

문제 2: 파일 경로 오류

확인 방법:

# 개인 Skills
ls ~/.claude/skills/my-skill/SKILL.md

# 프로젝트 Skills
ls .claude/skills/my-skill/SKILL.md

문제 3: YAML 구문 오류

YAML frontmatter 확인:

• 1행에 여는 ---
• Markdown 전에 닫는 ---
• 탭 대신 스페이스 사용
• 올바른 들여쓰기

문제 4: 오류 로그 확인

디버그 모드로 실행:

DEBUG=* claude-code

Skill 로딩 오류를 확인할 수 있습니다.

---

8부: 팀과 공유하기

훌륭한 Skill을 만들었다면 팀과 공유해야죠!

방법 1: 플러그인으로 배포 (권장)

가장 전문적인 방법입니다.

단계:

1. skills/ 디렉터리가 있는 플러그인 생성
2. 마켓플레이스에 플러그인 추가
3. 팀 구성원이 플러그인 설치

장점:

• 버전 관리 용이
• 마켓플레이스에서 검색 가능
• 자동 업데이트 지원

방법 2: Git 저장소로 공유

빠르고 간단한 방법입니다.

단계:

1. 프로젝트에 Skill 추가:

mkdir -p .claude/skills/my-skill
# SKILL.md 작성

1. Git에 커밋:

git add .claude/skills/
git commit -m "Add my-skill"
git push

1. 팀원이 풀하면 자동 사용 가능:

git pull
# Skills 즉시 사용 가능!

장점:

• 설정 없이 즉시 공유
• 프로젝트와 함께 버전 관리
• 간단한 워크플로우

---

9부: 모범 사례

Skill을 효과적으로 만들기 위한 네 가지 원칙을 알려드립니다.

1. 집중적으로 유지

하나의 Skill = 하나의 기능

좋은 예:

• "PDF 양식 작성"
• "Excel 데이터 분석"
• "Git 커밋 메시지 생성"

나쁜 예:

• "문서 처리" → PDF, Word, Excel을 별도 Skills로
• "데이터 도구" → 각 작업별로 분리

2. 명확한 설명 작성

특정 트리거 키워드를 포함하세요.

좋은 예:

description: "React 컴포넌트 생성. 'React', '컴포넌트', 'JSX'를 언급할 때 사용"

나쁜 예:

description: "코드 작성"  # 너무 광범위!

3. 팀과 함께 테스트

만들고 끝이 아닙니다!

질문:

• Skill이 예상대로 활성화되나요?
• 지침이 명확한가요?
• 누락된 예제나 엣지 케이스가 있나요?

팀원들의 피드백을 받아서 개선하세요.

4. 버전 문서화

시간이 지나면서 변경 사항을 추적하세요.

예시:

## 버전 기록

### v1.1.0 (2025-01-15)
- PDF 암호화 지원 추가
- 에러 처리 개선

### v1.0.0 (2025-01-01)
- 초기 릴리스
- 기본 PDF 양식 작성 기능

---

10부: 실전 예제

실제로 Skill을 하나 만들어보겠습니다.

시나리오: Git 커밋 메시지 생성기

팀에서 일관된 커밋 메시지 형식을 사용하고 싶다고 가정해봅시다.

1단계: 디렉터리 생성

mkdir -p .claude/skills/git-commit-helper
cd .claude/skills/git-commit-helper

2단계: SKILL.md 작성

---
name: git-commit-helper
description: "Git 커밋 메시지를 팀 컨벤션에 맞게 생성합니다. '커밋', '커밋 메시지', 'git commit'을 언급할 때 사용하세요"
---

# Git 커밋 메시지 생성기

팀의 커밋 메시지 컨벤션에 맞게 메시지를 생성합니다.

## 커밋 메시지 형식

\`\`\`
<type>(<scope>): <subject>

<body>

<footer>
\`\`\`

## Type 종류

- `feat`: 새로운 기능
- `fix`: 버그 수정
- `docs`: 문서 변경
- `style`: 코드 포맷팅
- `refactor`: 리팩토링
- `test`: 테스트 추가
- `chore`: 빌드 작업, 패키지 매니저 설정

## 예제

### 예제 1: 새 기능 추가

\`\`\`
feat(auth): 소셜 로그인 기능 추가

- Google OAuth 연동
- Facebook 로그인 지원
- 사용자 세션 관리 개선

Closes #123
\`\`\`

### 예제 2: 버그 수정

\`\`\`
fix(api): 사용자 조회 시 null 처리

사용자가 없을 때 발생하던 null pointer exception 수정

Fixes #456
\`\`\`

## 사용 방법

1. 변경 사항을 분석합니다
2. 적절한 type을 선택합니다
3. scope를 결정합니다 (선택사항)
4. 명확한 subject를 작성합니다 (50자 이내)
5. 필요시 body와 footer를 추가합니다

3단계: 템플릿 추가 (선택)

mkdir templates

templates/commit-template.txt:

<type>(<scope>): <subject>

<body>

<footer>

4단계: Git에 커밋

git add .claude/skills/git-commit-helper
git commit -m "feat(skills): Git 커밋 메시지 생성기 추가"
git push

5단계: 테스트

Claude에게 물어봅니다:

"변경 사항에 대한 커밋 메시지를 작성해줘"

Claude가 git-commit-helper Skill을 사용해서 팀 컨벤션에 맞는 메시지를 생성합니다!

---

11부: 고급 활용 팁

Skill 조합하기

여러 Skills를 함께 사용할 수 있습니다.

예시:

1. code-analyzer - 코드 분석
2. test-generator - 테스트 생성
3. git-commit-helper - 커밋 메시지 작성

Claude가 이 세 Skills를 순차적으로 사용해서 완전한 워크플로우를 실행합니다!

컨텍스트 활용

SKILL.md에서 프로젝트 구조를 참조할 수 있습니다:

## 프로젝트 구조 확인

먼저 프로젝트 루트에서 다음을 실행:
\`\`\`bash
find . -name "*.config.js"
\`\`\`

조건부 로직

## 환경에 따른 처리

- 개발 환경: `.env.development` 사용
- 프로덕션: `.env.production` 사용

환경을 확인하고 적절한 파일을 선택하세요.

---

12부: 문제 해결 FAQ

Q1: Skill이 너무 자주 활성화돼요

답: Description을 더 구체적으로 만드세요.

변경 전:

description: "코드 분석"

변경 후:

description: "Python 코드의 성능 병목을 분석합니다. 'performance', 'profiling', '성능 분석'을 명시적으로 요청할 때만 사용"

Q2: Skill이 전혀 활성화되지 않아요

체크리스트:

1. ✅ 파일 경로가 정확한가요?
2. ✅ YAML frontmatter 문법이 올바른가요?
3. ✅ Description에 관련 키워드가 있나요?
4. ✅ 파일 이름이 SKILL.md인가요? (대소문자 정확히)

Q3: 지원 파일이 실행되지 않아요

확인사항:

• 스크립트에 실행 권한이 있나요?

chmod +x scripts/helper.py

• 경로가 상대 경로로 작성되었나요?

❌ 잘못됨: `/absolute/path/script.py`
✅ 올바름: `scripts/helper.py`

Q4: 여러 Skills가 충돌해요

해결책:

• 각 Skill의 Description을 더 구체적으로 작성
• Scope를 명확히 분리
• 필요하다면 하나의 통합 Skill로 병합

---

아웃트로

오늘 Claude Code의 Agent Skills에 대해 알아봤습니다.

정리하면:

1. ✅ Skills는 전문 지식을 패키징하는 시스템
2. ✅ SKILL.md의 Description이 핵심
3. ✅ 개인/프로젝트/플러그인 세 가지 저장 위치
4. ✅ 팀과 공유하면 생산성 배가
5. ✅ 집중적이고 명확한 Skill 만들기

다음 단계:

• 지금 바로 첫 Skill 만들어보기
• 팀에서 공통으로 사용할 워크플로우 찾기
• Skills를 조합해서 자동화 구축하기

유용한 링크:

• 공식 문서: docs.claude.com/ko/docs/claude-code/skills