Claude Code 스킬: SKILL.md 작동 방식과 로드 위치

Claude Code 스킬은 내부에 SKILL.md 파일이 있는 폴더입니다. 파일에는 스킬을 적용할 때를 설명하는 YAML 프런트매터와 지침을 담은 Markdown 본문이 있습니다. Claude Code는 모든 스킬의 설명을 계속 볼 수 있게 유지하고, 스킬을 사용할 때만 전체 본문을 로드하며, /skill-name을 입력해 직접 실행할 수도 있습니다.^[1] 이제 사용자 정의 슬래시 명령도 같은 방식으로 작동합니다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 모두 /deploy를 만들며, 기존 명령 파일도 계속 작동합니다.^[1]

스킬을 언제 만들지에 대한 Anthropic의 조언은 실용적입니다. 같은 체크리스트나 절차를 채팅에 계속 붙여 넣거나, CLAUDE.md의 한 부분이 사실 설명이 아니라 절차가 됐다면 스킬을 만드세요. CLAUDE.md는 세션마다 로드되지만, 스킬 본문은 실행되기 전까지 비용이 거의 들지 않습니다.^[1]

최소 구성의 Claude Code 스킬

스킬에는 디렉터리와 파일 하나가 필요합니다. 다음 예시는 최근 커밋에서 릴리스 노트 초안을 만듭니다. ~/.claude/skills/release-notes/SKILL.md로 저장하세요.

---
description: Drafts release notes from recent git commits. Use when the user asks for release notes, a changelog entry, or what shipped.
disable-model-invocation: true
---

## Recent commits

!`git log --oneline -30`

## Instructions

Group the commits above into Added, Changed and Fixed. Write one line per change in plain language. Skip merge commits.

디렉터리 이름이 명령이 되므로 /release-notes로 실행합니다. !`...` 줄은 동적 컨텍스트 주입입니다. Claude Code가 명령을 실행하고 그 출력을 Claude가 읽기 전에 스킬에 넣으므로, 실제 이력을 바탕으로 노트를 만듭니다.^[1] disable-model-invocation: true는 Claude가 스스로 스킬을 시작하지 못하게 하므로, 직접 실행하고 싶은 작업에 적합합니다.

Claude Code 스킬이 로드되는 위치

어떤 폴더를 선택하느냐에 따라 스킬 사용자가 결정됩니다.^[1]

위치	경로	사용자
개인	`~/.claude/skills/<name>/SKILL.md`	이 컴퓨터의 모든 프로젝트에서 본인
프로젝트	`.claude/skills/<name>/SKILL.md`	커밋된 후 저장소에서 작업하는 모든 사람
하위 폴더	`<subdir>/.claude/skills/<name>/SKILL.md`	해당 폴더 또는 그 아래에서 시작한 세션
플러그인	`<plugin>/skills/<name>/SKILL.md`	플러그인을 활성화한 사람, `/plugin-name:skill-name`으로 사용
엔터프라이즈	관리형 설정 디렉터리	조직이 배포한 환경의 모든 사용자
claude.ai 계정	계정에서 활성화한 스킬	해당 계정으로 로그인한 세션

예약된 이름이 두 가지 있습니다. Claude Code는 claude.ai에서 다운로드한 스킬에 ~/.claude/skills/synced/를 사용하며, 이 폴더 이름으로 직접 만든 스킬은 건너뜁니다. 플러그인 밖에서는 폴더 이름이 anthropic-skills이거나 anthropic-skills:로 시작하면 로드되지 않습니다.^[1]

프런트매터로 제어하는 항목

모든 필드는 선택 사항이며 Anthropic은 description만 권장합니다. Claude Code는 필드 이름에 오타가 있어도 오류를 알리지 않고 무시하므로 이름을 정확히 복사하세요.^[1] 동작을 크게 바꾸는 필드는 다음과 같습니다.

**description**은 Claude가 스킬 사용 여부를 결정하는 근거입니다. 주된 용도를 먼저 적으세요. 스킬 목록에서는 when_to_use와 합쳐 1,536자에서 잘립니다.
**disable-model-invocation: true**는 수동 실행 전용으로 만듭니다. 설명도 컨텍스트에서 빠지므로 직접 입력하기 전에는 비용이 들지 않습니다.
**user-invocable: false**는 반대입니다. Claude만 로드할 수 있고 / 메뉴에서는 사라집니다. Anthropic은 레거시 시스템 작동 방식 같은 배경지식에 이를 권장합니다.
**allowed-tools**는 스킬을 실행하는 턴에 도구 사용을 사전 승인합니다. 다음 메시지를 보내면 이 권한은 끝납니다.
**paths**는 일치하는 파일로 자동 로드를 제한하고, **context: fork**는 하위 에이전트에서 스킬을 실행합니다.

model과 effort는 설정에 변경을 저장하지 않고 현재 턴의 나머지 부분에서 모델과 추론 수준을 바꿉니다.^[1]

스킬이 사용하는 컨텍스트 양

Anthropic은 세 단계를 설명합니다. 시작 시 각 스킬의 이름과 설명이 로드되며 스킬당 약 100토큰입니다. SKILL.md 본문은 스킬이 실행될 때 로드되며, Anthropic의 표에서 이 단계는 5,000토큰 미만입니다. 함께 제공되는 파일은 Claude가 읽기 전까지 비용이 없고, 스크립트 코드는 컨텍스트에 들어가지 않으며 출력만 들어갑니다.^[2]

