스킬 (Skills)

공식 문서: https://code.claude.com/docs/ko/skills

스킬이란?

스킬(Skills)은 Claude Code에 새로운 능력을 가르치거나 자주 쓰는 워크플로우를 패키징한 재사용 가능한 확장 기능입니다. /스킬이름으로 직접 실행하거나, Claude가 상황에 맞게 자동으로 실행할 수 있습니다.

CLAUDE.md가 "항상 적용되는 일반 규칙"이라면, 스킬은 **"필요할 때만 불러오는 전문 도구"**에 가깝습니다.

---

스킬 구성 요소 (SKILL.md 해부)

🏷️

이름 (name)

name: deploy

호출 시 사용할 슬래시 명령어 이름. /deploy 형태로 실행됩니다.

📝

설명 (description)

description: 배포 실행

Claude가 언제 이 스킬을 자동 호출할지 판단하는 기준이 됩니다.

⚡

실행 옵션 (context)

context: fork

fork — 유효한 유일한 값. 격리된 서브에이전트 컨텍스트에서 실행합니다. 생략 시 인라인(기본) 실행됩니다.

📋

지침 (prompt body)

1. 테스트 실행
2. 빌드
3. 배포

frontmatter 아래의 마크다운 본문. Claude에게 전달되는 단계별 작업 지침입니다.

파일 위치: .claude/skills/deploy/SKILL.md  →  /deploy 로 호출

---

오픈 스탠다드

Claude Code 스킬은 Agent Skills 오픈 스탠다드를 따릅니다. 다른 AI 도구에서도 사용할 수 있는 범용 표준입니다.

기본 제공 스킬 빠른 참조

스킬	명령어	용도	실행 방식
Batch	/batch	대규모 병렬 코드 변경 (50+ 파일)	병렬 워크트리 에이전트
Claude API	/claude-api	Claude API/SDK 레퍼런스 로딩	인라인 참조
Code Review	/code-review	diff 정확성·버그·코드 품질 검토	병렬 에이전트
Debug	/debug	디버그 로깅 활성화 및 분석	인라인
Doctor	/doctor	설정 점검 및 설치 문제 진단·수정	인라인
Loop	/loop	프롬프트 주기적 반복 실행	크론 작업
Run	/run	앱을 시작하고 변경 사항이 실제로 작동하는지 확인	인라인
Run-Skill-Generator	/run-skill-generator	/run·/verify 스킬을 프로젝트에 맞게 생성	인라인
Simplify	/simplify	코드 품질 자동 개선 (3개 병렬 리뷰)	병렬 에이전트
Verify	/verify	앱을 빌드·실행하여 코드 변경 동작 검증	인라인

CLAUDE.md와의 차이

구분	CLAUDE.md	스킬
로딩 시점	매 세션 시작 시 항상	필요할 때만 (온디맨드)
구성	단일 파일	디렉토리 (메인 파일 + 보조 파일)
호출 방식	자동	/이름 또는 Claude 자동 판단
용도	프로젝트 전반 규칙	특정 작업 워크플로우
컨텍스트	항상 컨텍스트에 포함	호출 시에만 로딩

스킬의 두 가지 유형

스킬 내용은 크게 두 가지 성격으로 나뉩니다:

참조 콘텐츠(Reference Content) - Claude가 현재 작업에 참고하는 지식입니다. 코딩 컨벤션, 아키텍처 패턴, 스타일 가이드 등이 해당됩니다. 인라인으로 실행되어 대화 컨텍스트와 함께 사용됩니다.

---
name: api-conventions
description: 이 코드베이스의 API 설계 패턴
---

API 엔드포인트 작성 시:
- RESTful 네이밍 규칙 사용
- 일관된 에러 형식 반환
- 요청 유효성 검사 포함

태스크 콘텐츠(Task Content) - Claude에게 단계별 작업 지침을 제공합니다. 배포, 커밋, 코드 생성 등 구체적인 행동을 지시합니다. 보통 /skill-name으로 직접 호출하며, disable-model-invocation: true로 자동 호출을 방지합니다.

---
name: deploy
description: 프로덕션에 애플리케이션 배포
context: fork
disable-model-invocation: true
---

애플리케이션을 배포합니다:
1. 테스트 스위트 실행
2. 애플리케이션 빌드
3. 배포 타겟에 푸시

기본 제공 스킬 (Bundled Skills)

Claude Code에는 여러 프롬프트 기반 스킬이 기본 내장되어 있습니다. 고정 로직으로 동작하는 내장 명령어(/help, /compact, /init 등)와 달리, 이 스킬들은 Claude에게 상세한 플레이북을 제공하여 병렬 에이전트를 띄우고, 파일을 읽고, 코드베이스에 맞게 유연하게 작업합니다.

/batch - 대규모 병렬 코드 변경

용도: 코드베이스 전체에 걸친 대규모 변경을 병렬로 처리합니다.

동작 방식:

1. 코드베이스를 분석하여 작업을 5~30개 독립 단위로 분해
2. 분해 계획을 사용자에게 보여주고 승인 요청
3. 승인 후 각 단위마다 **별도의 Git 워크트리(Worktree)**에서 백그라운드 에이전트 실행
4. 각 에이전트가 구현 → 테스트 → PR 생성까지 자동 수행

요구사항

/batch는 Git 저장소에서만 작동합니다. 각 작업 단위가 격리된 워크트리에서 실행되므로 Git이 필수입니다.

실전 활용 예시:

# 프레임워크 마이그레이션
/batch src/ 전체를 Solid에서 React로 마이그레이션

# 테스트 프레임워크 전환
/batch tests/ 디렉토리의 모든 테스트를 Jest에서 Vitest로 변환

# 일괄 리팩토링
/batch src/api/ 의 모든 엔드포인트에 Zod 스키마 유효성 검사 추가

# 다국어 지원
/batch src/ 의 모든 하드코딩된 문자열을 i18n 키로 교체

# 의존성 업데이트
/batch 모든 컴포넌트에서 deprecated된 lodash 함수를 ES2024 네이티브 메서드로 교체

# 접근성 개선
/batch src/components/ 의 모든 UI 컴포넌트에 ARIA 속성과 키보드 내비게이션 추가

팁: /batch는 각 작업이 독립적일 때 가장 효과적입니다. 서로 의존성이 있는 변경 사항은 하나의 단위로 묶거나 수동으로 처리하세요.

/claude-api - Claude API/SDK 레퍼런스 로딩

용도: Claude API 사용법, SDK 레퍼런스, Agent SDK 문서를 세션에 로딩합니다.

자동 활성화: 코드에서 anthropic, @anthropic-ai/sdk, claude_agent_sdk를 import하면 자동으로 활성화됩니다.

