이 가이드에서는 첫 번째 Skill을 5분 안에 만들어봅니다.
1단계: Skill이란?
간단히 말해서, Skill은 Claude가 알아야 할 전문 지식 패키지입니다.
일상 비유
- Slash Command: “계산기, 3+5를 계산해줄래?” (매번 명시적으로 요청)
- Skill: 계산기가 “아, 사용자가 수학 문제를 물어보고 있네! 내가 계산해야겠다”고 자동으로 감지하고 계산
Skill의 3가지 특징
- 자동 발견 - 사용자가 명시하지 않아도 Claude가 필요를 감지
- 조건 기반 - Skill의 설명과 사용자 요청이 일치할 때만 활성화
- 재사용 가능 - 여러 프로젝트나 팀에서 반복 사용
2단계: 폴더 구조 이해하기
Skill은 단순한 폴더 구조입니다:
~/.claude/skills/ # 개인 Skills 저장소
├── my-first-skill/ # 새로운 Skill
│ ├── SKILL.md # 필수: 핵심 정의 파일
│ └── guide.md # 선택사항: 추가 참고 자료
│
└── another-skill/
└── SKILL.md
또는 프로젝트 내에서 (팀 공유):
my-project/
├── .claude/
│ ├── skills/ # 프로젝트 Skills 저장소
│ │ └── team-skill/
│ │ └── SKILL.md
│ └── commands/ # Slash commands
│ └── my-command.md
└── src/
3단계: 첫 번째 Skill 만들기 (실습)
시나리오: “커밋 메시지 생성 Skill”
Git 커밋할 때마다 Claude가 좋은 커밋 메시지를 제안하는 Skill을 만들어봅시다.
3-1. 폴더 생성
# 개인 Skill로 만드는 경우
mkdir -p ~/.claude/skills/commit-message-helper
# 또는 프로젝트 Skill로 만드는 경우
mkdir -p .claude/skills/commit-message-helper3-2. SKILL.md 파일 생성
폴더 안에 SKILL.md 파일을 만들고 아래 내용을 복사합니다:
---
name: commit-message-helper
description: 코드 변경 사항으로부터 명확한 git 커밋 메시지를 생성합니다. 커밋 메시지를 작성하거나, git diff로 스테이징된 변경 사항을 검토하거나, 커밋에서 변경된 내용을 분석할 때 사용하세요. 표준 커밋 형식으로 메시지를 작성하는 데 도움이 됩니다.
---
# Commit Message Helper
## 무엇을 해야하는가?
git diff 결과를 보고 **명확하고 구조화된 커밋 메시지**를 생성합니다.
## 언제 사용하는가?
- `git diff --staged` 결과를 보고 메시지를 쓸 때
- 변경사항을 정리하고 싶을 때
- 좋은 커밋 메시지가 무엇인지 모를 때
## 지침
### 1단계: 변경사항 확인
```bash
git diff --staged
```
위 명령어 결과를 보여주세요.
### 2단계: 메시지 생성
다음 형식으로 커밋 메시지를 제안합니다:
```
<type>(<scope>): <subject>
<body>
<footer>
```
### 메시지 구성 요소
**type**: 변경의 종류
- `feat`: 새로운 기능
- `fix`: 버그 수정
- `docs`: 문서 변경
- `style`: 코드 스타일 (포맷팅 등)
- `refactor`: 코드 리팩토링
- `perf`: 성능 개선
- `test`: 테스트 추가/수정
**scope**: 영향 범위 (선택사항)
- 예: `auth`, `api`, `ui`
**subject**: 간단한 설명 (50자 이하)
- 현재형 사용: "Add" not "Added"
- 마침표 없음
**body**: 상세 설명 (선택사항)
- 무엇을 왜 했는지 설명
- 각 줄 72자 이하
**footer**: 관련 이슈 (선택사항)
- 예: `Closes #123`
## 예제
### 예제 1: 버그 수정
**입력:**
```
git diff --staged 결과:
- 로그인 페이지에서 에러 메시지 미표시 문제 해결
- 콘솔 에러 "Cannot read property 'message' of undefined"
```
**출력:**
```
fix(auth): handle undefined error in login form
When API returns an error without a message property,
the login form now displays a generic error message
instead of crashing.
This prevents users from seeing a blank error message
and improves error handling consistency.
Closes #456
```
### 예제 2: 새로운 기능
**입력:**
```
git diff --staged 결과:
+ 사용자 프로필에 다크 모드 토글 추가
+ CSS 변수로 라이트/다크 테마 구현
```
**출력:**
```
feat(ui): add dark mode toggle to user profile
Added a toggle switch in the user profile settings
to switch between light and dark themes. The preference
is saved to localStorage for persistence.
- Implemented using CSS custom properties
- Light theme as default
- Dark theme improves readability in low-light conditions
```
## 팁
- 한 번에 한 가지만 커밋하면 좋은 메시지를 쓰기 쉬움
- 메시지는 기술적 어떻게(how)보다는 무엇(what)과 왜(why)를 설명
- 팀원들이 3개월 후 git log를 읽을 때도 이해할 수 있게 작성3-3. 파일 저장
파일을 저장하면 끝입니다!
# 실제 파일 경로
~/.claude/skills/commit-message-helper/SKILL.md
# 또는
.claude/skills/commit-message-helper/SKILL.md4단계: Skill 테스트하기
이제 당신의 Skill을 테스트합니다:
테스트 방법 1: 직접 요청
Claude Code에서 다음처럼 입력해보세요:
내가 방금 로그인 버그를 고쳤는데 커밋 메시지를 써줄래?
변경사항은:
- 로그인 폼 에러 처리 개선
- 사용자가 상세 에러 메시지를 볼 수 있게 함
예상 결과: Claude가 자동으로 “Commit Message Helper” Skill을 사용해 커밋 메시지를 제안합니다.
테스트 방법 2: 실제 git diff 사용
# 파일 수정 후
git add .
# Claude에게 보여주기
git diff --staged그 후 Claude에게:
이 변경사항으로 좋은 커밋 메시지를 만들어줄래?
Claude가 Skill을 자동으로 사용합니다!
5단계: Skill을 팀과 공유하기
만든 Skill을 팀과 공유하려면:
# 1. 프로젝트 Skill로 옮기기
mkdir -p .claude/skills/commit-message-helper
# SKILL.md를 프로젝트 폴더로 복사
# 2. Git에 추가
git add .claude/skills/
git commit -m "Add commit-message-helper Skill"
git push
# 3. 팀원이 git pull하면 자동으로 사용 가능!자주 묻는 질문 (FAQ)
Q1: Skill이 자동으로 실행되지 않아요
확인사항:
-
Skill 파일이 올바른 위치에 있나요?
- Personal:
~/.claude/skills/skill-name/SKILL.md - Project:
.claude/skills/skill-name/SKILL.md
- Personal:
-
SKILL.md파일 이름이 정확한가요? (대소문자 구분) -
YAML 문법이 맞나요?
# 처음 10줄 확인 head -n 10 ~/.claude/skills/commit-message-helper/SKILL.md확인사항:
- 첫 줄:
--- - 마지막 frontmatter 줄:
--- - 탭 대신 공백 사용
- 첫 줄:
-
description필드가 구체적인가요?- 단순한 설명보다 “언제 사용하는가”를 명확히
Q2: 여러 Skill을 한 번에 만들 수 있나요?
네! 각 Skill은 독립적인 폴더입니다.
~/.claude/skills/
├── commit-message-helper/
│ └── SKILL.md
├── pdf-analyzer/
│ └── SKILL.md
└── weekly-report-generator/
└── SKILL.md
Q3: Skill을 수정했는데 반영이 안 돼요
Claude Code를 재시작해보세요. Skill은 시작 시에 한 번만 로드됩니다.
# Claude Code 종료 후 다시 시작
claudeQ4: Personal Skill과 Project Skill 중 어느 것을 사용해야 하나요?
| 상황 | 추천 |
|---|---|
| 개인 프로젝트, 개인용 도구 | Personal |
| 팀이 함께 사용해야 함 | Project |
| 여러 프로젝트에서 사용 | Personal (편리함) |
| 팀 규칙 (커밋 메시지, 코드 스타일) | Project (일관성) |
Q5: Description 필드에 개행을 사용할 수 있나요?
답변: 아니오, 개행은 불가능합니다. Description은 단일 라인만 지원합니다.
상세 설명
- 최대 길이: 1024자
- 형식: 단일 라인 텍스트만 지원
- YAML 멀티라인 문법 (
|,>등)은 작동하지 않음
❌ 잘못된 예
# 이렇게 쓰면 안 됩니다
description: |
첫 번째 라인
두 번째 라인
세 번째 라인✅ 올바른 예
1024자 제한 내에서 모든 내용을 한 줄로 작성하세요:
description: 코드 변경 사항으로부터 명확한 git 커밋 메시지를 생성합니다. 커밋 메시지를 작성하거나, git diff로 스테이징된 변경 사항을 검토할 때 사용하세요.권장 구조
Description에 다음 요소를 모두 포함시키되, 한 줄로 작성하세요:
- 무엇을 하는가: Skill의 기능
- 언제 사용하는가: 어떤 상황에 활성화될지
- 특수 기능 (선택): 추가 기능이나 제약사항
description: [기능] [언제 사용] [특수 기능/제약]예시들:
# 예제 1: 짧고 명확
description: PDF에서 텍스트와 표를 추출합니다. PDF 파일 작업, 내용 추출, 문서 병합 시 사용하세요.
# 예제 2: 더 자세함 (제약사항 포함)
description: Obsidian 볼트 전체의 태그를 정규화하고 표준화합니다. 불일치하는 태그, 중복 태그, 계층적 태그 조직이 필요할 때 사용하세요. 한국어와 영어 콘텐츠를 모두 지원합니다.
# 예제 3: 구체적인 트리거 포함
description: Python 코드를 검토하여 모범 사례, 잠재적 버그, 성능 문제를 확인합니다. Python 코드 검토, PR 확인, 코드 품질 분석 시 사용하세요.더 많은 설명이 필요하다면?
1024자보다 긴 설명이 필요하면, SKILL.md의 마크다운 본문에 작성하세요:
---
name: my-skill
description: 짧은 한 줄 요약
---
# My Skill
## 상세 설명
여기에 길게 작성할 수 있습니다.
여러 줄, 여러 섹션으로 상세히 설명하세요.
## 사용 예제
...다음 단계
1단계 정복했다면
✅ Skill의 기본 개념 이해 ✅ 첫 번째 Skill 생성 ✅ Skill 테스트
2단계: 더 복잡한 Skill 만들기
- Agent Skills - Claude Code Docs 읽기
- 스크립트와 보조 파일을 포함한 Skill 만들기
- 여러 개의 관련 Skill 조합하기
3단계: 팀 규칙 정의하기
- Agent Skills - 팀 워크플로우 문서 참고
- 조직 전체가 따를 Skill 설계
- git을 통한 버전 관리
추가 예제: 더 많은 Skill 아이디어
예제 1: 주간 보고서 작성
name: weekly-report-writer
description: 주간 팀 보고서를 체계적으로 작성하여 성과, 과제, 다음 주 계획을 포함하세요. 주간 현황 보고서, 팀 업데이트 또는 스프린트 리뷰 작성 시 활용하세요.예제 2: Python 코드 리뷰
name: python-code-reviewer
description: 파이썬 코드를 검토하여 모범 사례, 잠재적 버그 및 성능 문제를 확인합니다. 파이썬 코드 검토, 풀 리퀘스트 확인 또는 코드 품질 분석 시 사용합니다.예제 3: 마크다운 문서 최적화
name: markdown-formatter
description: 마크다운 문서를 포맷팅하고 최적화합니다. 마크다운 파일 작성 또는 편집, 문서 작성, 문서 구조 개선 시 사용하세요.문제 해결
Skill이 너무 많아서 헷갈려요
해결책: description을 더 구체적으로 작성하세요.
❌ 나쁜 예:
description: 글쓰기에 도움이 됩니다✅ 좋은 예:
description: 명확한 Git 커밋 메시지를 유형, 범위, 주제를 포함한 표준 형식으로 생성합니다. 커밋 메시지를 작성하거나 스테이징된 변경 사항을 검토할 때 사용하세요.YAML 문법 오류
가장 흔한 실수:
- 탭 대신 공격 사용 (반드시 공백!)
- 콜론(:) 뒤에 공백 없음
- 마크다운 들여쓰기 잘못됨
확인 방법:
# YAML 검증 (온라인 도구)
# https://www.yamllint.com/
# 또는 직접 보기
cat ~/.claude/skills/commit-message-helper/SKILL.md | head -n 20마무리
다음은 더 복잡한 Skill을 만들거나, 팀과 함께 조직 규칙을 정의하는 단계입니다!
더 자세한 내용은:
- Agent Skills - Claude Code Docs - 완전한 레퍼런스
- Agent Skills - 고급 활용 - 스크립트, 복합 Skill 등