Claude Code 스킬 완벽 가이드 (2026)

code.claude.com/docs/en/skills의 공식 문서로 검증했어요(2026-08-09 접속).

Claude Code 스킬이란?

Claude Code를 한동안 써 봤다면, 반복 작업을 원하는 방식으로 그냥 기억해 줬으면 하고 바란 적이 있을 거예요—"코드를 리뷰할 때는 이 체크리스트를 따라줘"라거나 "이미지를 최적화할 때는 정확히 이 명령을 실행해줘"처럼요. 스킬이 바로 그 문제를 해결해요.

Claude Code 스킬은 재사용할 수 있고 모델이 호출할 수 있는 지시문 묶음이에요—각각이 SKILL.md 파일을 담은 폴더로, 언제 사용하고 어떻게 작업을 처리하는지 Claude에게 알려줘요. 스킬을 벽에 붙여 둔 코팅된 "이 작업은 이렇게 한다" 카드라고 생각해 보세요. Claude는 먼저 제목을 읽어 어떤 카드가 있는지 파악하고, 작업이 필요할 때에만 한 장을 꺼내 세부 내용을 읽어요.

모든 스킬에는 두 가지 핵심 요소가 있어요.

• description 프런트매터 — 스킬이 무엇을 하고 언제 발동하는지 알려주는 짧은 한 줄이에요. Claude가 항상 "보고 있는" 부분이죠.
• 마크다운 본문 — 자세한 단계, 관례, 예시예요. 스킬이 실제로 호출될 때에만 로드돼요.

스킬은 Claude만의 발명품이 아니에요. 개방형 Agent Skills 표준(agentskills.io)을 따르는데, 이는 같은 SKILL.md 형식이 여러 Claude 환경에서, 그리고 원칙적으로 이 표준을 채택한 다른 도구에서도 작동한다는 뜻이에요. 스킬은 한 번 작성하면 프로젝트를 넘나들며 재사용하고, 팀원과 공유하고, 미리 만들어진 묶음을 통째로 설치할 수 있어요.