지원 언어: Python, TypeScript, Java, Go, Ruby, C#, PHP, cURL

포함 내용:

• 도구 사용(Tool Use) 패턴
• 스트리밍(Streaming) 구현
• 배치(Batch) 처리
• 구조화된 출력(Structured Output)
• 흔한 실수와 해결법

실전 활용 예시:

# TypeScript SDK 레퍼런스 로딩
/claude-api typescript

# Python으로 Tool Use 구현할 때
/claude-api python
# 이후: "Tool Use로 날씨 API를 호출하는 에이전트를 만들어줘"

# Agent SDK 사용
/claude-api
# 이후: "Agent SDK로 멀티스텝 워크플로우를 구현해줘"

팁: /claude-api를 먼저 실행한 후 구체적인 질문을 하면, Claude가 정확한 SDK 문법과 패턴으로 코드를 작성합니다. import문에 anthropic이 포함된 파일을 편집할 때는 자동으로 레퍼런스가 로딩됩니다.

/debug - 디버그 로깅 및 분석

용도: 세션의 디버그 로깅을 활성화하고, 로그를 분석하여 문제를 진단합니다.

동작 방식:

• 기본적으로 디버그 로깅은 꺼져 있음 (claude --debug로 시작하지 않는 한)
• /debug 실행 시점부터 로그 캡처 시작
• 선택적으로 이슈 설명을 전달하면 해당 문제에 집중하여 분석

실전 활용 예시:

# 디버그 모드 활성화
/debug

# 특정 문제 분석을 위해 활성화
/debug MCP 서버 연결이 자꾸 끊기는 문제

# 성능 문제 진단
/debug 파일 검색이 비정상적으로 느림

# 도구 실행 오류 추적
/debug Bash 도구가 타임아웃 되는 이유 분석

팁: 문제가 간헐적으로 발생할 때 /debug를 먼저 실행해두고, 문제가 재현되면 로그를 기반으로 분석할 수 있습니다.

/loop - 주기적 프롬프트 반복 실행

용도: 프롬프트를 정해진 간격으로 반복 실행합니다. 배포 모니터링, PR 관찰, 주기적 검사에 유용합니다.

문법: /loop [간격] <프롬프트> (간격 생략 시 모델이 자율 조정)

간격 형식: 5m (5분), 30s (30초), 1h (1시간)

실전 활용 예시:

# 배포 상태 모니터링 (5분마다)
/loop 5m 배포가 완료되었는지 확인하고 결과를 알려줘

# PR CI 상태 감시 (3분마다)
/loop 3m gh pr checks를 확인하고 실패한 것이 있으면 알려줘

# 서버 헬스체크 (1분마다)
/loop 1m curl로 https://api.example.com/health 를 확인하고 200이 아니면 경고

# 빌드 로그 모니터링
/loop 2m 빌드 로그에서 새로운 에러가 있는지 확인

# 테스트 결과 폴링
/loop 5m pytest 결과 파일을 확인하고 실패한 테스트가 있으면 보고

팁: 세션이 열려 있는 동안만 동작합니다. 세션을 닫으면 루프도 종료됩니다. 장기 실행이 필요하면 스케줄 작업을 사용하세요.

/simplify - 코드 품질 자동 개선

용도: 최근 변경된 파일을 3개의 리뷰 에이전트가 병렬로 검토하고 개선합니다.

검토 영역:

1. 코드 재사용: 중복 코드, 공통 로직 추출 가능성
2. 코드 품질: 가독성, 네이밍, 복잡도
3. 효율성: 불필요한 연산, 메모리 사용, 알고리즘 최적화

실전 활용 예시:

# 전체 품질 검토
/simplify

# 특정 관점에 집중
/simplify 메모리 효율에 집중

# 성능 최적화 관점
/simplify 렌더링 성능과 불필요한 re-render에 집중

# 보안 관점
/simplify 입력 유효성 검사와 SQL 인젝션 방어에 집중

# 타입 안전성 관점
/simplify TypeScript 타입 추론과 any 사용 제거에 집중

팁: 기능 구현 후 커밋하기 전에 /simplify를 실행하면 코드 리뷰에서 지적받을 사항을 미리 잡을 수 있습니다.

/code-review - 코드 리뷰

용도: 현재 diff를 대상으로 정확성 버그와 코드 개선점을 검토합니다.

문법: /code-review [low|medium|high|xhigh|max|ultracode] [--fix] [--comment] [target]

옵션:

• 노력 수준 지정 (기본값: 세션 설정)
• --fix: 발견된 문제를 자동으로 수정
• --comment: PR에 리뷰 코멘트 추가
• target: 검토할 파일/디렉토리 지정

# 현재 변경 사항 리뷰
/code-review

# 높은 강도로 자동 수정 포함
/code-review high --fix

# 특정 디렉토리만 리뷰
/code-review src/api/

/run - 앱 실행 및 변경 사항 검증

용도: 앱을 시작하고 코드 변경이 실제로 작동하는지 확인합니다.

/run

팁: /run-skill-generator를 먼저 실행하면 프로젝트 빌드/시작 방법을 학습시켜 더 정확하게 작동합니다.

/verify - 빌드·실행으로 변경 사항 검증

용도: 앱을 빌드하고 실행하여 코드 변경이 의도대로 작동하는지 확인합니다. 테스트·타입 체크와는 별도로 실제 실행을 통해 검증합니다.

/verify

/run-skill-generator - 프로젝트 실행 스킬 생성

용도: /run과 /verify 스킬이 현재 프로젝트의 빌드 및 시작 방법을 학습하도록 프로젝트 전용 스킬을 생성합니다.

/run-skill-generator

내장 명령어와 스킬의 차이

/help, /compact, /init, /memory, /config 등은 고정 로직으로 동작하는 내장 명령어입니다. 위의 스킬들은 프롬프트 기반 스킬로, Claude가 지침을 따라 병렬 에이전트를 띄우고 유연하게 작업합니다. 내장 명령어 목록은 CLI 레퍼런스를 참고하세요.

첫 번째 스킬 만들기

1단계: 디렉토리 생성

# 개인 스킬 (모든 프로젝트에서 사용)
mkdir -p ~/.claude/skills/explain-code

# 프로젝트 스킬 (이 프로젝트에서만 사용)
mkdir -p .claude/skills/explain-code

2단계: SKILL.md 작성

모든 스킬은 SKILL.md 파일이 필요합니다. 두 부분으로 구성됩니다:

1. YAML 프론트매터(Frontmatter): --- 마커 사이에 스킬 설정 (이름, 설명 등)
2. 마크다운 본문: Claude에게 전달할 지침