스킬이 실행되면 그 내용은 대화에 하나의 메시지로 남고, Claude Code는 이후 턴에서 파일을 다시 읽지 않습니다. 자동 압축 후에는 각 스킬의 가장 최근 실행을 다시 붙이며, 최신 것부터 공유 예산 25,000토큰 안에서 각 스킬의 처음 5,000토큰을 유지합니다. 긴 세션 하나에서 많은 스킬을 썼다면 가장 오래된 것은 빠질 수 있습니다.^[1] 작업 전체에서 유지해야 하는 규칙은 파일 상단 가까이에 상시 지침으로 적으세요.

Claude Code 밖의 Claude 스킬

같은 형식이 다른 Claude 환경에서도 실행되지만, 환경별 규칙은 다릅니다.^[2]

claude.ai에는 설정 없이 활성화되는 Anthropic의 PowerPoint, Excel, Word, PDF용 기본 스킬이 있습니다. 사용자 정의 스킬은 코드 실행을 활성화한 Pro, Max, Ultra, Team, Enterprise 요금제에서 Settings > Features를 통해 zip 파일로 업로드합니다. 각 업로드는 사용자 한 명에게만 공개됩니다.
Claude API는 코드 실행 도구와 함께 container 매개변수에 skill_id를 받습니다. 기본 ID는 pptx, xlsx, docx, pdf이며, 사용자 정의 스킬은 /v1/skills 엔드포인트를 통해 관리하고 워크스페이스 전체에서 공유합니다.
Claude Code는 사용자 정의 스킬을 지원하지만 기본 문서 스킬은 지원하지 않습니다.

동기화에 관한 Anthropic 문서는 서로 다릅니다. Agent Skills 개요에는 사용자 정의 스킬이 환경 간 동기화되지 않으며, Claude Code 스킬은 claude.ai 및 API와 별개라고 나옵니다.^[2] 더 새로운 Claude Code 페이지는 claude.ai 계정에서 활성화한 스킬을 그 계정으로 로그인한 터미널 세션의 로드 위치로 나열하며, ~/.claude/skills/synced/에 다운로드한다고 설명합니다.^[1] 이 동기화에 의존한다면 워크플로를 구성하기 전에 / 메뉴에 스킬이 나타나는지 확인하세요.

Claude Code 스킬을 claude.ai나 Skills API로 옮길 때는 주의가 필요합니다. 이 경로는 Agent Skills 개방형 표준의 프런트매터 필드 여섯 개만 받습니다. name, description, license, compatibility, metadata, allowed-tools입니다. disable-model-invocation이나 argument-hint 같은 다른 필드는 무시되지 않고 “Unexpected key(s)” 오류로 업로드를 실패시키며, !`command` 주입 같은 Claude Code 전용 기능도 실행되지 않습니다.^[1]^[3] 위 릴리스 노트 예시에서는 둘 다 제거해야 합니다.

다른 사람이 만든 스킬 설치하기

스킬은 Claude에게 명령 실행과 도구 호출을 지시할 수 있으므로, Anthropic은 신뢰하는 출처의 스킬만 쓰고 소프트웨어를 설치하듯 취급하라고 조언합니다. SKILL.md만 아니라 폴더의 모든 파일을 읽으세요. 스크립트, 이미지, 참고 파일 모두 지침을 담을 수 있습니다. 외부 URL에서 콘텐츠를 가져오는 스킬은 검토한 뒤 페이지가 바뀔 수 있어 추가 위험이 있습니다.^[2]

FAQ

Claude Code 스킬은 슬래시 명령과 같은가요?

둘은 통합됐습니다. .claude/commands/의 명령 파일과 같은 이름의 스킬 폴더는 동일한 /name 명령을 만듭니다. 스킬에는 보조 파일, 자동 로드, 호출 제어가 추가됩니다.^[1]

Claude Code에서 PowerPoint와 Excel 스킬을 사용할 수 있나요?

아니요. Anthropic의 기본 문서 스킬은 claude.ai와 API에서 실행되며 Claude Code에서는 사용할 수 없습니다. Claude Code는 /code-review, /debug, /claude-api 같은 자체 내장 스킬을 제공합니다.^[1]^[2]

Claude가 내 스킬을 무시하는 이유는 무엇인가요?

먼저 설명을 확인하세요. Claude가 결정 전에 보는 것은 when_to_use와 이 설명뿐입니다. 그런 다음 여는 ---가 파일의 첫 줄인지 확인하세요. 그렇지 않으면 Claude Code는 프런트매터를 일반 텍스트로 취급하고, YAML 오류가 있으면 필드가 하나도 설정되지 않은 채 스킬이 로드됩니다.^[1]

자체 모델 접근 경로로 Claude Code 스킬 실행하기

개인 및 프로젝트 스킬은 Claude Code 클라이언트가 읽는 컴퓨터의 파일입니다. Claude 구독 대신 게이트웨이에 Claude Code를 연결한다면 reAPI의 Claude Code 가이드에서 기본 URL, 키 유형, 지원하는 Claude 모델 ID를 확인할 수 있고, Claude Sonnet 5.5 페이지에는 현재 요금이 나옵니다. claude.ai에서 동기화하는 스킬은 해당 계정 로그인이 필요하므로, 어디서나 필요한 Claude Code 스킬은 개인 또는 프로젝트 폴더에 보관하세요.

참고 자료

Anthropic. Extend Claude with skills (Claude Code documentation). 2026년 11월 4일 확인, 출처: code.claude.com/docs/en/skills
Anthropic. Agent Skills overview. 2026년 11월 4일 확인, 출처: platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
Agent Skills. Agent Skills open standard. 2026년 11월 4일 확인, 출처: agentskills.io