Claude Code 커스텀 스킬 만들기: 완벽 튜토리얼

세 세션 연속으로 같은 보안 체크리스트를 Claude Code에 붙여넣었습니다. 그 체크리스트에는 우리 팀 고유의 취약점 패턴이 담겨 있었습니다 — 우리 API 설계에 특화된 IDOR 검사, 인증 흐름에 맞는 세션 처리 규칙, PII 필드에 대한 데이터 노출 규칙까지. 매번 Claude는 완벽하게 적용했습니다. 매번 제가 직접 붙여넣어야 했습니다.

같은 컨텍스트를 반복해서 설명하고 있다는 걸 깨닫는 순간이 바로 스킬을 만들어야 할 때입니다.

TL;DR

스킬은 모델이 호출하는 확장 기능입니다 — Claude가 컨텍스트를 기반으로 자동으로 발견하고 적용하며, 명시적으로 호출할 필요가 없습니다 ¹. 안정적인 스킬의 핵심은 description 필드입니다: Claude는 키워드 매칭이 아닌 LLM 추론을 사용하여 각 스킬의 활성화 시점을 결정합니다 ¹. 세션 간에 적용되는 도메인 전문 지식(보안 패턴, 코드 스타일, 비즈니스 규칙)을 위해 스킬을 만드세요. 일회성 작업에는 스킬을 만들지 마세요 — 대신 슬래시 명령어를 사용하세요.

사전 요구 사항: Claude Code 확장 시스템에 대한 이해가 필요합니다. 스킬, 명령어, 서브에이전트 간의 비교는 가이드의 스킬 섹션을 참고하세요.

스킬을 만들어야 할 때

반복되는 모든 프롬프트가 스킬이 되어야 하는 것은 아닙니다. 판단 기준은 다음과 같습니다:

스킬은 Claude가 항상 활용할 수 있는 지식입니다. 슬래시 명령어는 명시적으로 실행하는 액션입니다. 둘 사이에서 고민된다면 이렇게 자문해 보세요: “Claude가 자동으로 적용해야 하는가, 아니면 내가 실행 시점을 결정해야 하는가?”

흔한 실수: 일주일에 한 번 하는 작업을 스킬로 만드는 것입니다. 저는 git 관련 프롬프트에 활성화되는 git-rebase-helper 스킬을 만들었습니다 — rebase, merge, cherry-pick은 물론 git status에도 반응했습니다. 설명이 너무 광범위해서 필요하지 않은 80%의 세션에서도 컨텍스트를 오염시켰고, 2% 컨텍스트 예산 ¹을 놓고 다른 스킬과 경쟁했습니다. 해결책은 스킬을 삭제하고 실제로 필요할 때만 사용하는 슬래시 명령어 /rebase로 대체하는 것이었습니다. 스킬은 안정적인 도메인 전문 지식을 담아야지, 간헐적인 워크플로우를 담아서는 안 됩니다.

튜토리얼: 코드 리뷰 스킬 만들기

1단계: 디렉토리 생성

스킬은 가장 넓은 범위부터 좁은 범위까지 네 가지 위치에 배치할 수 있습니다 ¹:

이 튜토리얼에서는 개인 스킬을 만들겠습니다:

mkdir -p ~/.claude/skills/code-reviewer

2단계: 프론트매터와 함께 SKILL.md 작성

모든 스킬에는 두 부분으로 구성된 SKILL.md 파일이 필요합니다: Claude에게 언제 스킬을 사용할지 알려주는 YAML 프론트매터(--- 구분자 사이)와 스킬이 호출될 때 Claude가 따를 지침이 담긴 마크다운 콘텐츠입니다 ¹.

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

### Data Exposure
- PII masked in log output and error messages
- API responses don't leak internal IDs or stack traces
- Sensitive fields excluded from serialization defaults

allowed-tools: Read, Grep, Glob에 주목하세요 — 이 설정은 스킬을 읽기 전용 작업으로 제한합니다. 코드 리뷰어는 파일을 검사할 수 있지만 수정할 수는 없습니다. 도구 제한은 스킬이 의도치 않은 부작용을 일으키는 것을 방지합니다.

name, description, allowed-tools 외에도 유용한 프론트매터 필드가 있습니다 ¹:

공식 문서에서 언급하는 한 가지 주의사항: context: fork는 “격리의 이점이 있는 명시적 지침이 있는 스킬에만 의미가 있습니다” ¹. 메인 대화에 자연스럽게 녹아들어야 하는 지식 스킬이 아닌, 깨끗한 컨텍스트가 필요한 분석 스킬(코드 리뷰, 보안 감사)에 사용하세요.

3단계: 지원 리소스 추가

스킬은 같은 디렉토리 내의 추가 파일을 참조할 수 있습니다 ¹:

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

SKILL.md에서 상대 링크로 참조하세요:

See [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md) for OWASP Top 10 checks.
See [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md) for query optimization.

Claude는 스킬이 활성화될 때 표준 파일 읽기 도구를 사용하여 이 파일들을 필요에 따라 읽습니다 ¹. SKILL.md는 500줄 이내로 유지하고 상세한 참조 자료는 지원 파일로 분리하세요 ³ — 짧은 스킬 파일은 컨텍스트 주입 오버헤드를 줄이고 Claude가 현재 작업에 집중하도록 도와줍니다.

4단계: 활성화 테스트

스킬은 다음에 Claude Code 세션을 시작할 때 활성화됩니다. 테스트해 보세요:

# Ask Claude to review code — should trigger the skill automatically
claude "Review the authentication middleware in app/security/"

두 가지 방법 중 하나로 스킬이 로드되었는지 확인하세요 ¹:

# In an interactive session, ask Claude directly:
> What skills are available?

# Or check the context budget for excluded skills:
> /context

스킬이 활성화되지 않는다면, 문제는 거의 항상 description 필드에 있습니다. 5단계를 참고하세요.

5단계: 핵심 단계 — 설명 작성하기

description 필드는 스킬에서 가장 중요한 한 줄입니다. 내부 동작은 다음과 같습니다: 세션 시작 시 Claude Code는 모든 스킬의 name과 description을 추출하여 Claude의 컨텍스트에 주입합니다. 메시지를 보내면 Claude는 언어 모델 추론을 사용합니다 — 정규식도, 키워드 매칭도, 임베딩 유사도도 아닙니다 — 관련 스킬이 있는지 판단합니다. 공식 문서에는 이렇게 명시되어 있습니다: “Claude는 작업을 스킬 설명과 대조하여 관련성을 판단합니다. 설명이 모호하거나 겹치면 Claude가 잘못된 스킬을 로드하거나, 도움이 될 스킬을 놓칠 수 있습니다” ¹.

Claude Code 소스에 대한 독립적인 분석에서도 이 메커니즘이 확인됩니다: 스킬 설명은 시스템 프롬프트의 available_skills 섹션에 주입되며, 모델은 표준 언어 이해를 사용하여 호출 시 관련 스킬을 선택합니다 ⁴. LLM 기반 매칭은 설명 작성 방법에 중요한 시사점을 줍니다.

나쁜 설명:

description: Helps with code

Claude는 이 스킬을 언제 활성화해야 할지 알 수 없습니다. “코드를 도와줌”은 모든 것에 해당하면서 동시에 아무것에도 해당하지 않습니다 — 매칭이 LLM 추론이기 때문에 모호한 설명은 예측 불가능한 활성화를 야기합니다.

더 나은 설명:

description: Review code for bugs and issues

여전히 너무 모호합니다. 어떤 종류의 버그인가요? 어떤 종류의 이슈인가요? Claude가 내장 분석 대신 이 스킬을 언제 사용해야 하나요?

효과적인 설명:

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

효과적인 설명이 잘 작동하는 이유는 다음을 포함하기 때문입니다: - 무엇을 하는가: 구체적인 이슈 유형에 대한 코드 리뷰 - 언제 사용하는가: 변경 사항 검토, PR, 품질 분석 - 트리거 문구: review, audit, check — 사용자가 자연스럽게 입력하는 단어

알아두어야 할 제약: 모든 스킬 설명은 “컨텍스트 윈도우의 2%로 동적 조정되며, 폴백으로 16,000자”의 컨텍스트 예산을 공유합니다 ¹. 스킬이 많다면 각 설명을 간결하게 유지하세요 — 장황한 설명은 제한된 공간에서 다른 스킬과 경쟁합니다. SLASH_COMMAND_TOOL_CHAR_BUDGET 환경 변수로 예산을 재정의할 수 있지만 ², 더 나은 해결책은 더 짧고 정확한 설명을 작성하는 것입니다.