예시: 코드 설명 스킬

---
name: explain-code
description: 코드를 비유와 다이어그램으로 설명합니다. "이 코드가 어떻게 동작해?"라는 질문에 사용합니다.
---

코드를 설명할 때 다음 순서를 따르세요:

1. **비유로 시작**: 일상생활의 무언가에 비유하여 개념을 소개
2. **다이어그램 그리기**: ASCII 아트로 흐름/구조를 시각화
3. **코드 따라가기**: 단계별로 무슨 일이 일어나는지 설명
4. **주의할 점**: 흔히 하는 실수나 오해 언급

설명은 대화하듯 자연스럽게 작성하세요.

3단계: 사용하기

# 직접 호출
/explain-code src/auth/login.ts

# Claude가 자동으로 호출 (description에 매칭되는 질문을 하면)
> 이 코드가 어떻게 동작하는지 설명해줘

두 가지 방법 모두 Claude가 비유와 ASCII 다이어그램을 포함한 설명을 제공합니다.

스킬 저장 위치

스킬을 어디에 저장하느냐에 따라 사용 범위가 결정됩니다:

위치	경로	사용 범위	우선순위
조직(관리)	관리 설정으로 배포	조직 전체	1순위 (최우선)
개인	~/.claude/skills/이름/	모든 프로젝트	2순위
프로젝트	.claude/skills/이름/	현재 프로젝트만	3순위
플러그인	플러그인/skills/이름/	플러그인 활성화 시	네임스페이스 구분
추가 디렉토리	--add-dir 경로 내	해당 디렉토리	예외적 로딩

같은 이름의 스킬이 여러 위치에 있으면, 우선순위가 높은 쪽이 사용됩니다. 개인 스킬이 프로젝트 스킬보다 우선순위가 높습니다. 플러그인 스킬은 plugin-name:skill-name 네임스페이스를 사용하므로 충돌하지 않습니다.

모노레포 지원

하위 디렉토리의 .claude/skills/도 자동 발견됩니다. 예를 들어 packages/frontend/.claude/skills/에 프론트엔드 전용 스킬을 둘 수 있습니다.

기존 commands 호환

.claude/commands/ 경로의 기존 커맨드 파일도 계속 작동합니다. 같은 이름의 skill과 command가 있으면 skill이 우선됩니다. Skills는 보조 파일, 프론트매터 호출 제어, Claude 자동 로딩 등 추가 기능을 지원합니다.

스킬 디렉토리 구조

각 스킬은 SKILL.md를 포함하는 디렉토리입니다:

my-skill/
├── SKILL.md           # 메인 지침 (필수, 500줄 이내 권장)
├── template.md        # Claude가 채울 템플릿
├── examples/
│   └── sample.md      # 기대하는 출력 형식 예시
└── scripts/
    └── validate.sh    # Claude가 실행할 수 있는 스크립트

프론트매터 전체 레퍼런스

스킬의 동작을 세밀하게 제어하는 16개 설정 필드입니다. 모든 필드는 선택사항이며, description만 권장됩니다:

필드	설명	예시
name	스킬 이름 (/name으로 호출). 소문자, 숫자, 하이픈. 최대 64자. 미지정 시 디렉토리명 사용	fix-issue
description	스킬 설명 (Claude 자동 호출 판단에 사용). description과 when_to_use를 합산한 텍스트가 1,536자로 잘리므로 핵심 용도를 앞에 배치	GitHub 이슈를 분석하고 수정합니다
when_to_use	Claude가 이 스킬을 자동으로 호출할 시점 설명. description을 보완하는 상세 트리거 조건	사용자가 이슈 번호를 언급하면 실행
argument-hint	자동완성에 표시되는 인자 힌트	[이슈번호], [파일명] [형식]
disable-model-invocation	true면 사용자만 호출 가능 (Claude 자동 호출 불가)	true
user-invocable	false면 / 메뉴에서 숨김 (Claude만 호출 가능)	false
allowed-tools	자동 승인할 도구 목록 (공백 구분 또는 YAML 리스트)	Bash Read Grep
disallowed-tools	이 스킬 활성화 시 Claude의 도구 풀에서 제거할 도구 목록	WebFetch Bash
model	이 스킬에서 사용할 모델 (세션 모델 오버라이드)	sonnet, opus
effort	노력 수준 (세션 설정 오버라이드)	low, medium, high, xhigh
context	fork 설정 시 격리된 서브에이전트에서 실행	fork
agent	context: fork 시 사용할 에이전트 유형	Explore, Plan, general-purpose
hooks	스킬 라이프사이클에 스코프된 훅	아래 예시 참고
paths	이 글로브 패턴 파일 작업 시만 자동 활성화 (콤마 구분 또는 YAML 리스트)	src/**/*.ts, *.py
shell	인라인 셸 명령어 실행 시 사용할 셸. Windows에서 PowerShell 사용 시 CLAUDE_CODE_USE_POWERSHELL_TOOL=1 환경변수도 설정	bash (기본값), powershell
preload	⚠️ 비공식 필드 — 세션 시작 시 스킬 미리 로드 여부. 공식 문서에 명시되지 않은 확장 필드	true
arguments	이름이 있는 위치 인자 정의 (배열). $0, $1 대신 설명적 이름 제공	[issue_number, priority]

프론트매터 전체 예시:

---
name: deploy
description: 프로덕션 배포를 수행합니다
argument-hint: "[환경]"
disable-model-invocation: true
allowed-tools: Bash(npm *) Bash(git *)
model: sonnet
effort: xhigh
context: fork
agent: general-purpose
paths: "src/**,deploy/**"
shell: bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

호출 제어 매트릭스

설정	사용자 호출	Claude 자동 호출	설명이 컨텍스트에 로딩	전체 스킬 로드 시점
기본값 (설정 없음)	✅	✅	✅ (항상)	호출 시
disable-model-invocation: true	✅	❌	❌ (컨텍스트에 없음)	사용자가 호출할 때만
user-invocable: false	❌	✅	✅ (항상)	호출 시

언제 무엇을 쓸까?

사용 시나리오	추천 설정	이유
범용 스킬 (코드 리뷰, 설명 등)	기본값	사용자와 Claude 모두 자유롭게 사용
부작용이 있는 작업 (배포, 커밋, Slack 메시지 전송)	disable-model-invocation: true	Claude가 함부로 배포하는 것을 방지
배경 지식 제공 (레거시 시스템 문맥, 도메인 지식)	user-invocable: false	/legacy-context는 의미 있는 액션이 아님

인자 (Arguments) 사용

