Claude Code 스킬: 자동 활성화되는 커스텀 확장 만들기

Claude Code용 커스텀 스킬은 어떻게 만듭니까? ~/.claude/skills/<name>/(개인용) 또는 .claude/skills/<name>/(프로젝트 단위)에 SKILL.md 파일을 만들고, name, description, allowed-tools 필드를 담은 YAML frontmatter 뒤에 markdown으로 전문 지식을 작성합니다. Claude는 description을 대상으로 LLM 추론을 수행해, 작업이 일치할 때 스킬을 자동으로 활성화합니다. git으로 공유한 프로젝트 스킬은 팀원 쪽에서 별도의 설정이 전혀 필요 없습니다. {.answer-block}

세 번의 세션 연속으로 같은 보안 체크리스트를 Claude Code에 붙여 넣었습니다. 그 체크리스트에는 우리 팀에 특화된 취약점 패턴이 담겨 있었습니다. 우리 API 설계에만 해당하는 IDOR 점검, 우리 인증 흐름에 맞춘 세션 처리 규칙, PII 필드의 데이터 노출 규칙 같은 것들입니다. 매번 Claude는 그 내용을 완벽하게 적용했습니다. 그리고 매번, 붙여 넣는 일 자체를 제가 기억하고 있어야 했습니다.

같은 컨텍스트를 또다시 설명하고 있는 자신을 발견하는 순간이 바로 스킬을 만들어야 할 때입니다.

TL;DR

스킬은 모델이 호출하는 확장입니다. 명시적으로 부르지 않아도 Claude가 컨텍스트에 따라 알아서 찾아내 적용합니다 ¹. 믿을 만한 스킬을 만드는 핵심은 description 필드입니다. Claude는 키워드 매칭이 아니라 LLM 추론으로 각 스킬을 언제 활성화할지 판단하기 때문입니다 ¹. 여러 세션에 걸쳐 통용되는 도메인 전문 지식(보안 패턴, 코드 스타일, 비즈니스 규칙)은 스킬로 만드십시오. 일회성 작업이라면 스킬 대신 슬래시 명령을 쓰는 편이 낫습니다.

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

언제 스킬을 만들어야 하는가

반복되는 프롬프트라고 해서 모두 스킬이 될 자격이 있는 것은 아닙니다. 판단 기준은 다음과 같습니다.

스킬은 Claude가 항상 갖추고 있는 지식을 위한 것이고, 슬래시 명령은 직접 명시적으로 발동하는 동작을 위한 것입니다. 둘 중 무엇을 만들지 고민된다면 이렇게 자문해 보십시오. “이것을 Claude가 알아서 적용해야 하는가, 아니면 언제 실행할지 내가 결정해야 하는가?”

흔한 실수: 일주일에 한 번 하는 일을 스킬로 만드는 것입니다. 저는 git-rebase-helper 스킬을 만들었는데, git과 관련된 프롬프트라면 무엇에든 활성화됐습니다. 리베이스, 머지, 체리픽은 물론 git status에도 반응했습니다. description이 지나치게 넓었던 탓에 필요하지도 않은 세션의 80%에서 컨텍스트를 오염시켰고, 2%의 컨텍스트 예산을 놓고 다른 스킬들과 경쟁했습니다 ¹. 해법은 그 스킬을 지우고 슬래시 명령으로 바꾸는 것이었습니다. 정말 필요할 때만 /rebase를 치면 됩니다. 스킬에는 가끔 쓰는 워크플로가 아니라 안정적인 도메인 전문 지식을 담아야 합니다.

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

1단계: 디렉터리 만들기

스킬이 놓일 수 있는 위치는 네 곳이며, 스코프가 넓은 순서대로 나열하면 다음과 같습니다 ¹.

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

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

2단계: frontmatter를 갖춘 SKILL.md 작성하기

모든 스킬에는 두 부분으로 이뤄진 SKILL.md 파일이 필요합니다. 하나는 스킬을 언제 쓸지 Claude에게 알려 주는 YAML frontmatter(--- 표시 사이)이고, 다른 하나는 스킬이 호출됐을 때 Claude가 따를 지시를 담은 markdown 본문입니다 ¹.

---
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 외에 알아 두면 유용한 frontmatter 필드는 다음과 같습니다 ¹.

공식 문서가 붙인 단서가 하나 있습니다. 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 작성하기

