Claude Code Skills 완전 가이드: AI 개발 도우미 커스터마이징

개요

Claude Code의 Skills는 AI가 특정 작업을 더 잘 수행하도록 가르치는 지침 세트입니다. 마치 개발자에게 "우리 프로젝트는 이렇게 작업해"라고 온보딩하는 것처럼, Claude에게도 프로젝트별 규칙과 패턴을 학습시킬 수 있습니다.

Skills가 해결하는 문제

• 일관성: 매번 같은 설명을 반복하지 않아도 됨
• 전문화: 특정 프레임워크/라이브러리에 맞춤화된 응답
• 팀 공유: Git에 커밋하면 팀 전체가 같은 AI 가이드라인 사용
• 자동 활성화: 관련 작업 시 자동으로 해당 스킬 적용

1. 공식 Skills 설치하기

마켓플레이스 등록

/plugin marketplace add anthropics/skills

플러그인 설치

document-skills (PDF, DOCX, PPTX, XLSX 처리):

/plugin install document-skills@anthropic-agent-skills

example-skills (디자인, 개발, 테스트 등):

/plugin install example-skills@anthropic-agent-skills

설치 후 Claude Code 재시작 필요!

포함된 스킬 목록

2. 커스텀 Skills 만들기

디렉토리 구조

Skills는 두 가지 범위로 생성할 수 있습니다:

Personal Skills (개인용, 모든 프로젝트에서 사용):

~/.claude/skills/my-skill/
├── SKILL.md          # 필수
├── reference.md      # 선택
└── examples.md       # 선택

Project Skills (프로젝트용, Git으로 팀 공유):

your-project/.claude/skills/my-skill/
├── SKILL.md
└── ...

SKILL.md 필수 구조

---
name: skill-name
description: "이 스킬이 무엇을 하고 언제 활성화되는지 명확히 작성"
allowed-tools:
  - Read
  - Write
  - Edit
---

# 스킬 제목

## 내용
스킬의 지침, 규칙, 예시 등을 마크다운으로 작성

YAML Frontmatter 규칙

description 작성 팁

description이 가장 중요합니다! Claude는 이 내용을 보고 스킬 활성화 여부를 결정합니다.

좋은 예:

description: "Rhymix 게시판 스킨 개발 시 자동 활성화. board, skin, list.html, view.html, write_form, comment 등의 키워드가 포함된 작업에서 사용"

나쁜 예:

description: "게시판 관련"  # 너무 모호함

3. 실제 예시: 프로젝트에 적용된 Rhymix Skills

현재 이 프로젝트에는 3개의 커스텀 스킬이 등록되어 있습니다.

3.1 rhymix-blade-templates

용도: Rhymix Template v2 (Blade 문법) 개발 지원

위치: .claude/skills/rhymix-blade-templates/SKILL.md

---
name: rhymix-blade-templates
description: Rhymix Template v2 (Blade) 개발 시 자동 활성화. blade, 템플릿, @version, @if, @foreach, layout.html 등의 키워드가 포함된 작업에서 사용
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
  - Glob
---

# Rhymix Blade Template v2 개발 스킬

## 필수 규칙

### 1. 버전 선언
모든 Blade 템플릿 파일 상단에 반드시 선언:
```html
@version(2)

2. 변수 출력 (보안 중요!)

<!-- 일반 변수: 반드시 이스케이프 출력 사용 -->
{{ $variable }}

<!-- HTML 콘텐츠만 raw 출력 -->
{!! $html_content !!}

금지 사항 (v1 문법)

• cond="" 속성 사용 금지
• loop="" 속성 사용 금지
• {$variable} 출력 방식 금지

**활성화 시점**: "Blade 템플릿 수정해줘", "@if 문법으로 변경해줘" 등의 요청 시 자동 활성화

---

### 3.2 board-skin-development

**용도**: Rhymix 게시판 스킨 개발 지원

**위치**: `.claude/skills/board-skin-development/SKILL.md`

```markdown
---
name: board-skin-development
description: Rhymix 게시판 스킨 개발 시 자동 활성화. board, skin, list.html, view.html, write_form, comment, eb_basic, eb_portfolio 등의 키워드가 포함된 작업에서 사용
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
  - Glob