스킬에 인자를 전달할 수 있습니다. Claude가 스킬 내용을 읽기 전에 변수가 치환됩니다.

인자 변수

변수	설명	예시
$ARGUMENTS	전체 인자 문자열	/fix-issue 42 urgent → 42 urgent
$ARGUMENTS[0], $ARGUMENTS[1]	인덱스로 접근	/fix-issue 42 → $ARGUMENTS[0] = 42
$0, $1, $2	위치별 단축 표기	/migrate Button React Vue → $0=Button, $1=React, $2=Vue

특수 변수

변수	설명	용도
${CLAUDE_SESSION_ID}	현재 세션 ID	세션별 로그 파일, 추적
${CLAUDE_SKILL_DIR}	스킬의 SKILL.md가 있는 디렉토리 경로	번들된 스크립트/파일 참조
${CLAUDE_EFFORT}	현재 노력 수준: low, medium, high, xhigh	노력 수준에 따라 스킬 동작 분기

인자 예시

---
name: fix-issue
description: GitHub 이슈를 수정합니다
argument-hint: "[이슈번호]"
disable-model-invocation: true
---

GitHub 이슈 $ARGUMENTS를 수정하세요.

1. 이슈 설명을 읽고 이해
2. 관련 코드 찾기
3. 수정 구현
4. 테스트 실행
5. 커밋 생성

사용:

/fix-issue 42
# Claude는 "GitHub 이슈 42를 수정하세요."로 해석

$ARGUMENTS가 없을 때

스킬 내용에 $ARGUMENTS가 포함되어 있지 않아도, 인자를 전달하면 Claude Code가 자동으로 ARGUMENTS: <값>을 스킬 끝에 추가합니다.

위치 인자 예시:

---
name: migrate-component
description: 컴포넌트를 다른 프레임워크로 마이그레이션합니다
---

$0 컴포넌트를 $1에서 $2로 마이그레이션하세요.
기존의 모든 동작과 테스트를 유지하세요.

/migrate-component SearchBar React Vue
# $0=SearchBar, $1=React, $2=Vue

보조 파일 추가

SKILL.md에 모든 내용을 넣지 않고, 상세 내용은 별도 파일로 분리할 수 있습니다:

my-skill/
├── SKILL.md           # 메인 지침 (필수, 500줄 이내 권장)
├── reference.md       # 상세 API 문서 (필요 시 로딩)
├── examples.md        # 사용 예시 (필요 시 로딩)
├── template.md        # 생성 템플릿
└── scripts/
    └── helper.sh      # 유틸리티 스크립트 (실행 대상)

보조 파일은 온디맨드(On-demand)로 로딩됩니다. 대용량 레퍼런스 문서, API 스펙, 예시 컬렉션은 매번 로딩할 필요 없이 필요할 때만 불러옵니다.

SKILL.md에서 참조하여 Claude가 필요할 때 로딩하도록 안내:

## 추가 리소스

- 상세 API 문서는 [reference.md](reference.md)를 참고하세요.
- 사용 예시는 [examples.md](examples.md)를 참고하세요.

라이브 변경 감지

Claude Code는 스킬 디렉토리의 파일 변경을 자동으로 감시합니다. ~/.claude/skills/, 프로젝트 .claude/skills/, 또는 --add-dir 디렉토리 내의 .claude/skills/ 아래에서 스킬을 추가·편집·제거하면 Claude Code를 재시작하지 않고도 현재 세션 내에서 즉시 반영됩니다.

재시작이 필요한 경우

세션이 시작되었을 때 존재하지 않았던 최상위 skills 디렉토리를 새로 생성하는 경우에는 Claude Code를 재시작해야 새 디렉토리를 감시할 수 있습니다.

스킬 콘텐츠 자동 재첨부

/compact나 자동 압축으로 대화가 요약될 때, Claude Code는 요약 후 각 스킬의 가장 최근 호출을 자동으로 재첨부합니다. 재첨부된 스킬은 처음 5,000토큰을 유지하며, 모든 재첨부 스킬이 25,000토큰의 결합 예산을 공유합니다.

컨텍스트 포크 (서브에이전트 실행)

context: fork를 설정하면 스킬이 **격리된 서브에이전트(Sub-agent)**에서 실행됩니다. 스킬 내용이 서브에이전트의 프롬프트가 됩니다.

일반 스킬 vs 포크된 스킬

항목	일반 스킬 (인라인)	포크된 스킬 (context: fork)
대화 히스토리	접근 가능	접근 불가
컨텍스트 윈도우	메인 세션과 공유	별도의 새 컨텍스트
결과 전달	직접 대화에 포함	요약되어 반환
적합한 작업	가이드라인, 참조	대규모 리서치, 탐색, 배포

---
name: deep-research
description: 주제를 깊이 조사합니다
context: fork
agent: Explore
---

$ARGUMENTS에 대해 철저히 조사하세요:
1. Glob과 Grep으로 관련 파일 찾기
2. 코드 읽고 분석
3. 구체적인 파일 참조와 함께 결과 요약

context: fork 주의사항

context: fork는 명확한 작업 지시가 있는 스킬에서만 사용하세요. "이런 API 컨벤션을 따르세요" 같은 가이드라인만 포함된 스킬을 포크하면, 서브에이전트가 할 일을 찾지 못해 의미 없는 결과를 반환합니다.

사용 가능한 에이전트 유형

에이전트	설명	사용 사례
general-purpose (기본값)	전체 도구 접근	코드 수정, 명령어 실행, 파일 생성
Explore	읽기 전용 도구만	코드베이스 탐색, 리서치, 분석
Plan	분석/계획 도구	설계, 아키텍처 검토, 구현 계획
커스텀 에이전트	.claude/agents/에서 정의	프로젝트별 특화 에이전트

스킬과 서브에이전트의 관계

접근 방식	시스템 프롬프트	태스크	추가 로딩
스킬 + context: fork	에이전트 유형에서 제공	SKILL.md 내용	CLAUDE.md
서브에이전트 + skills 필드	서브에이전트의 마크다운 본문	Claude의 위임 메시지	프리로드된 스킬 + CLAUDE.md

동적 컨텍스트 주입

스킬 내용에 !`명령어` 문법을 사용하면, Claude가 스킬을 읽기 전에 셸 명령어를 실행하여 그 결과를 스킬에 삽입합니다. 이것은 **전처리(Preprocessing)**이며, Claude가 실행하는 것이 아닙니다.

인라인 명령어

---
name: pr-review
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`

## 리뷰 지침
위 PR 정보를 바탕으로 다음을 검토하세요:
1. 보안 이슈
2. 성능 문제
3. 코딩 컨벤션 준수

멀티라인 명령어

여러 줄의 명령어는 ```! 코드 블록을 사용합니다:

