Agent Skills는 Claude의 기능을 모듈화된 폴더 형태로 확장하는 시스템입니다. 각 Skill은 필수 파일인 SKILL.md와 선택적 지원 파일들(스크립트, 템플릿 등)로 구성됩니다.

핵심 특징: Model-Invoked

Skills의 가장 중요한 특징은 Model-Invoked 방식입니다. 사용자가 명시적으로 호출하지 않아도, Claude가 작업 맥락을 분석해 자동으로 적절한 Skill을 활성화합니다. 이는 Slash Commands와의 가장 큰 차이점입니다.

Skills vs Slash Commands

언제 Skills를 사용하나:
– Claude가 자동으로 인식해야 하는 복잡한 워크플로우
– 다중 파일과 스크립트가 필요한 작업
– 검증 절차가 포함된 복잡한 프로세스
– 팀 전체가 공유하는 표준화된 가이드

언제 Slash Commands를 사용하나:
– 같은 프롬프트를 반복 실행
– 단일 파일로 충분한 간단한 작업
– 명시적인 수동 실행이 필요한 경우

Skills의 종류와 적용 범위

Claude Code의 Skills는 3가지 범위로 관리됩니다.

1. Personal Skills (~/.claude/skills/)

목적: 개인 워크플로우와 실험적 도구

특징:
– 홈 디렉토리에 저장
– 모든 프로젝트에서 접근 가능
– Git 버전 관리 불필요
– 개인 개발 환경에 특화

사용 예시:

~/.claude/skills/
├── my-code-review/       # 개인 코드 리뷰 스타일
├── debug-helper/         # 자주 사용하는 디버깅 워크플로우
└── quick-refactor/       # 개인용 리팩토링 패턴

2. Project Skills (.claude/skills/)

목적: 프로젝트/팀 공유 전문 지식

특징:
– 프로젝트 루트의 .claude/skills/에 저장
– Git으로 팀원과 공유
– 프로젝트별 표준과 가이드라인
– 특정 프로젝트에만 적용

사용 예시:

project-root/
└── .claude/
    └── skills/
        ├── blog-posting-style/   # 블로그 스타일 가이드
        ├── api-design-guide/     # API 설계 표준
        └── test-automation/      # 프로젝트별 테스트 자동화

3. Plugin Skills

목적: 플러그인이 제공하는 번들 기능

특징:
– 플러그인 설치 시 자동 제공
– 플러그인 개발자가 관리
– 범용적인 도구와 워크플로우
– 설치만으로 사용 가능

적용 범위 비교표

Skills 사용 방법

자동 활성화 (권장)

Claude는 다음 3곳에서 Skills를 자동으로 발견합니다:

# 1. Personal Skills
~/.claude/skills/

# 2. Project Skills (현재 프로젝트)
/path/to/project/.claude/skills/

# 3. Plugin Skills (설치된 플러그인)

사용자가 요청할 때, Claude는 각 Skill의 description 필드를 분석해 가장 적합한 Skill을 자동으로 활성화합니다.

예시:

# 사용자 요청
"블로그 포스팅 초안 작성해줘"

# Claude의 동작
1. 사용 가능한 Skills 확인
2. description에서 "블로그", "포스팅" 키워드 발견
3. blog-posting-style Skill 자동 활성화
4. Skill 가이드라인에 따라 작성

사용 가능한 Skills 확인

# Claude Code에서 실행
claude "What Skills are available?"

명시적 호출 (선택적)

특정 Skill을 강제로 사용하려면:

# Skill 도구 명시
claude "blog-posting-style skill을 사용해서 경험 기록형 포스팅 작성해줘"

Skills 만들기 – 실전 가이드

디렉토리 구조

my-skill/
├── SKILL.md           # 필수: Skill 정의와 지침
├── reference.md       # 선택: 추가 참고 자료
├── scripts/           # 선택: 실행 스크립트
│   └── validate.sh
└── templates/         # 선택: 템플릿 파일
    └── template.yaml

SKILL.md 작성법

필수 구성 요소:

1. YAML 프론트매터 (필수)
2. 상세 지침 (필수)
3. 예시와 템플릿 (권장)

전체 예시:

---
name: blog-posting-style
description: 블로그 포스팅 작성 스타일 가이드. 정보 정리형과 경험 기록형 두 가지 모드 지원. 블로그, 포스팅, 글쓰기 작업 시 자동 적용.
allowed-tools: [Read, Write, Edit, WebFetch]
---

# 블로그 포스팅 스타일 가이드

## 목적
ShowMeTheTime 블로그의 표준 작성 스타일을 정의합니다.

## 모드 구분

### 정보 정리형
- 공식 문서 기반 객관적 정보
- "~입니다", "~합니다" 체
- 코드 예시와 비교표 중심

### 경험 기록형
- 실제 경험과 시행착오 기록
- 구어체 사용
- 솔직한 감정 표현

## 작성 원칙

### 코드 예시
- 반드시 주석 추가
- 동작하는 코드만 제시

```yaml
# 좋은 예시
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config  # ConfigMap 이름
data:
  LOG_LEVEL: "info"  # 로그 레벨 설정

구조화

• 짧은 문단 (2-4줄)
• 불렛 포인트 적극 활용
• 비교는 표로 정리

참고 자료

• 마크다운 가이드

### YAML 프론트매터 필드

#### name (필수)

**규칙:**
- 소문자, 숫자, 하이픈만 사용
- 최대 64자
- 고유해야 함

```yaml
# ✅ 올바른 예시
name: blog-posting-style
name: api-design-guide
name: test-automation-v2

# ❌ 잘못된 예시
name: Blog Posting Style  # 공백 불가
name: api_design_guide    # 언더스코어 불가
name: API-Design-Guide    # 대문자 불가

description (필수)

중요: description은 Claude가 Skill을 발견하는 핵심입니다.

작성 원칙:
– 무엇을 하는 Skill인지 명확히
– 언제 Claude가 사용해야 하는지 구체적으로
– 사용자가 언급할 트리거 키워드 포함
– 최대 1024자

#  나쁜 예시: 너무 모호함
description: 문서 작업을 돕습니다.

#  좋은 예시: 구체적이고 트리거 키워드 포함
description: 블로그 포스팅 작성 스타일 가이드. 정보 정리형과 경험 기록형 두 가지 모드 지원. 블로그, 포스팅, 글쓰기, 기술 블로그 작업 시 자동 적용.

트리거 키워드 예시:

allowed-tools (선택)

특정 도구만 허용해 보안과 읽기 전용 워크플로우를 구현합니다.

---
name: security-audit
description: 보안 감사를 위한 읽기 전용 Skill. 코드 수정 불가.
allowed-tools: [Read, Grep, Glob, Bash]
---

주요 도구:
– Read: 파일 읽기
– Write: 파일 쓰기
– Edit: 파일 수정
– Bash: 쉘 명령 실행
– Grep: 코드 검색
– Glob: 파일 검색
– WebFetch: 웹 페이지 가져오기

선택적 파일들

reference.md

추가 참고 자료와 긴 문서를 분리합니다.

# reference.md
## 추가 참고 자료