---

# Rhymix 게시판 스킨 개발 스킬

## 스킨 파일 구조

modules/board/skins/{skin_name}/ ├── skin.xml # 스킨 정보 ├── list.html # 목록 페이지 ├── view.html # 게시글 보기 ├── write_form.html # 작성 폼 └── assets/ # CSS, JS, 이미지

## 주요 변수
- `$document_list`: 게시글 목록
- `$oDocument`: 현재 게시글
- `$grant->write`: 쓰기 권한

활성화 시점: "list.html 수정", "게시판 스킨 만들어줘", "eb_imin 스킨에서..." 등의 요청 시

3.3 security-audit

용도: 보안 취약점 분석 및 검토

위치: .claude/skills/security-audit/SKILL.md

---
name: security-audit
description: 보안 검토 및 취약점 분석 시 자동 활성화. XSS, CSRF, SQL injection, 보안, security, 취약점, 인젝션 등의 키워드가 포함된 작업에서 사용
allowed-tools:
  - Read
  - Grep
  - Glob
---

# Rhymix 보안 감사 스킬

## XSS 방지
취약: `{!! $user_input !!}`
안전: `{{ $user_input }}`

## CSRF 방지
필수 토큰: `_rx_csrf_token`

## SQL Injection 방지
executeQuery() 사용 필수

활성화 시점: "보안 검토해줘", "XSS 취약점 있나", "이 코드 안전해?" 등의 요청 시

4. 새로운 Skill 추가하기

단계별 가이드

Step 1: 폴더 생성

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

Step 2: SKILL.md 작성

# .claude/skills/my-new-skill/SKILL.md 생성

---
name: my-new-skill
description: "명확한 설명과 트리거 키워드 포함"
allowed-tools:
  - Read
  - Write
---

# 스킬 제목

## 규칙
1. 첫 번째 규칙
2. 두 번째 규칙

## 예시
```코드 예

참고사항

• 주의사항 1
• 주의사항 2

**Step 3: Git 커밋 (팀 공유)**
```bash
git add .claude/skills/my-new-skill/
git commit -m "Add my-new-skill for ..."
git push

팀원들이 git pull 하면 자동으로 스킬 적용!

5. Skills vs Slash Commands

선택 가이드

• 규칙/가이드라인이 필요하면 → Skills
• 명령어로 실행할 작업이면 → Slash Commands

6. 디버깅 및 확인

로드된 스킬 확인

claude --debug

스킬이 활성화되지 않을 때

1. description 확인: 트리거 키워드가 명확한가?
2. 파일 경로 확인: .claude/skills/스킬명/SKILL.md 구조인가?
3. YAML 문법 확인: ---로 시작하고 끝나는가?
4. name 규칙: 소문자와 하이픈만 사용했는가?

7. 베스트 프랙티스

DO ✅

• description에 구체적인 키워드 포함
• 규칙은 명확하고 간결하게
• 예시 코드 포함
• allowed-tools로 필요한 권한만 부여

DON'T ❌

• 너무 일반적인 description
• 여러 주제를 하나의 스킬에 섞기
• 불필요하게 긴 지침 작성

8. 유용한 스킬 아이디어

결론

Claude Code Skills는 AI를 프로젝트에 맞게 "훈련"시키는 강력한 방법입니다. 특히:

1. 공식 스킬: 마켓플레이스에서 바로 설치
2. 커스텀 스킬: 프로젝트별 규칙을 Git으로 공유
3. 자동 활성화: description 기반으로 필요할 때 자동 적용

잘 구성된 Skills는 AI 페어 프로그래밍의 품질을 크게 향상시킵니다.

참고 자료

• Anthropic Skills GitHub
• Claude Code 공식 문서
• Skills API Quickstart