## 환경 정보
```!
node --version
npm --version
git status --short
```

Extended Thinking 활성화

스킬 내용에 "ultrathink"이라는 단어를 포함하면 해당 스킬에서 Extended Thinking(사고 모드)이 활성화됩니다.

셸 실행 비활성화

보안 정책으로 동적 컨텍스트 주입을 비활성화하려면 설정에서 "disableSkillShellExecution": true를 설정합니다. 각 명령어가 [shell command execution disabled by policy]로 대체됩니다. 번들(기본 제공) 스킬과 관리(조직) 스킬은 영향받지 않습니다.

시각적 출력 생성

스킬은 번들된 스크립트를 실행할 수 있어, 단순한 프롬프트를 넘어선 강력한 기능을 구현할 수 있습니다. 대표적인 패턴이 인터랙티브 HTML 파일을 생성하여 브라우저에서 데이터를 탐색하는 것입니다.

예시: 코드베이스 시각화 스킬

디렉토리 트리를 인터랙티브 HTML로 시각화하는 스킬입니다:

1. 디렉토리 생성:

mkdir -p ~/.claude/skills/codebase-visualizer/scripts

2. SKILL.md 작성 (~/.claude/skills/codebase-visualizer/SKILL.md):

---
name: codebase-visualizer
description: 코드베이스의 인터랙티브 트리 시각화를 생성합니다. 새 레포 탐색, 프로젝트 구조 파악, 대용량 파일 식별에 사용합니다.
allowed-tools: Bash(python *)
---

# 코드베이스 시각화

프로젝트 루트에서 시각화 스크립트를 실행하세요:

```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .

현재 디렉토리에 codebase-map.html이 생성되고 브라우저에서 열립니다.

**3. Python 스크립트 작성** (`scripts/visualize.py`): 디렉토리를 스캔하여 접을 수 있는 트리, 파일 크기, 타입별 색상이 포함된 HTML 파일을 생성합니다.

**사용법**:

```bash
# Claude에게 자연어로 요청
> 이 코드베이스를 시각화해줘

# 또는 직접 호출
/codebase-visualizer

이 패턴은 의존성 그래프, 테스트 커버리지 리포트, API 문서, DB 스키마 시각화 등 다양한 시각적 출력에 적용할 수 있습니다.

스킬 접근 제한

도구 접근 제한

allowed-tools 필드로 스킬 실행 중 사용할 수 있는 도구를 제한합니다:

---
name: safe-reader
description: 파일을 읽기만 하고 수정하지 않습니다
allowed-tools: Read Grep Glob
---

코드를 탐색하되 수정하지 마세요.

Claude의 스킬 접근 제어

Claude가 스킬을 호출하는 것을 세 가지 방법으로 제어할 수 있습니다:

1. 모든 스킬 비활성화 - /permissions에서 Skill 도구를 deny:

# deny 규칙에 추가:
Skill

2. 특정 스킬만 허용/차단 - 권한 규칙 사용:

# 특정 스킬만 허용
Skill(commit)
Skill(review-pr *)

# 특정 스킬 차단
Skill(deploy *)

권한 문법: Skill(이름) 정확히 일치, Skill(이름 *) 접두사 일치 + 모든 인자.

3. 개별 스킬 숨기기 - 프론트매터에 disable-model-invocation: true 설정.

설명 문자 예산

스킬 설명은 Claude가 사용 가능한 스킬을 파악할 수 있도록 컨텍스트에 로딩됩니다. 스킬이 많으면 설명이 축약될 수 있습니다. 예산은 컨텍스트 윈도우의 1% (폴백 8,000자)로 동적 설정됩니다.

예산을 늘리려면 환경 변수를 설정하세요:

export SLASH_COMMAND_TOOL_CHAR_BUDGET=16000

각 스킬의 description과 when_to_use를 합산한 텍스트는 1,536자로 잘리므로, 핵심 용도를 설명 앞부분에 배치하세요.

스킬 콘텐츠 생명주기

활성화된 스킬의 전체 콘텐츠(SKILL.md 내용)는 다음 규칙에 따라 컨텍스트에 유지됩니다:

구분	설명
전체 콘텐츠 유지 예산	최대 25,000 토큰. 이 이하이면 전체 스킬 콘텐츠가 컨텍스트에 포함됩니다.
보존 예산	/compact 또는 컨텍스트 압축 후에는 핵심 내용 5,000 토큰이 보존됩니다.
재로딩	/compact 후 스킬 콘텐츠가 25,000 토큰 이내이면 전체가 다시 컨텍스트에 첨부됩니다.

이를 통해 컨텍스트 압축(compact) 이후에도 중요한 스킬 내용이 유지됩니다.

실시간 스킬 변경 감지

개발 중에 SKILL.md를 수정하면 즉시 반영됩니다. Claude Code는 스킬 파일의 변경을 감지하여 세션을 재시작하지 않아도 최신 내용을 읽습니다. 새 스킬 디렉토리를 추가하면 자동으로 발견됩니다.

스킬 내 훅(Hook)

스킬의 라이프사이클에 스코프된 훅(Hook)을 정의할 수 있습니다. 스킬이 활성화된 동안만 실행되고, 완료 시 자동 정리됩니다:

---
name: secure-deploy
description: 보안 검사 후 배포
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

배포 전 보안 검사를 수행합니다...

플러그인과 스킬

플러그인(Plugin)은 스킬을 패키징하여 배포하는 시스템입니다.

플러그인 구조

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # 플러그인 매니페스트
├── skills/                  # 스킬 디렉토리
│   ├── review/
│   │   └── SKILL.md
│   └── deploy/
│       └── SKILL.md
└── .mcp.json                # 선택: MCP 서버 설정

플러그인 스킬 vs 독립 스킬

항목	독립 스킬	플러그인 스킬
경로	.claude/skills/	플러그인/skills/
호출	/skill-name	/plugin-name:skill-name
배포	Git 직접 공유	마켓플레이스
버전 관리	없음	시맨틱 버저닝
MCP 번들	별도 설정	.mcp.json 자동 로딩

플러그인과 스킬의 통합

플러그인은 스킬뿐 아니라 MCP 서버, CLAUDE.md 오버라이드 등을 함께 패키징할 수 있습니다:

aws-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── deploy-lambda/       # Lambda 배포 스킬
│   │   └── SKILL.md
│   ├── query-dynamodb/      # DynamoDB 쿼리 스킬
│   │   └── SKILL.md
│   └── monitor-cloudwatch/  # CloudWatch 모니터링 스킬
│       └── SKILL.md
├── .mcp.json                # AWS MCP 서버 자동 설정
└── CLAUDE.md                # AWS 관련 프로젝트 규칙