다양한 설명을 테스트하세요. 새 세션을 시작하고 Claude에게 코드 리뷰를 요청한 뒤 스킬이 활성화되는지 확인하세요. 활성화되지 않으면 트리거 문구를 더 추가하세요. 활성화되지 말아야 할 때 활성화되면 설명을 더 구체적으로 만드세요.

6단계: 사용 경험을 바탕으로 개선하기

일주일간 사용하면 다음을 발견하게 됩니다: - 스킬이 확인해야 하지만 하지 않는 패턴 — SKILL.md에 추가하세요 - 관련 없는 작업에서의 잘못된 활성화 — 설명을 더 정밀하게 조정하거나, disable-model-invocation: true를 추가하고 명시적인 /code-reviewer 호출을 요구하세요 - 부족한 컨텍스트 — 지원 리소스 파일을 추가하세요 - 너무 엄격하거나 너무 느슨한 도구 제한 — allowed-tools를 조정하세요

스킬은 살아있는 문서입니다. 첫 번째 버전이 최종 버전이 되는 일은 없습니다.

고급: 프롬프트 라이브러리로서의 스킬

단일 목적의 스킬을 넘어, 디렉토리 구조는 체계적인 프롬프트 라이브러리로 활용할 수 있습니다:

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

각 스킬은 팀 전문 지식의 다른 측면을 담고 있습니다. 이들은 함께 Claude가 컨텍스트에 따라 자동으로 활용하는 지식 베이스를 형성합니다. 주니어 개발자도 따로 요청하지 않아도 시니어 수준의 가이드를 받을 수 있습니다.

스킬 수에 대한 참고: 스킬이 많을수록 컨텍스트 예산을 놓고 더 많은 설명이 경쟁합니다 ¹. 스킬이 활성화되지 않는 것이 발견되면 /context를 실행하여 제외된 스킬이 있는지 확인하세요. 모호한 스킬 여러 개보다 잘 설명된 적은 수의 스킬을 우선시하세요.

팀과 스킬 공유하기

개인 스킬 (~/.claude/skills/)은 본인만 사용합니다. 개인 선호도, 실험적 패턴, 또는 본인의 워크플로우에 특화된 전문 지식에 활용하세요.

프로젝트 스킬 (레포지토리 루트의 .claude/skills/)은 git을 통해 공유됩니다 ¹:

# Create project-level skill
mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...

# Commit and push
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

팀원이 pull하면 자동으로 스킬을 받게 됩니다. 설치도, 설정도 필요 없습니다. Git 배포는 팀 전체에 전문 지식을 표준화하는 가장 효과적인 방법입니다.

공유 스킬 가이드라인: - 프로젝트 스킬은 도메인 전문 지식(비즈니스 규칙, 아키텍처 패턴)에 집중하세요 - 개인 스킬은 워크플로우 선호도(포매팅, 커밋 스타일)에 활용하세요 - 스킬이 존재하는 이유를 SKILL.md 상단에 주석으로 문서화하세요 - 다른 코드와 마찬가지로 PR에서 스킬 변경 사항을 리뷰하세요

핵심 정리

• 같은 컨텍스트를 반복 설명하고 있다면 스킬을 만드세요. 같은 체크리스트를 세 번 붙여넣었다면 스킬이 되어야 합니다.
• 설명 필드가 모든 것을 결정합니다. Claude는 LLM 추론을 사용하여 요청을 설명과 매칭합니다 ¹. 스킬 내용보다 설명에 더 많은 시간을 투자하세요.
• allowed-tools로 부작용을 제한하세요. 읽기 전용 스킬은 Read, Grep, Glob으로 제한해야 합니다.
• 프로젝트 스킬은 git으로 공유하세요. 설정 없이 팀 지식을 배포할 수 있습니다 ¹.
• 과도한 추상화를 피하세요. 모든 세부 패턴에 스킬을 만들면 유지보수 부담이 늘어나고 컨텍스트 예산 경쟁도 심해집니다. 안정적이고, 재사용 가능하며, 유지할 가치가 있는 전문 지식에 대해서만 스킬을 만드세요.

참고 자료