description 필드는 스킬을 통틀어 가장 중요한 한 줄입니다. 내부에서는 이런 일이 벌어집니다. 세션이 시작될 때 Claude Code는 모든 스킬의 name과 description을 추출해 Claude의 컨텍스트에 주입합니다. 그리고 메시지를 보내면 Claude는 정규식도, 키워드 매칭도, 임베딩 유사도도 아닌 언어 모델의 추론으로 관련된 스킬이 있는지 판단합니다. 공식 문서는 이렇게 설명합니다. “Claude는 어떤 스킬이 관련 있는지 판단하기 위해 사용자의 작업을 스킬 description과 대조합니다. description이 모호하거나 서로 겹치면 Claude가 엉뚱한 스킬을 로드하거나, 도움이 됐을 스킬을 놓칠 수 있습니다” ¹.

Claude Code 소스를 독립적으로 분석한 결과도 이 메커니즘을 뒷받침합니다. 스킬 description은 시스템 프롬프트의 available_skills 섹션에 주입되고, 모델은 호출 시점에 일반적인 언어 이해로 관련 스킬을 골라냅니다 ⁴. 매칭이 LLM 기반이라는 사실은 description을 어떻게 써야 하는지에 큰 영향을 미칩니다.

나쁜 description:

description: Helps with code

이래서는 Claude가 언제 활성화해야 할지 알 길이 없습니다. “Helps with code”는 모든 것에 해당하는 동시에 아무것에도 해당하지 않습니다. 게다가 매칭이 LLM 추론이기 때문에, 모호한 description은 예측할 수 없는 활성화로 이어집니다.

조금 나은 description:

description: Review code for bugs and issues

여전히 너무 막연합니다. 어떤 종류의 버그입니까? 어떤 종류의 문제입니까? Claude가 내장 분석 대신 이 스킬을 써야 할 때는 언제입니까?

효과적인 description:

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.

이 description이 통하는 이유는 다음을 담고 있기 때문입니다. - 무엇을 하는가: 구체적인 문제 유형을 대상으로 코드를 리뷰합니다 - 언제 쓰는가: 변경 사항 검토, PR, 품질 분석 - 트리거 문구: review, audit, check처럼 사용자가 자연스럽게 입력하는 단어

알아 둘 제약이 하나 있습니다. 모든 스킬 description은 하나의 컨텍스트 예산을 나눠 쓰며, 이 예산은 “컨텍스트 윈도우의 2%로 동적으로 조정되고, 폴백은 16,000자”입니다 ¹. 스킬이 많다면 description을 각각 간결하게 유지하십시오. 장황한 description은 한정된 공간을 놓고 다른 스킬과 경쟁합니다. SLASH_COMMAND_TOOL_CHAR_BUDGET 환경 변수로 예산을 재정의할 수도 있지만 ², 더 나은 해법은 더 짧고 더 정확한 description입니다.

여러 description을 시험해 보십시오. 새 세션을 시작해 Claude에게 코드 리뷰를 요청하고 스킬이 활성화되는지 확인합니다. 활성화되지 않으면 트리거 문구를 더 넣으십시오. 활성화되지 말아야 할 때 활성화된다면 description을 더 구체적으로 다듬으십시오.

6단계: 사용해 보며 개선하기

일주일쯤 써 보면 다음과 같은 것들이 눈에 들어옵니다. - 스킬이 점검해야 하는데 놓치고 있는 패턴 — SKILL.md에 추가하십시오 - 관계없는 작업에서 잘못 활성화되는 경우 — description을 더 조이거나, 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가 컨텍스트에 따라 알아서 끌어다 쓰는 지식 베이스가 됩니다. 주니어 개발자는 따로 청하지 않아도 시니어 수준의 조언을 받게 됩니다.

스킬 개수에 관한 참고: 스킬이 많아질수록 컨텍스트 예산을 놓고 경쟁하는 description도 많아집니다 ¹. 스킬이 활성화되지 않는 것 같다면 /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에서 리뷰하십시오

핵심 정리

• 컨텍스트를 또다시 설명하고 있는 자신을 발견하면 스킬을 만드십시오. 같은 체크리스트를 세 번 붙여 넣었다면 그것은 스킬이어야 합니다.
• description 필드가 모든 것을 좌우합니다. Claude는 LLM 추론으로 요청과 description을 대조합니다 ¹. 스킬 본문보다 description에 더 많은 시간을 쏟으십시오.
• allowed-tools로 부작용을 제한하십시오. 읽기 전용 스킬은 Read, Grep, Glob으로 제한해야 합니다.
• 프로젝트 스킬은 git으로 공유하십시오. 설정 없이 팀 지식을 배포할 수 있습니다 ¹.
• 과도하게 추상화하지 마십시오. 사소한 패턴마다 스킬을 만들면 유지보수 부담이 생기고 컨텍스트 예산까지 잡아먹습니다. 안정적이고, 재사용할 수 있으며, 유지할 가치가 충분한 전문성에만 스킬을 만드십시오.