이 플러그인을 설치하면 /aws-plugin:deploy-lambda, /aws-plugin:query-dynamodb 등의 스킬과 AWS MCP 도구가 함께 활성화됩니다.

스킬 마켓플레이스

플러그인 스킬은 마켓플레이스를 통해 배포할 수 있습니다. 다른 개발자가 만든 스킬을 설치하여 사용하거나, 직접 만든 스킬을 공유할 수 있습니다. 마켓플레이스는 현재 확장 중이며, 향후 더 많은 플러그인이 등록될 예정입니다.

팀에서 스킬 공유하기

Git으로 프로젝트 스킬 공유

가장 간단한 방법은 .claude/skills/를 Git에 커밋하는 것입니다:

# 스킬 생성
mkdir -p .claude/skills/team-review
# SKILL.md 작성 후
git add .claude/skills/team-review/
git commit -m "feat: 팀 코드 리뷰 스킬 추가"
git push

팀원이 저장소를 pull하면 자동으로 스킬을 사용할 수 있습니다.

심링크로 개인 스킬 공유

여러 프로젝트에서 같은 스킬을 사용하려면 심링크를 활용합니다:

# 공통 스킬을 별도 저장소에 관리
git clone https://github.com/team/shared-skills.git ~/shared-skills

# 각 프로젝트에 심링크
ln -s ~/shared-skills/review .claude/skills/review
ln -s ~/shared-skills/deploy .claude/skills/deploy

Git 서브모듈로 관리

팀 공통 스킬을 서브모듈로 관리하면 버전 관리가 더 체계적입니다:

# 공유 스킬 저장소를 서브모듈로 추가
git submodule add https://github.com/team/shared-skills.git .claude/shared-skills

# 심링크로 연결
ln -s ../shared-skills/review .claude/skills/review

# 팀원이 저장소 클론 시
git clone --recurse-submodules https://github.com/team/project.git

# 또는 기존 클론에서
git submodule update --init

실전 스킬 예시 모음

코드 리뷰 스킬

---
name: review
description: 현재 브랜치의 변경 사항을 리뷰합니다
---

현재 브랜치의 diff를 리뷰하세요.

## 검토 항목
1. **보안**: SQL 인젝션(Injection), XSS, 인증 우회 등
2. **성능**: N+1 쿼리, 불필요한 렌더링, 메모리 누수
3. **코딩 컨벤션**: 프로젝트 규칙 준수 여부
4. **테스트**: 누락된 테스트 케이스

## 출력 형식
각 이슈에 대해:
- 파일명:라인번호
- 심각도 (Critical/Warning/Info)
- 설명과 개선 제안

세션 로거 스킬 (특수 변수 활용)

---
name: session-logger
description: 이 세션의 활동을 로그에 기록합니다
---

다음 내용을 logs/${CLAUDE_SESSION_ID}.log에 기록하세요:

$ARGUMENTS

읽기 전용 보안 감사 스킬

---
name: audit
description: 코드베이스의 보안 감사를 수행합니다
allowed-tools: Read Grep Glob
context: fork
agent: Explore
---

코드베이스의 보안 이슈를 감사하세요:
1. 하드코딩된 시크릿(Secret), API 키
2. SQL 인젝션 가능성
3. XSS 취약점
4. 인증/인가 우회 가능성
5. 안전하지 않은 의존성

PR 요약 스킬 (동적 컨텍스트 활용)

---
name: pr-summary
description: Pull Request를 요약합니다
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull Request 컨텍스트
- PR diff: !`gh pr diff`
- PR 코멘트: !`gh pr view --comments`
- 변경된 파일: !`gh pr diff --name-only`

## 작업
이 Pull Request를 다음 형식으로 요약하세요:
1. 변경 목적 (한 줄)
2. 주요 변경 사항 (불릿 포인트)
3. 리스크 분석 (잠재적 문제점)

파일 패턴 기반 자동 활성화 스킬

---
name: react-patterns
description: React 컴포넌트 작성 시 프로젝트 패턴을 적용합니다
paths: "src/components/**/*.tsx,src/pages/**/*.tsx"
user-invocable: false
---

React 컴포넌트 작성 시 다음 패턴을 따르세요:
- 함수형 컴포넌트만 사용
- Props 타입을 별도 interface로 정의
- useCallback/useMemo는 성능 프로파일링 후에만 적용
- 테스트는 Testing Library 사용

이 스킬은 src/components/ 또는 src/pages/ 내의 .tsx 파일을 작업할 때 Claude가 자동으로 로딩합니다. user-invocable: false이므로 / 메뉴에는 표시되지 않습니다.

실전 예시: 팀 전용 코드 리뷰 스킬 만들기

팀에서 공통으로 사용할 코드 리뷰 스킬을 처음부터 끝까지 만들어 봅시다.

1단계: 요구사항 정리

팀의 코드 리뷰 기준을 정리합니다:

• TypeScript 프로젝트, React + Express 스택
• 보안, 성능, 접근성을 중점적으로 검토
• 한국어 리뷰 코멘트
• GitHub PR에 직접 리뷰 코멘트 작성

2단계: 스킬 유형 결정

• 사용자가 직접 /review-pr로 호출 → disable-model-invocation: true
• 읽기 전용 + GitHub CLI만 사용 → context: fork, agent: Explore
• 인자로 PR 번호를 받음 → argument-hint 설정

3단계: 디렉토리 및 파일 생성

mkdir -p .claude/skills/review-pr

SKILL.md (.claude/skills/review-pr/SKILL.md):

---
name: review-pr
description: 현재 브랜치의 PR을 팀 컨벤션에 맞게 리뷰합니다. 보안, 성능, 접근성을 중점 검토합니다.
disable-model-invocation: true
context: fork
agent: Explore
allowed-tools: Bash(gh *) Read Grep Glob
argument-hint: "[PR번호 또는 빈칸=현재 브랜치]"
---

## PR 컨텍스트 수집
- PR diff: !`gh pr diff`
- PR 정보: !`gh pr view --json title,body,labels`
- 변경 파일: !`gh pr diff --name-only`

## 리뷰 체크리스트

### 필수 검토 (Critical)
1. **보안**: SQL 인젝션, XSS, CSRF, 하드코딩된 시크릿
2. **에러 처리**: try-catch 누락, 에러 무시, 사용자에게 내부 에러 노출
3. **타입 안전성**: `any` 사용, 타입 단언(assertion) 남용, 런타임 타입 불일치