먼저 짚어 둘 만한 2026년의 변화가 하나 있어요. 커스텀 슬래시 명령이 스킬에 통합됐어요. 예전의 .claude/commands/*.md 파일도 여전히 작동하지만, 이제 SKILL.md 하나가 두 역할을 다 해요—Claude가 설명을 보고 자동으로 호출할 수 있고, 대응하는 /skill-name 명령도 만들어져요. 2025년 초에 쓰인 튜토리얼에서 "명령"과 "스킬"을 별개의 두 시스템으로 다룬다면, 그건 통합 이전의 모델이에요.

Claude Code 스킬의 작동 방식(점진적 공개)

이 부분이야말로 스킬이 단순히 "프롬프트를 깔끔하게 보관하는 방법"이 아니라 왜 그만한 가치가 있는지 이해하는 데 가장 중요해요. 이 메커니즘을 점진적 공개(progressive disclosure)라고 불러요.

Claude Code는 시작할 때 모든 스킬의 전체 내용을 컨텍스트 윈도에 로드하지 않아요. 대신 각 스킬의 짧은 description만 로드하죠—"code-review 스킬, deploy 스킬, image-optimizer 스킬이 있구나" 하고 알 수 있을 정도로요. 작업이 그중 한 설명과 맞으면, Claude는 그 스킬 하나의 본문 전체를 읽고 따라 해요. 보조 파일(템플릿, 참고 문서, 스크립트)은 스킬이 명시적으로 참조할 때에만 로드돼요.

토큰 비용에 대한 직관을 알려드릴게요. 모든 관례를 CLAUDE.md에 몰아넣으면, 좀처럼 필요 없는 90%의 지침까지 포함해 그 전부가 매 턴 컨텍스트에 자리 잡고, 매 턴 그만큼 토큰 비용을 내게 돼요. 스킬을 쓰면 "상시 비용"은 스킬마다 몇 줄짜리 description뿐이고, 무거운 본문은 필요한 바로 그 순간에만 컨텍스트에 들어와요. 그렇게 스킬은 컨텍스트 윈도를 부풀리지 않으면서 큰 지시문 라이브러리를 유지하게 해줘요.

스킬은 다음 두 가지 방식 중 하나로 활성화돼요.

• 자동으로 — Claude가 요청을 모든 스킬의 description과 대조해 어떤 걸 호출할지 결정해요. 여러분은 작업을 설명하기만 하면 되고, 스킬 쪽은 명확한 설명만 있으면 돼요.
• /skill-name으로 직접 — 특정 스킬을 곧바로 호출해요. 예를 들어 /code-review처럼요. Claude를 정해진 워크플로로 밀어붙이고 싶을 때 편리해요.

Claude는 자동 선택에 이 description을 의존하기 때문에, 그 한 줄의 품질이 스킬이 적절한 순간에 발동할지를 좌우해요. "이미지에 도움이 됨" 같은 모호한 설명은 Claude를 망설이게 하지만, "PNG를 WebP로 변환하고 200KB 미만으로 압축할 때 사용" 같은 트리거가 풍부한 설명은 거의 매번 발동해요.

스킬 vs 명령, 서브에이전트, 훅, MCP

바로 여기서 초보자들이 헷갈려요—Claude Code에는 비슷하게 들리는 개념이 한 무리 있거든요. 자리를 잡을 수 있도록, 각각 한두 줄로 빠르게 비교해 볼게요.

핵심 차이는 이래요. 스킬은 Claude가 일하는 방식을 빚는 마크다운과 스크립트이고, MCP는 외부 시스템에서 새로운 능력을 Claude에 주는 도구 프로토콜이에요. 둘은 서로 보완해요—스킬은 MCP로 연결된 도구를 잘 쓰는 법을 설명할 수 있어요. 각 개념이 어디서 시작하고 어디서 끝나는지 전체를 알고 싶다면, 전용 심층 글을 하나 써 뒀어요: 스킬 vs 서브에이전트 vs 훅 vs MCP.

스킬이 사는 곳(개인, 프로젝트, 플러그인, 엔터프라이즈)

스킬 폴더를 어디에 두느냐가 그 적용 범위를 정해요. Claude Code는 우선순위가 높은 순서로 여러 위치에서 스킬을 찾아요.

모든 작업에 걸친 자기 습관에는 개인 스킬을, 특정 저장소에 속하는 관례에는 프로젝트 스킬을 쓰세요(.claude/skills/를 커밋하면 팀의 모두가 갖게 돼요). 좋은 세부 하나: Claude Code는 스킬 파일 변경을 실시간으로 감지해요—SKILL.md를 편집하면 재시작 없이 새 버전을 반영해서, 스킬을 다듬는 작업이 빨라져요.

SKILL.md 파일의 구조

파일 수준에서 보면 스킬은 놀랄 만큼 단순해요. 스킬의 슬러그를 이름으로 한 폴더에 필수 파일 SKILL.md 하나가 들어 있을 뿐이에요. 실행할 때 스킬이 참조할 선택적 보조 파일—템플릿, 스크립트, 예시—을 추가할 수 있어요.

~/.claude/skills/optimize-web-image/
├── SKILL.md (required)
├── template.md (optional - output template)
├── examples/ (optional - reference examples)
└── scripts/convert.sh (optional - helper script)

SKILL.md 자체는 YAML 프런트매터와 그 뒤를 잇는 마크다운 본문이에요. 실제로 실행되는 진짜 스킬을 보여드릴게요.

---
name: optimize-web-image
description: Convert a PNG to WebP and compress under 200KB. Use when the user needs to optimize an image for the web.
allowed-tools: Bash, Read
---

# Optimize web image

When asked to optimize an image:

1. Run `cwebp -q 80 input.png -o output.webp`.
2. Check the output file size. If it is still over 200KB,
 drop quality to `-q 70` and run again.
3. Report the new file path and its final size.

이게 전부예요. 프런트매터는 스킬을 언제 쓸지 Claude에게 알려주고, 본문은 어떻게 쓸지 알려줘요. 가장 자주 손이 가는 프런트매터 필드를 정리했어요(전체 목록은 공식 문서를 보세요).

실용적인 규칙 하나: SKILL.md는 대략 500줄 미만으로 유지하세요. 스킬은 한 번 호출되면 본문이 컨텍스트에 들어와 세션 내내 남아요. 그래서 부풀어 오른 본문은 토큰을 낭비해요—긴 참고 자료는 보조 파일로 밀어내고 필요할 때만 가리키세요.

5분 만에 첫 스킬 만들기(단계별)

작지만 정말 쓸모 있는 스킬을 만들어 볼게요: summarize-changes는 최근 git diff를 쉬운 말 요약으로 바꿔줘요. 세 단계예요.

1. 폴더를 만들어요(개인 스코프라 모든 프로젝트에서 작동해요):

   mkdir -p ~/.claude/skills/summarize-changes

2. SKILL.md를 작성해요 — 위치는 ~/.claude/skills/summarize-changes/SKILL.md예요:

   ---
   name: summarize-changes
   description: Summarize the current git changes in plain English, grouped by area. Use when the user asks what changed or wants a PR summary.
   allowed-tools: Bash, Read
   ---
   
   # Summarize changes
   
   1. Run `git diff --stat` and `git diff` for uncommitted changes.
   2. Group edits by area (feature, fix, docs, tests, chore).
   3. Write 3-6 bullet points in plain English - what changed and why
    it matters - short enough to paste into a pull request.

3. 두 가지 방법으로 테스트해요. 커밋하지 않은 편집이 있는 저장소에서 Claude Code를 열고, 명령을 직접 입력하거나—/summarize-changes—아니면 그냥 자연스럽게 "내가 뭘 바꿨는지 요약해줘"라고 물어보세요. description이 명확하면, 스킬 이름을 대지 않아도 자연스러운 요청만으로 자동 발동해요.

Claude Code는 스킬 파일을 실시간으로 감지하니 재시작할 필요가 없어요—파일을 저장하는 순간 스킬을 쓸 수 있어요.

스킬 실전(진짜 예시와 솔직한 소감)

위의 summarize-changes 스킬은 제가 실제로 개인 폴더에 두고 쓰는 것으로, 스킬이 제 몫을 하는 때—그리고 그렇지 않은 때—를 잘 보여줘요.

이전에는: 세션이 끝날 무렵 Claude에게 "PR 설명을 써줘"라고 하면, 커밋 메시지에 기댄 뻔한 글이 나오고 왜가 빠져 있었어요. 이후에는: 이 스킬이 있으면 지시문이 실제 diff를 읽고 영역별로 묶도록 강제해서, 요약이 제가 커밋에 어떻게 라벨을 달았는지가 아니라 정말로 바뀐 내용을 반영해요. 단계가 지난번에 어떻게 표현했는지에 대한 제 기억이 아니라 스킬 안에 들어 있어서, 출력이 매번 일관돼요.

처음에 잘 안 됐던 점: 제 첫 description은 그냥 "summarize git changes"였는데, Claude가 이를 무시하고 대신 커밋 이력에서 답하곤 했어요. 구체적인 트리거—"사용자가 무엇이 바뀌었는지 묻거나 PR 요약을 원할 때 사용"—를 더하니 자동 호출이 고쳐졌어요. 이게 솔직한 교훈이에요: 스킬은 그 설명만큼만 좋고, 그 한 줄은 몇 번은 다듬어야 한다고 여기세요.

또 하나 솔직한 유의점: 이건 작고 작업 형태를 띤 일이라, 딱 스킬에 맞아요. 만약 저장소의 코딩 스타일 전체를 스킬에 담으려 했다면, 그건 잘못된 자리예요—모든 턴에 적용되는 스타일은 호출할 때만 로드되는 스킬이 아니라 CLAUDE.md에 속해요.

고급: 동적 컨텍스트와 스킬을 서브에이전트로 실행하기

기본에 익숙해지면 스킬을 더 강력하게 해주는 두 가지 기능이 있어요.

동적 컨텍스트 주입. SKILL.md 안에 ` !`command` ` 구문으로 셸 명령을 넣으면, Claude Code가 그걸 실행해 Claude가 본문을 읽기 전에 출력을 주입해요. 즉 스킬이 정적 텍스트가 아니라 실시간 상태에 대고 동작할 수 있다는 뜻이에요.

---
name: summarize-changes
description: Summarize the current git diff in plain English.
---

# Summarize changes

Here is the current diff:

!`git diff HEAD`

Summarize the changes above, grouped by area, in 3-6 bullets.

` !`git diff HEAD` ` 줄은 스킬이 로드될 때 실행되므로, Claude는 실제 diff가 이미 인라인으로 들어간 상태로 보게 돼요—별도의 툴 호출이 필요 없어요.

스킬을 서브에이전트로 실행하기. 프런트매터에 context: fork를 설정하면, 스킬은 자체 컨텍스트 윈도를 가진 격리된 서브에이전트에서 실행되어 결과만 메인 세션에 돌려줘요.

---
name: summarize-changes
description: Summarize the current git diff in an isolated subagent.
context: fork
---

이건 토큰을 많이 쓰는 작업에 이상적이에요—거대한 diff 리뷰나 많은 파일 훑기처럼요—덩치 큰 중간 작업이 포크된 컨텍스트에 머물러 메인 대화를 어지럽히지 않거든요. 포크된 스킬이 온전한 서브에이전트와 어떻게 연관되는지 이해하고 싶다면, 그 경계는 스킬 vs 서브에이전트 vs 훅 vs MCP 비교에서 다뤄요.

전부 만들지 마세요—미리 만들어진 스킬 팩

정확한 워크플로를 손수 맞추고 싶다면 스킬을 직접 쓰는 게 아주 좋아요. 하지만 흔한 작업—프런트엔드, 백엔드, 데이터베이스, DevOps, 코드 리뷰—을 위한 탄탄한 라이브러리가 필요할 뿐이라면, 모든 SKILL.md를 직접 쓸 필요는 없어요. 엄선된 스킬 팩을 설치하면 돼요.

인기 있는 선택지 하나는 AgentKit, Claude Code를 위한 미리 만들어진 스킬 팩이에요(ak CLI로 설치). 108개가 넘는 기성 스킬을 담고 있죠. (여기서 AgentKit은 Claude Code용 키트—CLI ak, agentkit.best—를 뜻하며 OpenAI의 AgentKit이 아니에요.) 이 Engineer Kit은 99달러로 올라와 있고 평생 업데이트와 환불 보장이 딸려 있어요. 페이지에 정기 결제 언급은 없어요. 몇 가지 선택지를 먼저 비교하고 싶다면, 제가 정리한 2026년 최고의 Claude Code 키트에서 나란히 견줘 봤어요. AgentKit 스킬 팩을 둘러보고(링크로 20% 할인) 직접 판단해 봐도 좋아요.

필요가 크지 않다면 먼저 직접 스킬을 쓰세요. 키트는 큰 라이브러리를 처음부터 만드는 수고를 건너뛰고 싶을 때에만 값을 해요.

모범 사례와 한계

스킬은 편리하지만 "설치하면 완벽"은 아니에요. 솔직한 그림을 보여드릴게요.

• 설명은 항상 컨텍스트에 있어요. 모든 스킬의 한 줄 설명은 늘 컨텍스트 윈도에 자리 잡아요. 스킬 하나당 비용은 아주 작지만, 겹치는 스킬 수십 개를 설치하면 쌓이고, Claude가 올바른 걸 고르기 더 어려워질 수 있어요—이름과 설명은 서로 구별되게 유지하세요.
• 모델은 스킬을 무시할 수 있어요. 스킬이 자동 발동하지 않는다면, 설명이 거의 틀림없이 너무 모호한 거예요. 구체적인 트리거("~할 때 사용")로 강화하거나, 그냥 /skill-name으로 직접 호출하세요.
• 호출된 스킬은 여러 턴에 걸쳐 남아요. 점진적 공개는 "아직 쓰지 않은" 부분의 토큰을 아끼지만, 일단 스킬이 로드되면 본문은 세션 내내 컨텍스트에 남아요. 본문은 짧게 유지하고 긴 참고 자료는 보조 파일로 밀어내세요.
• 부작용이 있는 작업은 지키세요. 배포·삭제·프로덕션 쓰기를 하는 스킬에는 disable-model-invocation을 설정해 Claude가 스스로 발동하지 못하게 하세요—여러분이 의도적으로 호출하는 거예요.
• 모든 걸 스킬로 만들지 마세요. 모든 턴에 적용되는 관례(저장소의 일반 코딩 스타일)는 여전히 CLAUDE.md에 속하고, 스킬은 작업별 워크플로를 위한 거예요. 올바른 자리를 고르는 게 토큰을 효율적으로 유지하는 길이에요. 커밋하기 전에 스킬의 통과율을 토큰 비용과 견주어 평가하려면 skill-creator 도구를 쓸 수도 있어요.

FAQ

Claude Code 스킬은 무료인가요?

네—스킬은 Claude Code의 내장 기능이라, 기존 Claude Code 요금제(예를 들어 월 20달러의 Pro) 외에 사용하거나 직접 만드는 데 드는 비용은 없어요. 비용은 서드파티가 미리 만든 스킬 팩을 구매하기로 할 때에만 생겨요.

스킬 vs MCP—무엇이 다른가요?

스킬은 Claude가 작업을 어떻게 하는지 빚는 마크다운 지시문(그리고 선택적 스크립트)이에요. MCP는 Claude를 외부 도구와 데이터에 연결하는 프로토콜이고요. 스킬은 행동을 바꾸고, MCP는 능력을 더해요. 둘은 함께 작동해요—스킬은 MCP로 연결된 도구를 잘 쓰는 법을 설명할 수 있어요.

스킬은 어디에 두나요?

개인 스킬은 ~/.claude/skills/(컴퓨터 어디서나 사용 가능)에, 프로젝트 스킬은 저장소 안 .claude/skills/(커밋해서 팀과 공유)에 두세요. 각 스킬은 SKILL.md를 담은 자체 폴더예요.

Claude가 스킬을 자동으로 호출할 수 있나요?

네. Claude는 요청을 각 스킬의 description과 대조해 가장 잘 맞는 걸 자동으로 호출해요—이름을 댈 필요가 없어요. /skill-name으로 직접 호출하거나, disable-model-invocation을 설정해 수동 호출을 강제할 수도 있어요.

스킬은 Claude 앱과 API에서도 작동하나요?

네. 스킬은 개방형 Agent Skills 표준을 따르므로 Claude 앱(Pro, Max, Team, Enterprise)에서도, Developer Platform / Skills API를 통해서도 작동해요. Claude Code는 호출 제어, 서브에이전트 실행, 동적 컨텍스트 주입 같은 터미널 전용 부가 기능을 더해요.

스킬은 CLAUDE.md와 어떻게 다른가요?

CLAUDE.md는 모든 턴에 적용되는 관례를 담고 항상 컨텍스트에 남아요. 스킬은 특정 작업을 위한 지시문을 담고, 점진적 공개 덕분에 호출될 때에만 본문 전체를 로드해요. 상시 규칙에는 CLAUDE.md를, 작업별 워크플로에는 스킬을 쓰세요.

결론과 다음 단계

Claude Code 스킬은 Claude에게 한 번에 한 작업씩 일을 가르치는 깔끔한 방법이에요: 폴더 하나, SKILL.md 하나, 자동으로 또는 /skill-name으로 발동하며, 점진적 공개로 비용을 낮게 유지해요. 여기서부터는 개념의 무리 전체를 자리매김하도록 스킬 vs 서브에이전트 vs 훅 vs MCP 전체 정리를 읽고, 아직 감을 잡는 중이라면 Claude Code란 무엇인가를 다시 보고, 빈 파일보다 준비된 라이브러리에서 시작하고 싶다면 처음부터 직접 쓰기 전에 AgentKit 스킬 팩을 사용해 보세요(링크로 20% 할인).