자주 묻는 질문

Claude Code 스킬이란 무엇입니까?

스킬은 markdown 파일로 저장되는, 모델이 호출하는 확장입니다. Claude가 컨텍스트에 따라 스스로 찾아내 적용합니다. 직접 발동해야 하는 슬래시 명령과 달리, 스킬은 Claude의 LLM 추론이 현재 작업과 스킬의 description이 맞아떨어진다고 판단할 때 활성화됩니다. 스킬에는 보안 패턴, 코드 스타일 규칙, 비즈니스 로직 같은 도메인 전문 지식이 담기며, 매번 컨텍스트를 다시 설명하지 않아도 여러 세션에 걸쳐 유지됩니다.

Claude Code용 커스텀 스킬은 어떻게 만듭니까?

개인 스킬은 ~/.claude/skills/<name>/ 아래에, 프로젝트 단위 스킬은 .claude/skills/<name>/ 아래에 디렉터리를 만듭니다. 그 안에 SKILL.md 파일을 만들고, YAML frontmatter(name, description, 그리고 선택적으로 allowed-tools를 포함)에 이어 Claude가 적용할 전문 지식을 markdown으로 작성합니다. 여기서 결정적인 것은 description 필드입니다. Claude가 이 필드를 대상으로 LLM 추론을 수행해 스킬을 언제 활성화할지 판단하기 때문입니다. 단계별 설명은 위의 전체 튜토리얼을 참고하십시오.

Claude Code 스킬과 슬래시 명령의 차이는 무엇입니까?

스킬은 컨텍스트에 따라 자동으로 활성화됩니다. 스킬의 description을 대상으로 한 LLM 추론으로 Claude가 관련 여부를 판단합니다. 반면 슬래시 명령은 /command-name을 입력해 사용자가 명시적으로 발동하는 동작입니다. Claude가 그 지식을 항상 갖추고 있어야 한다면(도메인 전문 지식, 품질 기준) 스킬을 만드십시오. 언제 실행할지 직접 정하고 싶다면(배포 스크립트, 일회성 워크플로) 슬래시 명령을 만드십시오.

Claude Code 스킬이 다른 도구를 호출할 수 있습니까?

가능합니다. 다만 어떤 도구를 쓸지는 allowed-tools frontmatter 필드로 직접 통제합니다. 코드 리뷰어처럼 읽기 전용인 스킬은 의도치 않은 부작용을 막기 위해 Read, Grep, Glob으로 제한하는 것이 좋습니다. allowed-tools를 생략하면 스킬은 Claude가 접근할 수 있는 모든 도구를 쓸 수 있습니다. 또한 스킬은 frontmatter에 자체 훅을 정의할 수 있으며, 이 훅은 해당 스킬이 실행되는 동안에만 작동합니다.

제 Claude Code 스킬이 활성화되지 않는 이유는 무엇입니까?

가장 흔한 원인은 모호하거나 지나치게 넓은 description 필드입니다. Claude는 키워드 매칭이 아니라 LLM 추론으로 스킬이 현재 작업과 관련 있는지 판단합니다. description이 “helps with code”라고만 되어 있으면, 다른 코딩 작업과 구분해 언제 활성화해야 할지 Claude가 알 수 없습니다. description을 구체적으로 쓰십시오. 정확한 문제 유형, 발동 상황, 그리고 사용자가 자연스럽게 입력하는 행위 동사를 적으십시오. 세션에서 /context를 확인해, 2% 컨텍스트 예산 한도 때문에 스킬이 제외되고 있지는 않은지도 살펴보십시오. 많은 스킬이 공간을 놓고 다투면 일부는 탈락합니다.

Claude Code 스킬은 어디에 저장되고 어떻게 공유됩니까?

스킬은 스코프가 넓어지는 순서로 네 곳에 놓입니다. 개인(~/.claude/skills/<name>/SKILL.md), 프로젝트(.claude/skills/<name>/SKILL.md), 플러그인, 그리고 Enterprise(관리형 설정)입니다. 개인 스킬은 자신의 모든 프로젝트에 적용됩니다. 프로젝트 스킬은 git으로 공유되며, 팀원이 pull하면 설정 없이 자동으로 따라옵니다. 모든 스킬의 description은 컨텍스트 윈도우의 2%라는 예산을 함께 나눠 쓰므로, 스킬이 많다면 description을 간결하게 유지하십시오.

참고 문헌