### 권장 검토 (Warning)
4. **성능**: N+1 쿼리, 불필요한 re-render, 큰 번들 사이즈
5. **접근성**: alt 텍스트, aria 속성, 키보드 내비게이션
6. **테스트**: 새 기능에 테스트 포함 여부, 엣지 케이스 커버리지

### 참고 사항 (Info)
7. **네이밍**: 변수명, 함수명이 의도를 잘 설명하는지
8. **일관성**: 기존 코드 패턴과 일치 여부
9. **문서**: API 변경 시 문서 업데이트 여부

## 출력 형식
파일별로 그룹화하여 한국어로 보고:

### 📁 파일명
| 라인 | 심각도 | 설명 |
|------|--------|------|
| 42 | 🔴 Critical | 설명 |
| 78 | 🟡 Warning | 설명 |
| 120 | 🔵 Info | 설명 |

## 최종 판정
- 🔴 Critical이 1건 이상: **Request Changes** 권장
- 🟡 Warning만: **Approve with comments** 권장
- 🔵 Info만: **Approve** 권장

4단계: 테스트

# Claude Code 세션에서
> 사용 가능한 스킬이 뭐야?
# review-pr가 목록에 있는지 확인

# 직접 호출 테스트
/review-pr

# PR 번호 지정 테스트
/review-pr 42

5단계: Git에 커밋하여 팀 공유

git add .claude/skills/review-pr/SKILL.md
git commit -m "feat: 팀 PR 리뷰 스킬 추가"
git push

이제 팀원 모두가 /review-pr로 동일한 기준의 코드 리뷰를 받을 수 있습니다.

실전 예시: 프레임워크 마이그레이션 스킬

대규모 프레임워크 마이그레이션을 체계적으로 수행하는 복합 스킬 예시입니다.

스킬 구조

.claude/skills/migrate-framework/
├── SKILL.md                    # 메인 지침
├── patterns/
│   ├── react-to-vue.md         # React → Vue 패턴
│   ├── jest-to-vitest.md       # Jest → Vitest 패턴
│   └── express-to-fastify.md   # Express → Fastify 패턴
└── scripts/
    └── validate-migration.sh   # 마이그레이션 검증 스크립트

SKILL.md

---
name: migrate-framework
description: 프레임워크 마이그레이션을 체계적으로 수행합니다. 패턴 매핑, 호환성 검증, 점진적 전환을 지원합니다.
argument-hint: "[소스프레임워크] [타겟프레임워크] [대상경로]"
disable-model-invocation: true
context: fork
agent: general-purpose
allowed-tools: Bash Read Grep Glob Edit Write
effort: high
---

# 프레임워크 마이그레이션

## 입력
- 소스 프레임워크: $0
- 타겟 프레임워크: $1
- 대상 경로: $2 (미지정 시 src/)

## 마이그레이션 절차

### Phase 1: 분석
1. 대상 경로의 모든 파일 스캔
2. 소스 프레임워크 패턴 식별 (import, API 사용, 설정 파일)
3. 의존성 그래프 분석
4. 마이그레이션 난이도 평가 (파일별 복잡도)
5. 분석 결과를 migration-plan.md로 출력

### Phase 2: 환경 준비
1. 타겟 프레임워크 의존성 설치
2. 설정 파일 변환 (tsconfig, 빌드 설정 등)
3. 호환 레이어 설정 (필요 시)

### Phase 3: 파일별 변환
1. 복잡도가 낮은 파일부터 시작
2. 패턴 매핑 적용 (${CLAUDE_SKILL_DIR}/patterns/ 참고)
3. 각 파일 변환 후 타입 체크 실행
4. 변환이 어려운 파일은 TODO 주석으로 마킹

### Phase 4: 검증
1. 전체 빌드 실행
2. 기존 테스트 실행 (실패 항목 기록)
3. 타입 에러 수정
4. 검증 스크립트 실행: `bash ${CLAUDE_SKILL_DIR}/scripts/validate-migration.sh`

## 패턴 참조
마이그레이션 패턴은 [patterns/](patterns/) 디렉토리를 참고하세요.

사용법

# React → Vue 마이그레이션
/migrate-framework React Vue src/components/

# Jest → Vitest 전환
/migrate-framework Jest Vitest tests/

# Express → Fastify 마이그레이션
/migrate-framework Express Fastify src/api/

스킬 테스트 및 검증 전략

스킬이 작동하는지 확인하기

새로 만든 스킬을 테스트하는 3단계 방법입니다:

1단계: 스킬 목록에서 확인

# Claude Code 세션에서
> 사용 가능한 스킬이 뭐야?

스킬이 목록에 나타나면 Claude가 description을 정상적으로 읽은 것입니다. 목록에 없다면:

• 파일 경로 확인: ~/.claude/skills/이름/SKILL.md 또는 .claude/skills/이름/SKILL.md
• 파일명이 정확히 SKILL.md인지 확인 (대소문자 구분)
• YAML 프론트매터의 --- 마커가 올바른지 확인

2단계: 직접 호출 테스트

# 슬래시 명령으로 직접 호출
/my-skill 테스트 인자

# Claude 응답에서 스킬이 로드되었는지 확인

3단계: 자동 호출 테스트

# description에 매칭되는 자연어로 질문
> 이 코드가 어떻게 동작하는지 설명해줘
# → explain-code 스킬이 자동 로드되는지 확인

검증 체크리스트

스킬을 팀에 배포하기 전 확인할 항목입니다:

항목	확인 방법
SKILL.md 문법	YAML 프론트매터 --- 마커, 유효한 YAML
description 길이	description+when_to_use 합산 1,536자 이내, 핵심 용도가 앞에
인자 치환	$ARGUMENTS, $0 등이 올바르게 치환되는지
도구 제한	allowed-tools가 필요한 도구만 포함하는지
보조 파일 참조	${CLAUDE_SKILL_DIR}로 올바르게 참조하는지
동적 컨텍스트	!`명령어`가 정상 실행되는지
포크 동작	context: fork 시 명확한 작업 지시가 있는지
에지 케이스	인자 없이 호출, 잘못된 인자, 빈 결과 처리

스킬 디버깅 체크리스트

증상	확인사항	해결
스킬이 목록에 안 나옴	SKILL.md 경로/이름	정확한 디렉토리에 SKILL.md 배치
자동 호출이 안 됨	description 키워드	사용자가 쓸 법한 표현 포함
인자가 전달 안 됨	$ARGUMENTS 사용 여부	SKILL.md 내용에 $ARGUMENTS 추가
보조 파일을 못 찾음	파일 참조 방식	${CLAUDE_SKILL_DIR} 경로 사용
셸 명령어 실행 안 됨	정책 설정	disableSkillShellExecution 확인
포크된 스킬이 빈 결과	context: fork + 가이드라인만	명확한 작업 지시를 스킬에 포함

