Skills란 무엇인가

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

핵심 특징: Model-Invoked

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

Skills vs Slash Commands

구분	Skills	Slash Commands
복잡도	복잡한 워크플로우	간단한 프롬프트
구조	디렉토리 + 다중 파일	단일 .md 파일
활성화 방식	자동 (컨텍스트 기반)	수동 (/명령어)
파일 구성	SKILL.md + 스크립트 + 템플릿	하나의 파일만
적용 범위	Personal / Project / Plugin	Personal / Project
사용 사례	복잡한 자동화, 팀 표준	반복 프롬프트, 간단한 템플릿

 

언제 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

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

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

적용 범위 비교표

항목	Personal Skills	Project Skills	Plugin Skills
위치	~/.claude/skills/	.claude/skills/	플러그인 내장
범위	모든 프로젝트	특정 프로젝트만	플러그인 설치 시
Git 관리	불필요	필수 (팀 공유)	플러그인이 관리
사용자	개인	팀 전체	플러그인 사용자
목적	개인 워크플로우	프로젝트 표준	범용 도구

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: 블로그 포스팅 작성 스타일 가이드. 정보 정리형과 경험 기록형 두 가지 모드 지원. 블로그, 포스팅, 글쓰기, 기술 블로그 작업 시 자동 적용.

트리거 키워드 예시:

Skill 목적	포함할 키워드
블로그 작성	블로그, 포스팅, 글쓰기, 기술 블로그
코드 리뷰	코드 리뷰, PR, pull request, 검토
API 설계	API, 엔드포인트, REST, GraphQL, 설계
테스트 자동화	테스트, 자동화, TDD, 단위 테스트

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