Claude Code는 터미널에서 코드를 읽고, 수정하고, 실행하는 AI 에이전트다. 하지만 프로젝트마다 반복되는 작업이 있다면? Skills를 만들어 Claude에게 “우리 팀은 이렇게 일한다”고 가르칠 수 있다. 이 글에서는 Skills의 개념부터 고급 활용까지 단계별로 다룬다.
Skills란 무엇인가
Skills는 Claude Code에 추가하는 커스텀 명령(Custom Slash Command)이다. 마크다운 파일 하나로 정의하며, Claude가 특정 작업을 수행할 때 따라야 할 지침을 담는다.
예를 들어 /deploy라는 Skill을 만들면, Claude가 배포 절차를 정확히 따르도록 할 수 있다. /write-test를 만들면, 팀의 테스트 컨벤션에 맞춰 테스트 코드를 생성한다.
Skills vs CLAUDE.md
| 항목 | CLAUDE.md | Skills |
|---|---|---|
| 역할 | 프로젝트 전반의 규칙 | 특정 작업에 대한 지침 |
| 로딩 시점 | 항상 로딩 | 필요할 때만 로딩 |
| 호출 방식 | 자동 | /skill-name 또는 자동 감지 |
| 컨텍스트 비용 | 항상 소비 | 호출 시에만 소비 |
CLAUDE.md에 모든 규칙을 넣으면 컨텍스트 윈도우를 불필요하게 소비한다. Skills는 필요한 순간에만 로딩되므로 효율적이다.
기본 구조
저장 위치
Skills는 두 가지 레벨로 저장할 수 있다.
# 프로젝트 레벨 (이 프로젝트에서만 사용)
.claude/skills/skill-name/SKILL.md
.claude/skills/skill-name.md # 단일 파일도 가능
# 개인 레벨 (모든 프로젝트에서 사용)
~/.claude/skills/skill-name/SKILL.md
프로젝트 레벨 Skills는 Git으로 버전 관리되므로 팀원 모두가 같은 워크플로우를 공유할 수 있다. 개인 레벨 Skills는 자신만의 작업 스타일을 정의할 때 유용하다.
파일 형식
Skill 파일은 YAML frontmatter + 마크다운 본문으로 구성된다.
---
name: my-skill
description: 이 Skill이 하는 일을 한 줄로 설명
---
## 지침
Claude가 이 Skill을 실행할 때 따라야 할 구체적인 지침을 작성한다.
1. 첫 번째 단계
2. 두 번째 단계
3. 세 번째 단계
가장 간단한 형태는 이것뿐이다. name과 description만 있으면 동작한다.
Step 1: 첫 번째 Skill 만들기
실전 예시로 코드 리뷰 Skill을 만들어 보자.
디렉토리 생성
mkdir -p .claude/skills
Skill 파일 작성
.claude/skills/review-code.md 파일을 생성한다.
---
name: review-code
description: 코드 리뷰를 수행한다. 보안, 성능, 가독성 관점에서 분석한다.
argument-hint: [파일 경로]
---
## 코드 리뷰 절차
지정된 파일에 대해 아래 관점으로 리뷰를 수행한다.
### 1. 보안 (Security)
- SQL 인젝션, XSS, 인증 우회 등 OWASP Top 10 취약점 확인
- 하드코딩된 시크릿이나 API 키 존재 여부
### 2. 성능 (Performance)
- N+1 쿼리, 불필요한 반복, 메모리 누수 가능성
- 캐싱 가능한 로직 식별
### 3. 가독성 (Readability)
- 변수/함수 네이밍 컨벤션 준수 여부
- 복잡한 로직에 대한 주석 필요성
### 4. 출력 형식
리뷰 결과를 아래 형식으로 정리한다:
- **심각도**: 🔴 Critical / 🟡 Warning / 🔵 Info
- **위치**: 파일명:라인번호
- **설명**: 문제점과 개선 방안
사용
# Claude Code에서 직접 호출
> /review-code src/auth/login.ts
Claude가 description을 읽고 관련 상황에서 자동으로 이 Skill을 로딩하기도 한다. “이 파일 리뷰해줘”라고 요청하면 Claude가 /review-code Skill을 감지해서 적용한다.
Step 2: Frontmatter 옵션 이해하기
Frontmatter는 Skill의 동작을 제어하는 설정이다. 모든 필드는 선택사항이지만, description은 반드시 작성하는 것이 좋다.
필수 권장 필드
| 필드 | 타입 | 설명 |
|---|---|---|
name |
String | / 뒤에 오는 명령어 이름. 생략 시 디렉토리명 사용 |
description |
String | Skill의 역할. Claude가 자동 감지에 사용 |
호출 제어 필드
| 필드 | 타입 | 설명 |
|---|---|---|
argument-hint |
String | 자동완성에서 인자 형태 표시. 예: [filename] [format] |
disable-model-invocation |
Boolean | true면 Claude가 자동 호출 불가. 사용자만 /로 직접 호출 |
user-invocable |
Boolean | false면 / 메뉴에 숨김. Claude만 내부적으로 사용 |
실행 환경 필드
| 필드 | 타입 | 설명 |
|---|---|---|
allowed-tools |
Array | Skill 실행 시 허용되는 도구 목록. 예: [Read, Grep, Bash] |
context |
String | fork 설정 시 독립 서브에이전트에서 실행 |
agent |
String | context: fork 시 에이전트 타입. Explore, Plan 등 |
model |
String | 이 Skill에 사용할 모델 지정 |
호출 제어 조합
| 설정 | 사용자가 호출? | Claude가 자동 호출? |
|---|---|---|
| 기본값 (둘 다 미설정) | ✅ | ✅ |
disable-model-invocation: true |
✅ | ❌ |
user-invocable: false |
❌ | ✅ |
부작용이 있는 Skill(배포, 커밋, 메시지 전송 등)에는 반드시 disable-model-invocation: true를 설정한다. 의도치 않은 자동 실행을 방지하기 위해서다.
Step 3: 변수 치환 활용하기
Skills는 동적 값을 주입할 수 있는 변수 치환(String Substitution)을 지원한다.
기본 변수
| 변수 | 설명 | 예시 |
|---|---|---|
$ARGUMENTS |
전달된 모든 인자 | /skill arg1 arg2 → arg1 arg2 |
$ARGUMENTS[0], $ARGUMENTS[1] |
특정 인자 접근 | 0-based 인덱스 |
$0, $1, $2 |
특정 인자 단축형 | $ARGUMENTS[N]과 동일 |
${CLAUDE_SESSION_ID} |
현재 세션 ID | 로깅/추적에 활용 |
실전 예시: 컴포넌트 생성 Skill
---
name: create-component
description: React 컴포넌트를 프로젝트 컨벤션에 맞게 생성한다
argument-hint: [컴포넌트명]
---
## 생성 규칙
`$0` 컴포넌트를 아래 구조로 생성한다:
1. `src/components/$0/$0.tsx` - 컴포넌트 본체
2. `src/components/$0/$0.test.tsx` - 테스트 파일
3. `src/components/$0/index.ts` - 배럴 파일(barrel export)
### 컴포넌트 컨벤션
- 함수형 컴포넌트 사용
- Props 타입은 `$0Props`로 정의
- CSS Modules 사용 (`$0.module.css`)
사용:
> /create-component SearchBar
$0이 SearchBar로 치환되어 Claude가 SearchBar.tsx, SearchBar.test.tsx, index.ts를 자동 생성한다.
Step 4: 고급 패턴
셸 명령어로 동적 컨텍스트 주입
Skills에서 !`command` 구문을 사용하면 셸 명령어의 결과를 프롬프트에 삽입할 수 있다. 이 명령어는 Claude에게 전달되기 전에 실행된다.
---
name: pr-review
description: 현재 PR을 리뷰한다
context: fork
agent: Explore
allowed-tools: [Bash(gh *)]
---
## PR 정보
- PR diff: !`gh pr diff`
- 변경된 파일: !`gh pr diff --name-only`
- PR 코멘트: !`gh pr view --comments`
## 리뷰 지침
위 PR의 변경 사항을 분석하고 리뷰를 작성한다.
코드 품질, 테스트 커버리지, 잠재적 버그를 중점적으로 확인한다.
gh pr diff의 실행 결과가 프롬프트에 삽입된 상태로 Claude에게 전달된다. Claude가 직접 명령어를 실행하는 것이 아니라 전처리(preprocessing) 단계에서 이루어진다.
서브에이전트로 격리 실행
context: fork를 설정하면 Skill이 독립된 서브에이전트에서 실행된다. 메인 대화 컨텍스트에 영향을 주지 않으므로, 탐색이나 분석 같은 작업에 적합하다.
---
name: find-bugs
description: 코드베이스에서 잠재적 버그를 탐색한다
context: fork
agent: Explore
---
프로젝트 전체를 탐색하여 잠재적 버그를 찾는다:
1. 에러 핸들링이 누락된 곳
2. 타입 안전성이 보장되지 않는 곳
3. 경쟁 조건(race condition) 가능성
4. 리소스 누수 (파일 핸들, DB 연결 등)
파일 경로와 라인 번호를 포함해서 결과를 정리한다.
Extended Thinking 활성화
Skill 본문에 ultrathink라는 키워드를 포함하면 Claude의 확장 사고(Extended Thinking) 모드가 활성화된다. 복잡한 분석이 필요한 Skill에서 활용할 수 있다.
---
name: architecture-review
description: 아키텍처 수준의 깊은 분석을 수행한다
---
ultrathink 모드로 아키텍처를 분석한다.
$ARGUMENTS에 대해:
1. 의존성 그래프 분석
2. 순환 의존성 검출
3. 레이어 위반 사항 확인
4. 개선 방안 제시
실전 예시: 이 블로그의 Skills
이 블로그 프로젝트에서 실제로 사용 중인 Skills를 소개한다. .claude/skills/ 디렉토리에 4개의 Skill이 정의되어 있다.
.claude/skills/
├── write-research-post.md # 논문 리뷰 포스트 작성
├── write-tech-post.md # 기술 포스트 작성
├── write-food-post.md # 음식 리뷰 포스트 작성
└── write-trip-post.md # 여행 포스트 작성
write-tech-post.md (발췌)
# Skill: Tech 포스트 작성
## 설명
기술, 개발, 바이오인포매틱스 도구에 대한 블로그 포스트를 작성한다.
## 작성 절차
1. 기술 주제와 범위를 확인한다
2. `_posts/` 디렉토리에 `YYYY-MM-DD-title-in-english.md` 형식으로 파일을 생성한다
3. 아래 템플릿에 따라 내용을 작성한다
## 작성 지침
- 명확하고 간결한 기술적 톤을 사용한다
- 코드 블록에는 반드시 언어 태그를 명시한다
- 단계별 설명을 선호한다
- 실행 가능한 예시 코드를 포함한다
이 Skill 덕분에 “Claude Code skills에 대한 기술 포스팅 적어줘”라고만 말하면, Claude가 자동으로 이 Skill을 감지하고 블로그의 포맷과 톤에 맞춰 포스트를 작성한다. frontmatter, 파일 위치, 마크다운 스타일까지 모두 Skill에 정의되어 있기 때문이다.
왜 효과적인가
- 일관성: 매번 같은 포맷으로 포스트가 생성된다
- 효율성: “이런 주제로 포스트 써줘” 한 마디면 끝이다
- 맥락 분리: 포스트 작성 규칙이 CLAUDE.md를 비대하게 만들지 않는다
- 공유 가능: Git에 커밋되므로 협업자도 같은 워크플로우를 사용할 수 있다
보조 파일 활용
Skill이 복잡해지면 SKILL.md 하나에 모든 내용을 담기 어렵다. 이때 보조 파일을 활용한다.
.claude/skills/deploy/
├── SKILL.md # 메인 지침 (500줄 이하 권장)
├── checklist.md # 배포 체크리스트
├── examples/
│ └── rollback.md # 롤백 예시
└── scripts/
└── validate.sh # 검증 스크립트
SKILL.md에서 보조 파일을 참조한다:
---
name: deploy
description: 프로덕션 배포를 수행한다
disable-model-invocation: true
---
## 배포 절차
배포 전 [checklist.md](checklist.md)를 확인한다.
문제 발생 시 [rollback.md](examples/rollback.md)를 참고한다.
Claude는 보조 파일을 필요할 때만 로딩하므로 컨텍스트를 효율적으로 사용한다.
도구 접근 제어
allowed-tools로 Skill이 사용할 수 있는 도구를 제한할 수 있다. 읽기 전용 Skill이 파일을 수정하는 사고를 방지하는 데 유용하다.
---
name: codebase-explorer
description: 코드베이스를 탐색하고 구조를 분석한다
allowed-tools: [Read, Grep, Glob]
---
이 Skill은 Read, Grep, Glob만 사용할 수 있다. Edit, Write, Bash 등의 도구는 차단된다.
도구별 세부 제한도 가능하다:
allowed-tools: [Bash(git *), Bash(npm test), Read, Grep]
Bash는 git과 npm test 명령어만 허용된다.
Best Practices
1. Description을 구체적으로 작성한다
Claude가 자동 감지에 description을 사용하므로, 어떤 상황에서 이 Skill이 필요한지 명확히 작성한다.
# ❌ 너무 모호
description: 코드를 처리한다
# ✅ 구체적
description: Python 함수에 대한 단위 테스트를 pytest 컨벤션으로 생성한다
2. 부작용이 있는 Skill은 보호한다
# 배포, 커밋, 메시지 전송 등
disable-model-invocation: true
3. SKILL.md는 500줄 이하로 유지한다
길어지면 보조 파일로 분리한다. Claude가 온디맨드로 로딩하므로 컨텍스트 효율이 좋다.
4. 프로젝트 Skills는 버전 관리한다
git add .claude/skills/
git commit -m "feat: add code review skill"
팀원 모두가 같은 Skill을 사용할 수 있게 된다.
5. 두 가지 호출 방식을 모두 테스트한다
- 직접 호출:
/skill-name arguments - 자동 감지: 관련 작업을 자연어로 요청
정리
| 핵심 포인트 | 설명 |
|---|---|
| Skill은 마크다운 파일 | YAML frontmatter + 마크다운 본문으로 구성 |
| 두 가지 스코프 | 프로젝트(.claude/skills/) 또는 개인(~/.claude/skills/) |
| 자동 감지 지원 | description을 기반으로 Claude가 관련 상황에서 자동 로딩 |
| 변수 치환 | $0, $ARGUMENTS 등으로 동적 값 주입 |
| 격리 실행 | context: fork로 서브에이전트에서 독립 실행 |
| 도구 제한 | allowed-tools로 Skill의 권한을 세밀하게 제어 |
Skills는 Claude Code를 범용 AI 도구에서 프로젝트 전용 어시스턴트로 바꿔준다. 반복되는 작업이 있다면 Skill로 만들어 보자. 한 번 정의하면 팀 전체가 일관된 워크플로우로 작업할 수 있다.
참고 자료
💬 댓글