내장 스킬 선택 가이드

어떤 내장 스킬을 사용해야 할지 헷갈릴 때:

상황	추천 스킬	이유
대규모 코드 변경 (50+ 파일)	/batch	병렬 워크트리로 안전하게 분산 처리
Claude API/SDK 코드 작성	/claude-api	정확한 SDK 문법과 패턴 로딩
코드 변경 사항 리뷰	/code-review	diff 대상으로 버그·품질 문제 자동 검토
문제 원인을 모를 때	/debug	디버그 로그로 근본 원인 추적
배포/CI 상태 대기	/loop	주기적 폴링으로 상태 자동 확인
코드 변경이 실제로 작동하는지	/run 또는 /verify	앱 실행으로 실제 동작 검증
코드 품질 마무리	/simplify	3개 병렬 리뷰로 빠르게 개선
커스텀 반복 작업	직접 스킬 생성	/스킬이름으로 팀 공유

모범 사례

1. 설명은 1,536자 이내: description+when_to_use 합산 1,536자로 잘리므로 핵심 용도를 앞에 배치
2. 하나의 스킬 = 하나의 작업: 대규모 워크플로우는 여러 스킬로 분리
3. SKILL.md는 500줄 이내: 상세 내용은 보조 파일로 분리
4. 부작용 있는 작업: disable-model-invocation: true 설정 필수
5. $ARGUMENTS 포함: 인자를 받는 스킬은 $ARGUMENTS 변수 사용
6. argument-hint 추가: 사용자에게 기대하는 인자를 안내
7. 테스트: 자연어 질문과 /스킬이름 직접 호출 모두 테스트
8. 공유할 스킬: Git에 .claude/skills/를 커밋하여 팀원과 공유

문제 해결

문제	원인	해결
스킬이 자동 호출되지 않음	description이 사용자 질문과 매칭되지 않음	description에 사용자가 쓸 법한 키워드 포함
스킬이 너무 자주 호출됨	description이 너무 포괄적	더 구체적으로 작성하거나 disable-model-invocation: true
보조 파일을 찾지 못함	경로 문제	${CLAUDE_SKILL_DIR} 사용
설명이 잘림	description+when_to_use 합산 1,536자 초과	핵심 내용을 앞에 배치
스킬 메뉴에 표시 안 됨	user-invocable: false 설정	의도된 동작이거나, 설정 제거
"사용 가능한 스킬은?"에 없음	description 예산 초과	SLASH_COMMAND_TOOL_CHAR_BUDGET 환경 변수 증가
Windows에서 셸 스크립트 실행 안 됨	PowerShell 도구 미활성화	CLAUDE_CODE_USE_POWERSHELL_TOOL=1 환경변수 설정

연계 기능

스킬과 함께 활용하면 강력한 기능들

📜 규칙 (Rules / CLAUDE.md)

CLAUDE.md에 항상 적용할 규칙을, 스킬에 특정 상황의 워크플로우를 분리하면 컨텍스트를 효율적으로 관리할 수 있습니다.

규칙 가이드 →

⚙️ MCP 서버

MCP 도구 호출을 스킬의 프롬프트에 포함하면 외부 서비스(GitHub, DB 등)와 연동된 복합 워크플로우를 단일 명령으로 실행할 수 있습니다.

MCP 가이드 →

💻 CLI 레퍼런스

스킬을 헤드리스 모드(-p 플래그)와 결합하면 CI/CD 파이프라인에서 자동으로 워크플로우를 실행할 수 있습니다.

CLI 레퍼런스 →

장점, 단점과 한계점

장점

• 워크플로우 재사용: 자주 수행하는 작업(코드 리뷰, 커밋, 배포 등)을 SKILL.md로 정의하면 /명령어로 간편하게 반복 실행할 수 있습니다.
• 팀 공유 가능: .claude/skills/ 디렉토리를 Git에 커밋하면 팀 전체가 동일한 스킬을 사용할 수 있어 워크플로우를 표준화할 수 있습니다.
• 프론트매터로 세밀한 제어: allowed-tools, disallowed-tools, paths 등 YAML 프론트매터로 스킬의 권한, 적용 범위, 모델 등을 세밀하게 제어할 수 있습니다.
• 내장 스킬 즉시 사용: /batch, /claude-api, /code-review, /debug, /loop, /run, /simplify, /verify 등 기본 제공 스킬을 설치 없이 바로 사용할 수 있어 빠르게 생산성을 높일 수 있습니다.
• 컨텍스트 포크로 독립 실행: 스킬은 독립된 컨텍스트에서 실행되어 현재 대화의 컨텍스트를 오염시키지 않으며, 결과만 깔끔하게 반환됩니다.

단점과 한계점

• SKILL.md 작성 학습 필요: 프론트매터 문법, 변수(${ARGUMENTS}, ${CLAUDE_SKILL_DIR}), 보조 파일 구조 등을 이해해야 효과적인 스킬을 만들 수 있습니다.
• 프론트매터 오류 시 무시됨: YAML 프론트매터에 문법 오류가 있으면 에러 메시지 없이 기본값으로 동작하여, 의도한 제한이 적용되지 않을 수 있습니다.
• 복잡한 스킬 디버깅 어려움: 스킬이 예상대로 동작하지 않을 때 프론트매터 설정, 보조 파일 경로, 도구 권한 등 여러 요인을 확인해야 하며, 디버깅 도구가 제한적입니다.
• 스킬 간 의존성 관리 없음: 스킬 A가 스킬 B의 결과에 의존하는 경우를 자동으로 관리하는 메커니즘이 없어, 복잡한 파이프라인 구성이 어렵습니다.
• 스킬 버전 관리가 수동: 스킬 파일의 변경 이력은 Git에 의존하며, 스킬 자체의 버전 관리나 롤백 메커니즘이 별도로 제공되지 않습니다.

활용 팁

스킬 작성 시 먼저 내장 스킬(/batch, /debug, /simplify)의 구조를 참고하세요. 프론트매터 오류를 방지하려면 YAML 린터로 검증하거나, 간단한 스킬부터 시작하여 점진적으로 복잡도를 높이는 것이 좋습니다.

다음 단계

• MCP 서버 - 외부 도구 연동으로 스킬의 능력 확장
• 규칙 - CLAUDE.md로 프로젝트 전반 규칙 설정
• 스케줄 - 스킬을 주기적으로 자동 실행
• 기능 비교 - Remote Control, Dispatch, Channels 등 비교