Claude Code를 쓰다 보면 매번 비슷한 작업을 반복하게 됩니다. "블로그 글 써줘", "이 코드 리뷰해줘", "배포해줘" 같은 요청을 할 때마다 같은 맥락을 다시 설명하는 건 비효율적입니다. 이럴 때 필요한 게 바로 스킬(Skill) 입니다.
최근 Claude Code의 스킬 시스템이 1.0에서 2.0으로 크게 업그레이드되었습니다. 이 글에서는 무엇이 달라졌는지, 그리고 공식 문서 기반으로 스킬을 어떻게 만들고 활용하는지 다룹니다.
스킬 1.0 → 2.0, 무엇이 달라졌나?
기존 스킬 1.0은 .claude/commands/ 디렉토리에 마크다운 파일을 넣는 단순한 구조였습니다. 2.0에서는 이 구조가 크게 확장되었습니다.
주요 변경점
| 항목 | Skills 1.0 | Skills 2.0 |
|---|---|---|
| 파일 위치 | .claude/commands/deploy.md | skills/deploy/SKILL.md |
| 설정 | 없음 | YAML frontmatter |
| 실행 방식 | 메인 대화에서 실행 | context: fork로 서브에이전트 분리 가능 |
| 도구 제한 | 불가 | allowed-tools로 허용 도구 지정 |
| 자동 로딩 | 불가 | description으로 Claude가 자동 판단 |
| 디렉토리 구조 | 단일 파일 | 템플릿, 예제, 스크립트 포함 가능 |
| 동적 컨텍스트 | $ARGUMENTS만 | !`command`로 셸 명령 결과 주입 |
기존 .claude/commands/ 파일도 하위 호환되므로 기존 커맨드가 깨지지는 않습니다. 하지만 새로운 기능을 활용하려면 2.0 구조를 사용하는 것이 좋습니다.
Skills 2.0 기본 구조
Skills 2.0의 핵심은 SKILL.md 파일과 YAML frontmatter입니다.
디렉토리 구조
my-skill/
├── SKILL.md # 메인 지시사항 (필수)
├── template.md # Claude가 채울 템플릿
├── examples/
│ └── sample.md # 예상 결과물 예시
└── scripts/
└── validate.sh # Claude가 실행할 스크립트
SKILL.md 작성법
SKILL.md는 YAML frontmatter와 마크다운 본문으로 구성됩니다.
---
name: code-review
description: 코드 품질과 잠재적 이슈를 검토합니다. 코드 리뷰, PR 확인, 품질 분석 시 사용하세요.
---
코드 리뷰 시 다음을 확인하세요:
1. 코드 구조와 조직
2. 에러 핸들링
3. 보안 이슈
4. 테스트 커버리지
name 필드가 곧 /code-review 슬래시 커맨드가 됩니다. description은 Claude가 자동으로 스킬을 로딩할지 판단하는 기준입니다.
frontmatter 주요 필드
---
name: skill-name # 슬래시 커맨드 이름
description: 설명 # 자동 로딩 판단 기준
context: fork # fork: 서브에이전트로 분리 실행
agent: Explore # 사용할 서브에이전트 (Explore, Plan 등)
allowed-tools: Read, Bash(git:*) # 허용할 도구 제한
argument-hint: [파일경로] # 인자 힌트
---
context: fork — 가장 큰 변화
Skills 2.0에서 가장 중요한 기능은 context: fork입니다. 이전에는 모든 스킬이 메인 대화 컨텍스트에서 실행되었지만, 이제는 독립된 서브에이전트에서 실행할 수 있습니다.
---
name: deep-research
description: 주제를 깊이 조사합니다
context: fork
agent: Explore
---
$ARGUMENTS에 대해 철저히 조사하세요:
1. Glob과 Grep으로 관련 파일 찾기
2. 코드를 읽고 분석하기
3. 구체적인 파일 참조와 함께 결과 요약
context: fork의 장점은 세 가지입니다.
컨텍스트 보호: 메인 대화의 컨텍스트 윈도우를 소모하지 않습니다. 대규모 조사 작업을 해도 메인 대화는 깔끔하게 유지됩니다.
격리 실행: 스킬이 독립적으로 실행되므로, 실패하더라도 메인 대화에 영향을 주지 않습니다.
에이전트 지정: agent: Explore처럼 목적에 맞는 서브에이전트를 지정할 수 있습니다.
동적 컨텍스트 주입: !command 문법
Skills 2.0에서 추가된 또 다른 강력한 기능은 셸 명령 결과를 스킬에 주입하는 것입니다.
---
name: pr-summary
description: PR 변경사항을 요약합니다
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
## PR 컨텍스트
- PR diff: !`gh pr diff`
- PR 댓글: !`gh pr view --comments`
- 변경된 파일: !`gh pr diff --name-only`
!`gh pr diff` 문법을 사용하면, 스킬이 실행되는 시점에 명령이 먼저 실행되고 그 결과가 프롬프트에 삽입됩니다. 정적인 프롬프트가 아니라 실시간 데이터를 기반으로 작업할 수 있습니다.
실전 스킬 예제
코드 설명 스킬
---
name: explain-code
description: 코드를 다이어그램과 비유로 설명합니다. "이게 어떻게 동작해?"라고 물을 때 사용하세요.
---
코드를 설명할 때 항상 포함하세요:
1. **비유로 시작**: 일상생활의 무언가에 비교
2. **다이어그램 그리기**: ASCII 아트로 흐름이나 구조를 표현
3. **코드 워크스루**: 단계별로 무슨 일이 일어나는지 설명
4. **주의사항 강조**: 흔한 실수나 오해는 무엇인지
복잡한 개념은 여러 비유를 사용하세요.
배포 자동화 스킬
---
name: deploy
description: 프로덕션 배포를 실행합니다
allowed-tools: Bash(npm:*), Bash(firebase:*)
---
## 배포 순서
1. `npm run lint`로 코드 검사
2. `npm run build`로 프로덕션 빌드
3. 빌드 에러가 없으면 `firebase deploy --only hosting`
4. 배포 URL과 상태를 보고
컴포넌트 생성 스킬
---
name: component
description: React 컴포넌트를 생성합니다
argument-hint: [컴포넌트명]
---
$ARGUMENTS 컴포넌트를 생성하세요:
1. `src/components/` 아래에 파일 생성
2. TypeScript props 인터페이스 포함
3. 프로젝트의 디자인 시스템 컨벤션 준수
4. 필요시 테스트 파일도 함께 생성
스킬 작성 팁
description을 잘 작성하세요. Claude가 자동으로 스킬을 로딩할지 판단하는 기준입니다. "어떤 상황에서 사용하는지"를 명시하면 더 정확하게 동작합니다.
allowed-tools로 범위를 제한하세요. 배포 스킬에는 Bash(firebase:*)만, 리서치 스킬에는 Read만 허용하는 식으로 안전하게 관리할 수 있습니다.
프로젝트 스킬 vs 사용자 스킬: .claude/commands/에 만들면 프로젝트 전용, ~/.claude/commands/에 만들면 모든 프로젝트에서 사용 가능합니다.
마무리: 반복을 자동화하세요
스킬 2.0의 핵심은 "더 안전하고, 더 강력하게"입니다. context: fork로 격리 실행하고, allowed-tools로 권한을 제한하고, !`command`로 실시간 데이터를 주입할 수 있습니다.
자주 하는 작업을 스킬로 만들어두면, 한 줄의 명령으로 복잡한 워크플로우를 실행할 수 있습니다. 처음에는 간단한 /deploy, /review부터 시작해보세요.
AI 도구는 완벽하지 않습니다. 하지만 잘 정의된 스킬은 Claude Code의 일관성과 정확도를 크게 높여줍니다.