### 관련 문서
- [공식 가이드](https://example.com)

### 상세 예시
...

scripts/

검증 스크립트나 자동화 도구를 포함합니다.

# scripts/validate.sh
#!/bin/bash
# 포스팅 형식 검증 스크립트

echo "Validating blog post format..."
# 검증 로직

templates/

재사용 가능한 템플릿 파일을 저장합니다.

# templates/api-template.yaml
openapi: 3.0.0
info:
  title: API Name
  version: 1.0.0
paths:
  /resource:
    get:
      summary: Get resource

고급 기능

Progressive Disclosure (점진적 컨텍스트 로딩)

Claude는 필요한 시점에만 지원 파일을 로드해 컨텍스트를 효율적으로 관리합니다.

동작 방식:
1. 초기에는 SKILL.md만 로드
2. 추가 정보 필요 시 reference.md 로드
3. 스크립트 실행 필요 시 scripts/ 로드

이점:
– 토큰 사용량 최적화
– 빠른 응답 시간
– 필요한 정보만 로드

보안 중심 워크플로우

allowed-tools로 읽기 전용 Skill을 만들 수 있습니다.

예시: 보안 감사 Skill

---
name: security-audit
description: 코드베이스 보안 취약점 검사. 읽기 전용으로 동작하며 코드 수정 불가.
allowed-tools: [Read, Grep, Glob, Bash]
---

# 보안 감사 Skill

## 검사 항목
- SQL Injection 취약점
- XSS 취약점
- 하드코딩된 시크릿
- 안전하지 않은 의존성

## 검사 방법
```bash
# 하드코딩된 API 키 검색
grep -r "API_KEY\s*=\s*['\"]" .

# SQL Injection 취약 패턴
grep -r "execute.*\+.*request\." .

보고서 형식

• 발견된 취약점 목록
• 심각도 평가
• 수정 권장사항

### 팀 표준화

Project Skills로 팀 전체의 작업 방식을 표준화합니다.

**예시: API 설계 표준**

```bash
project-api/
└── .claude/
    └── skills/
        └── api-design-standard/
            ├── SKILL.md
            ├── naming-conventions.md
            ├── templates/
            │   ├── rest-api.yaml
            │   └── graphql-schema.graphql
            └── scripts/
                └── validate-api.sh

베스트 프랙티스

1. 효과적인 description 작성

핵심 원칙:
– 구체적인 트리거 키워드 포함
– 사용 시점 명확히 설명
– 간결하지만 충분한 정보

비교 예시:

#  모호한 description
description: 문서 작업 도구

#  효과적인 description
description: PDF에서 텍스트 추출. PDF, 문서, 텍스트 추출 작업 시 사용.

#  너무 일반적
description: 코드 리뷰를 돕습니다.

#  구체적이고 명확
description: Pull Request 코드 리뷰 자동화. PR, 코드 리뷰, 검토 요청 시 자동으로 코드 품질, 보안, 스타일 검사 수행.

2. 하나의 Skill = 하나의 기능

각 Skill은 단일 목적에 집중해야 합니다.

#  나쁜 예시: 너무 많은 기능
general-helper/
└── SKILL.md  # 블로그 작성 + 코드 리뷰 + API 설계

#  좋은 예시: 명확한 분리
skills/
├── blog-posting/      # 블로그 작성만
├── code-review/       # 코드 리뷰만
└── api-design/        # API 설계만

3. 팀과 함께 테스트

Project Skills는 팀원들과 함께 테스트해야 합니다.

테스트 프로세스:
1. Skill 작성 및 커밋
2. 팀원들에게 다양한 요청으로 테스트 요청
3. 활성화 빈도와 정확도 확인
4. description 개선 및 재배포

예시:

# 팀원 A: "API 엔드포인트 설계해줘"
# → api-design Skill 활성화됨 

# 팀원 B: "REST API 만들어줘"
# → api-design Skill 활성화 안 됨 
# → description에 "REST" 키워드 추가 필요

4. 버전 관리와 문서화

SKILL.md 내에 버전 히스토리를 포함합니다.

---
name: blog-posting-style
description: 블로그 포스팅 스타일 가이드
---

# 블로그 포스팅 스타일 가이드

## 버전 히스토리

### v2.0.0 (2025-10-27)
- 경험 기록형 모드 추가
- SEO 최적화 가이드 추가

### v1.0.0 (2025-10-01)
- 초기 버전 (정보 정리형만)

5. Unix 스타일 경로 사용

파일 경로는 항상 Forward Slash(/)를 사용합니다.

#  올바른 경로
참고: scripts/validate.sh
템플릿: templates/api.yaml

#  잘못된 경로 (Windows 스타일)
참고: scripts\validate.sh

문제 해결

Skill이 활성화되지 않을 때

원인 1: 모호한 description

# 문제
description: 코드 작업 도구

# 해결
description: Python 코드 리팩토링 자동화. 리팩토링, 코드 정리, Python, 클린 코드 작업 시 사용.

원인 2: YAML 문법 오류

# 문제: 콜론 뒤 공백 누락
description:블로그 작성 도구

# 해결
description: 블로그 작성 도구

원인 3: 잘못된 파일 경로

# 문제
참고: ./reference.md  # 상대 경로 사용

# 해결
참고: reference.md    # 직접 파일명만

원인 4: 누락된 의존성

스크립트가 외부 도구를 사용하는 경우, SKILL.md에 명시합니다.

## 사전 요구사항
- Node.js 18+
- `jq` (JSON 처리)
- `yq` (YAML 처리)

설치 방법:
```bash
brew install jq yq

## 실제 사용 예시

### 예시 1: 블로그 포스팅 자동화

**Skill 구조:**

```bash
.claude/skills/blog-posting-style/
├── SKILL.md
├── templates/
│   ├── info-post.md      # 정보 정리형 템플릿
│   └── experience-post.md # 경험 기록형 템플릿
└── scripts/
    └── seo-check.sh      # SEO 검증 스크립트

SKILL.md:

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

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

## 모드 선택

사용자 요청 분석:
- "공식 문서 정리", "비교 분석", "설치 가이드" → 정보 정리형
- "삽질", "트러블슈팅", "회고", "경험" → 경험 기록형

## 정보 정리형 작성

### 구조
```markdown
# [기술명] 개념 및 사용 가이드

## 개요
- 정의와 목적
- 주요 특징

## 상세 설명
- 비교표
- 코드 예시 (주석 포함)

## 참고 자료
- 공식 문서 링크

스타일

• 객관적이고 명확한 설명
• “~입니다”, “~합니다” 체
• 공식 문서 기반

경험 기록형 작성

구조

# [경험 제목]

## 문제 상황
- 배경과 동기

## 시행착오
- 실패 과정 솔직하게
- 에러 로그 전체 포함

## 해결 과정
- 최종 해결 방법

## 고민했던 포인트
- 의사결정 과정

## 느낀 점
- 배운 점과 교훈

스타일

• 솔직하고 개인적인 표현
• 구어체 사용
• 감정 표현 OK

SEO 최적화

스크립트 실행:

./scripts/seo-check.sh draft.md

체크 항목:
– 제목 40-60자
– 메타 설명 120-160자
– 헤딩 구조 (H2, H3)
– 내부 링크 포함

**사용 시나리오:**

```bash
# 사용자 요청
"Docker Compose 설치 가이드 작성해줘"

# Claude의 동작
1. "설치 가이드" 키워드 감지
2. blog-posting-style Skill 활성화
3. 정보 정리형 모드 선택
4. templates/info-post.md 템플릿 사용
5. 공식 문서 리서치 (WebFetch)
6. 포스팅 작성
7. scripts/seo-check.sh 실행

예시 2: 코드 리뷰 자동화

Skill 구조:

.claude/skills/code-review/
├── SKILL.md
├── checklists/
│   ├── backend.md
│   ├── frontend.md
│   └── security.md
└── scripts/
    └── lint-check.sh

SKILL.md:

---
name: code-review-automation
description: Pull Request 코드 리뷰 자동화. PR, 코드 리뷰, 검토, pull request 작업 시 코드 품질, 보안, 스타일 검사 자동 수행.
allowed-tools: [Read, Grep, Glob, Bash]
---

# 코드 리뷰 자동화

## 리뷰 프로세스

### 1단계: 변경 파일 분석
```bash
git diff --name-only origin/main

2단계: 타입별 체크리스트 선택

• *.ts, *.tsx → frontend.md
• *.py, *.go → backend.md
• 모든 파일 → security.md

3단계: 자동 검사

./scripts/lint-check.sh

4단계: 수동 리뷰 포인트

코드 품질

• [ ] 중복 코드 없음
• [ ] 명확한 변수명
• [ ] 적절한 주석
• [ ] 에러 처리 완료

보안

• [ ] 입력 검증
• [ ] SQL Injection 방어
• [ ] XSS 방어
• [ ] 하드코딩된 시크릿 없음

성능

• [ ] N+1 쿼리 없음
• [ ] 적절한 인덱스
• [ ] 캐싱 고려

5단계: 리뷰 코멘트 작성

형식:

## 요약
- 변경 파일: X개
- 주요 변경: [설명]
- 전체 평가:  승인 /  수정 필요 /  재작업 필요

## 상세 리뷰

### 긍정적인 부분
- ...

### 개선 필요
1. [파일명:줄번호] 문제 설명
   - 권장: 개선 방법

### 질문
- ...

**사용 시나리오:**

```bash
# 사용자 요청
"PR #123 코드 리뷰해줘"

# Claude의 동작
1. "코드 리뷰", "PR" 키워드 감지
2. code-review-automation Skill 활성화
3. git diff로 변경 파일 확인
4. 파일 타입별 체크리스트 선택
5. scripts/lint-check.sh 실행
6. 수동 리뷰 포인트 확인
7. 구조화된 리뷰 코멘트 작성

예시 3: 프로젝트별 문서 생성

Skill 구조:

.claude/skills/doc-generator/
├── SKILL.md
├── templates/
│   ├── README.md
│   ├── API.md
│   ├── CONTRIBUTING.md
│   └── CHANGELOG.md
└── scripts/
    └── generate-api-docs.sh

SKILL.md:

---
name: project-doc-generator
description: 프로젝트 문서 자동 생성. README, API 문서, CONTRIBUTING, CHANGELOG 생성 및 업데이트. 문서, 문서화, docs 작업 시 사용.
allowed-tools: [Read, Write, Grep, Glob, Bash]
---

# 프로젝트 문서 생성 Skill

## 지원 문서 타입

### README.md
- 프로젝트 개요
- 설치 방법
- 사용 예시
- 라이선스

자동 수집 정보:
- `package.json`에서 의존성
- `scripts/`에서 사용 가능한 명령어
- 테스트 파일에서 예시 코드

### API.md
스크립트 실행:
```bash
./scripts/generate-api-docs.sh src/

포함 내용:
– 엔드포인트 목록
– 요청/응답 스키마
– 인증 방법
– 에러 코드

CONTRIBUTING.md

• Git 워크플로우
• 브랜치 전략
• PR 템플릿
• 코드 스타일 가이드

CHANGELOG.md

• 버전별 변경사항
• Git 커밋 히스토리 분석
• Semantic Versioning 준수

문서 생성 프로세스

1. 프로젝트 분석

# 프로젝트 타입 감지
ls package.json 2>/dev/null && echo "Node.js"
ls requirements.txt 2>/dev/null && echo "Python"
ls go.mod 2>/dev/null && echo "Go"

2. 템플릿 선택

프로젝트 타입에 맞는 템플릿 선택

3. 정보 수집

• Git 로그 분석
• 코드 구조 파악
• 의존성 목록 추출

4. 문서 생성

템플릿에 수집 정보 삽입

5. 검증

• 링크 유효성 확인
• 코드 예시 문법 검사
• 목차 구조 검증

**사용 시나리오:**

```bash
# 사용자 요청
"프로젝트 README 생성해줘"

# Claude의 동작
1. "README", "문서" 키워드 감지
2. project-doc-generator Skill 활성화
3. 프로젝트 타입 감지 (package.json → Node.js)
4. templates/README.md 템플릿 로드
5. package.json 파싱 (의존성, 스크립트)
6. src/ 디렉토리 분석 (주요 파일)
7. README.md 생성

참고 자료

공식 문서

• Claude Code Skills 공식 가이드
• Skills vs Slash Commands 비교
• Plugin Skills 개발

관련 리소스

• Claude Code 공식 문서
• Sub-Agents 가이드

작성 일자: 2025-10-27
공식 문서 버전: Claude Code 최신 버전 기준
카테고리: Development Tools
태그: Claude, Claude Code, AI, Development, Automation, Skills, Developer Tools, Productivity

The post Claude Code Skills 세팅 완벽 가이드 appeared first on .