Claude Code Skill.md 완벽 가이드 (작성법과 실전 팁)

들어가며: AI 개발 파트너에게 매뉴얼을 건네는 시간 ⏰

코딩할 때마다 Claude Code에게 똑같은 설명을 반복하고 계신가요? "우리 프로젝트는 Next.js 15 쓰고, ESLint는 이렇게 설정하고..."라고 매번 알려주는 게 지겹지 않으신가요?

바로 그 문제를 해결하는 게 skill.md입니다.

Claude Code에 skill.md 파일 하나만 만들어두면, 신입 개발자에게 업무 인수인계서를 건네듯이 Claude에게 여러분의 프로젝트 규칙과 작업 방식을 한 번에 전달할 수 있어요. 세션이 바뀌어도, 브랜치를 옮겨도, 팀원이 프로젝트를 클론해도 일관된 품질이 유지됩니다.

이 글에서는 실전에서 바로 써먹을 수 있는 skill.md 작성법을 처음부터 끝까지 알려드릴게요! 💪

skill.md가 뭐길래? 개념부터 확실하게 🎯

Claude Code Skills란?

Claude Code Skills는 AI에게 특정 작업을 더 똑똑하게 처리하도록 만드는 업무 매뉴얼이에요. 마치 신입 사원에게 회사 업무 가이드를 주는 것처럼, Claude에게 여러분의 프로젝트에 특화된 지식과 절차를 패키징해서 제공하는 거죠.

Skills 없을 때:

• 당신: "블로그 포스트 작성해줘"
• Claude: 일반적인 방식으로 작성

Skills 있을 때:

• 당신: "블로그 포스트 작성해줘"
• Claude: (Skill 매뉴얼 확인) → 당신이 정해둔 형식과 스타일대로 정확하게 작성 ✨

왜 필요할까?

Claude Code는 기본적으로 범용 AI입니다. 하지만 skill.md를 통해 여러분의 프로젝트에 특화된 전문가로 변신시킬 수 있어요.

• ✅ 반복 설명 제거: 매번 프로젝트 규칙 설명할 필요 없음
• ✅ 일관된 품질: 팀 전체가 같은 코딩 스타일 유지
• ✅ 생산성 폭발: 3분 걸리던 작업이 30초로 단축
• ✅ 지식 자산화: 팀의 노하우를 문서로 축적

skill.md의 구조: 두 부분으로 이루어진 마법 📋

skill.md는 크게 두 파트로 구성됩니다:

1️⃣ YAML 프론트매터 (메타데이터)

파일 상단에 ---로 감싼 YAML 형식의 메타데이터입니다. Claude가 "이 스킬을 언제 써야 하는지" 판단하는 핵심 정보가 들어가요.

---
name: blog-posting-style
description: 기술 블로그 포스팅 자동 작성. 블로그, 포스팅, 글쓰기, 기술 블로그 작업 시 정보 정리형/경험 기록형 중 적절한 템플릿 적용.
version: 1.0.0
---

2️⃣ 마크다운 본문 (실제 지침)

프론트매터 아래에 작성하는 일반 마크다운 문서입니다. Claude가 스킬을 실행할 때 따를 구체적인 절차와 가이드라인이 담깁니다.

# 기술 블로그 포스팅 스타일

## 작성 모드 선택
사용자 요청 분석:
- "공식 문서 정리", "비교 분석" → 정보 정리형
- "삽질", "트러블슈팅" → 경험 기록형

## 정보 정리형 작성 구조
1. 개요: 정의와 목적
2. 상세 설명: 비교표, 코드 예시
3. 참고 자료: 공식 문서 링크

가장 중요한 부분: description 제대로 쓰기 🎯

description이 왜 중요한가?

Claude는 description만 보고 100개가 넘는 스킬 중에서 지금 써야 할 스킬을 선택합니다. description이 애매하면 스킬이 아예 발동하지 않아요!

description 작성 황금 법칙

✅ 좋은 예시: 구체적이고 트리거 키워드 포함

description: Pull Request 코드 리뷰 자동화. PR, 코드 리뷰, 검토 요청 시 자동으로 코드 품질, 보안, 스타일 검사 수행.

❌ 나쁜 예시: 너무 모호함

description: 코드 리뷰를 돕습니다.

description 작성 체크리스트 ✔️

1. 무엇을 하는가? - 스킬의 기능을 명확히
2. 언제 사용하는가? - 트리거 상황을 구체적으로
3. 키워드 포함 - 사용자가 쓸 법한 단어들 나열
4. 최대 1024자 - 하지만 간결할수록 좋음

실전 예시로 배우는 skill.md 작성법 💡

예시 1: PDF 처리 스킬

---
name: pdf-processor
description: PDF 파일에서 텍스트 및 표 추출, 양식 작성, 문서 병합. PDF, 문서, 텍스트 추출, 양식 작업 시 사용.
version: 1.0.0
---

# PDF 처리 스킬

## 텍스트 추출 방법

텍스트 추출에는 pdfplumber를 사용하세요:

\`\`\`python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
    print(text)
\`\`\`

## OCR이 필요한 경우

스캔된 PDF의 경우 pdf2image와 pytesseract를 사용:

\`\`\`python
from pdf2image import convert_from_path
import pytesseract

images = convert_from_path('scanned.pdf')
text = pytesseract.image_to_string(images[0])
\`\`\`

예시 2: 코드 리뷰 스킬

---
name: code-review-guide
description: Pull Request 코드 리뷰 자동화. PR, 코드 리뷰, 검토, 피드백 요청 시 코드 품질, 보안, 성능, 스타일 자동 검사.
version: 1.0.0
---

# 코드 리뷰 가이드

## 검토 항목

### 1. 코드 품질
- [ ] 함수는 단일 책임 원칙을 따르는가?
- [ ] 변수명이 의미를 명확히 전달하는가?
- [ ] 중복 코드가 없는가?

### 2. 보안
- [ ] SQL Injection 취약점은 없는가?
- [ ] API 키가 하드코딩되지 않았는가?
- [ ] 사용자 입력 검증이 적절한가?

### 3. 성능
- [ ] 불필요한 반복문은 없는가?
- [ ] 메모리 누수 가능성은 없는가?

## 피드백 형식

\`\`\`
✅ 좋은 점:
- [구체적인 칭찬]

⚠️ 개선 제안:
- [파일명:줄번호] 이유와 함께 개선 방법 제시

🔒 보안 이슈:
- [심각도] 문제점과 해결 방법
\`\`\`

폴더 구조로 skill 정리하기 📁

복잡한 skill은 여러 파일로 분리하는 게 좋아요. Progressive Disclosure 원칙에 따라 필요할 때만 추가 파일을 로드하면 context window를 효율적으로 사용할 수 있습니다.

권장 폴더 구조

.claude/skills/blog-posting-style/
├── SKILL.md                    # 핵심 가이드 (필수)
├── references/                 # 참고 문서
│   ├── seo-guide.md
│   └── style-guide.md
├── templates/                  # 템플릿 파일
│   ├── info-post.md
│   └── experience-post.md
└── scripts/                    # 실행 스크립트
    └── seo-check.sh

SKILL.md에서 다른 파일 참조하기

## SEO 최적화

상세한 SEO 가이드는 `references/seo-guide.md`를 참고하세요.

## 템플릿 사용

정보 정리형 포스트는 `templates/info-post.md` 템플릿을 사용합니다.

자주 하는 실수 Top 5 & 해결법 ⚠️

1️⃣ name 필드 규칙 위반

❌ 잘못된 예:

name: Blog Posting Style    # 공백 사용
name: api_design_guide       # 언더스코어 사용
name: API-Design-Guide       # 대문자 사용

✅ 올바른 예:

name: blog-posting-style
name: api-design-guide

2️⃣ description이 너무 모호함

❌ 잘못된 예:

description: 문서 작업 도구

✅ 올바른 예:

description: PDF에서 텍스트 추출, 표 분석, 양식 작성. PDF, 문서, 추출 작업 시 사용.

3️⃣ 하나의 skill에 너무 많은 기능

❌ 나쁜 예: 너무 많은 기능

general-helper/
└── SKILL.md    # 블로그 작성 + 코드 리뷰 + API 설계

✅ 좋은 예: 명확한 분리

skills/
├── blog-posting/       # 블로그 작성만
├── code-review/        # 코드 리뷰만
└── api-design/         # API 설계만

4️⃣ 파일 경로 문제

❌ 잘못된 예:

참고: ./reference.md        # 상대 경로 사용
참고: C:\docs\guide.md      # Windows 스타일

✅ 올바른 예:

참고: reference.md          # 직접 파일명
참고: references/guide.md   # Unix 스타일 슬래시

5️⃣ 너무 많은 선택지 제시

❌ 나쁜 예:

pypdf, pdfplumber, PyMuPDF, pdf2image 중 하나를 선택해서 사용할 수 있습니다.

✅ 좋은 예:

텍스트 추출은 pdfplumber를 사용하세요.
OCR이 필요한 스캔 PDF는 pdf2image + pytesseract를 사용하세요.

실전 팁: skill.md를 Claude에게 작성시키기 🤖

놀랍게도, skill.md는 Claude 자신이 가장 잘 작성합니다!

방법 1: 대화 기반 생성

"이 작업 흐름을 skill로 만들어줘. 
우리 프로젝트는 Next.js 15 사용하고, 
Tailwind CSS로 스타일링하며,
코드 리뷰 시에는 보안, 성능, 접근성을 중점적으로 체크해."

Claude가 프로젝트를 스캔하고, 패턴을 파악하고, 일관된 규칙을 추출해서 skill.md를 자동 생성해줍니다!

방법 2: skill-creator 사용

# 1. 마켓플레이스 활성화
/plugin marketplace add anthropics/skills

# 2. skill-creator 설치
/plugin install example-skills@anthropic-agent-skills

# 3. 자연어로 요청
"skill-creator를 이용해서 React 컴포넌트 작성 규칙 skill 만들어줘"

성능 최적화: Context Window 효율적으로 사용하기 ⚡

Progressive Disclosure 원칙

Claude는 3단계로 skill을 로드합니다:

1. Level 1: name + description (항상 로드)
2. Level 2: SKILL.md 본문 (skill 트리거 시)
3. Level 3: references, scripts (필요할 때만)

최적화 체크리스트

• ✅ 핵심만 SKILL.md에: 자주 쓰는 정보만 메인 파일에
• ✅ 상세 내용은 분리: references/ 폴더로 분산
• ✅ 스크립트 활용: 반복 코드는 Python/Bash로
• ✅ 코드블록 최소화: 예시는 간결하게

트러블슈팅: skill이 자동 활성화 안 될 때 🔧

문제: skill 설명과 요청이 같은데도 무시됨

많은 개발자들이 겪는 문제입니다. 자동 활성화가 항상 완벽하지는 않아요.

해결책: Hook으로 강제 트리거

# ~/.claude/hooks/auto-skill-trigger.sh

#!/bin/bash
INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty')

# "블로그" 키워드 감지 시 스킬 강제 활성화
if echo "$PROMPT" | grep -qiE '(블로그|포스팅|글쓰기)'; then
    echo "📝 INSTRUCTION: Use Skill(blog-posting-style) to handle this request."
fi

# "코드 리뷰" 키워드 감지 시
if echo "$PROMPT" | grep -qiE '(코드 리뷰|PR|검토)'; then
    echo "🔍 INSTRUCTION: Use Skill(code-review-guide) to handle this request."
fi

마무리: 지금 바로 시작하세요! 🚀

skill.md는 AI 시대의 업무 인수인계서입니다. 한 번 작성해두면:

• ✨ 매번 반복 설명하지 않아도 됨
• ✨ 팀 전체가 일관된 품질 유지
• ✨ 프로젝트 규칙이 코드로 문서화됨
• ✨ 신입 개발자 온보딩 시간 단축

첫 번째 skill.md는 Claude에게 만들어달라고 하세요! 그게 가장 빠르고 정확합니다. 그 다음부터는 팀과 함께 리뷰하면서 점진적으로 개선해나가면 됩니다.

---

📌 관련 자료

• 공식 문서: Claude Code Skills
• GitHub 예시 모음: anthropics/skills
• 커뮤니티 가이드: Claude Code 완벽 가이드북