Skills는 아직도 많은 사람이 사용하지 않는 Claude Code의 가장 중요한 기능입니다. Claude Skill은 SKILL.md 파일을 포함한 폴더로, 프롬프트가 설명에 일치하는 순간 Claude가 자동으로 로드합니다 — 프롬프트를 복사하고 붙여넣을 필요도, 부풀린 CLAUDE.md도, 어떤 템플릿을 가져올지 기억할 필요도 없습니다. 이 저장소의 .claude/skills/agent/ 폴더에 4개의 skill을 배포했으며, Skills 2.0과 2026년 초 Anthropic Marketplace 출시로 이제야 이 포맷이 제 성능을 낼 수 있게 되었습니다. 여기 시행착오를 거쳐 정립된 패턴을 소개합니다.
Claude Skills란 무엇인가요?
Claude Skill은 YAML frontmatter (name, description, 선택사항: allowed-tools)가 있는 SKILL.md 파일을 포함한 폴더로, 프롬프트가 설명과 일치할 때 Claude Code가 자동으로 컨텍스트에 로드합니다. Skills는 /commit이나 /explain-code 같은 재사용 가능한 워크플로우를 패키징하면서 시스템 프롬프트를 부풀리지 않습니다.
Anthropic의 공식 문서에 따르면, 모든 skill 폴더는 세 가지를 포함합니다: 필수인 SKILL.md, 선택사항인 번들된 스크립트(Python 헬퍼부터 JSON 설정까지 뭐든지), 선택사항인 본문과 함께 로드되는 레퍼런스 문서. 이게 전부입니다. 빌드 단계도 없고, 설치도 없고, 매니페스트도 없습니다.
영리한 부분은 점진적 공개입니다. 시작할 때 Claude는 모든 skill의 description 필드만 스캔합니다. 본문 — 지침, 예제, 도구 호출 패턴 — 은 실제로 프롬프트가 일치할 때까지 디스크에 남아 있습니다. 따라서 50개의 skill을 설치해도 하나가 작동할 때까지 토큰 비용이 전혀 없습니다.
Skill을 Claude가 프롬프트의 재료를 보면 펼치는 요리책 레시피처럼 생각해보세요. Skill은 Claude가 필요할 때 읽는 폴더입니다 — 붙여넣기를 기억해야 하는 프롬프트가 아닙니다. 그게 핵심입니다.
최소한의 SKILL.md는 다음과 같습니다:
---
name: explain-code
description: walk me through what this code does
---
Carefully read the specified file or code snippet the user references.
Explain what it does, why those design choices were made, and how it fits with adjacent code.
Focus on intention and logic, not syntax.
10줄. 진짜 skill. 작동할 준비 완료.
빠른 시작: 10분에 첫 Skill 구축하기
10분에 첫 Claude skill을 구축하려면: (1) ~/.claude/skills/explain-code/ 디렉터리 생성, (2) name, description, 워크플로우 본문이 있는 SKILL.md 파일 추가, (3) Claude Code를 재시작해 새 디렉터리 스캔, (4) 설명과 일치하는 프롬프트로 작동시키기.
전체 흐름입니다.
1단계: 디렉터리 생성하기
개인 skill(자신만 사용)은 ~/.claude/skills/ 아래로 갑니다. 프로젝트 skill(팀과 git으로 공유)은 저장소 루트의 .claude/skills/ 아래로 갑니다. 일상적인 워크플로우는 개인으로, 모든 기여자가 이를 상속받게 하려면 프로젝트로 선택하세요.
2단계: SKILL.md 작성하기
이 파일을 ~/.claude/skills/explain-code/SKILL.md에 드롭하세요:
---
name: explain-code
description: walk me through what this code does; explain a code snippet
---
Carefully read the file or code snippet the user references.
Explain what it does, the design choices, and how it connects to adjacent code.
Focus on intention and logic. Use examples if the logic is subtle.
이게 전부입니다. Frontmatter가 계약이고 본문이 플레이북입니다.
3단계: Claude Code 재시작하기
Live discovery는 Skills 2.0의 기능입니다 — 이전 Claude Code 버전은 새 디렉터리를 픽업하려면 재시작이 필요합니다. 사용 중인 버전을 잘 모르면 재시작 한 번은 비용이 없습니다.
4단계: 작동시키기
프로젝트를 열고 프롬프트를 입력하세요:
walk me through what auth/middleware.ts does
Claude가 프롬프트를 description 필드와 일치시키고, explain-code를 찾고, SKILL.md 본문을 컨텍스트에 조용히 로드합니다. 도구 로그에서 "Using skill: explain-code"를 보게 됩니다. 완료.
10분 약속이 지켜집니다 — 5분의 타이핑, 한 번의 재시작, 한 번의 테스트 프롬프트.
SKILL.md 내부: Frontmatter 레퍼런스
SKILL.md frontmatter는 --- 구분자로 감싼 YAML입니다. 두 필드는 필수입니다: name (≤64자, 슬래시 명령 이름으로 사용)과 description (Claude가 프롬프트와 대조하는 트리거 텍스트). 선택사항 필드는 도구 접근, 모델 호출, 파일 glob, 실행 컨텍스트를 제어합니다.
Anthropic의 skills 문서를 출처로 한 전체 레퍼런스입니다:
---
name: string(≤64) # 필수. /slash-command 이름
description: string(≤1024) # 필수. Claude의 프롬프트 일치 트리거
allowed-tools: # 선택사항. 이 skill이 호출할 수 있는 도구
- Bash
- Read
- Edit
disable-model-invocation: boolean # 선택사항. true면 /slash-command만, 자동 호출 안 함
model: string # 선택사항. 기본값 대신 이 모델 사용 (claude-opus-4-8 등)
context: string # 선택사항. "fork" 시 독립된 컨텍스트 윈도우에서 실행
file-globs: # 선택사항. 이 skill을 활성화하는 파일 패턴
- "*.tsx"
- "src/api/**"
---
context: fork 행은 특별히 언급할 가치가 있습니다. 이는 Skills 2.0의 원시 기능으로, skill을 격리된 컨텍스트 윈도우 내에서 실행합니다 — 오래 실행되는 리서치 skill이나 메인 스레드를 오염시키고 싶지 않은 중간 토큰을 많이 생성하는 작업에 유용합니다. 이 개념이 생소하면 우리의 컨텍스트 엔지니어링 가이드에서 트레이드오프를 다룹니다.
모든 필드를 채운 maximalist SKILL.md frontmatter:
---
name: research-bug
description: investigate this production bug end-to-end
allowed-tools:
- Read
- Bash
- WebFetch
model: claude-opus-4-8
context: fork
file-globs:
- "src/**"
- "docs/**"
---
You are a bug investigator. When given a production error or issue, you:
1. Search logs and error traces the user provides.
2. Read relevant source files.
3. Fetch external docs if needed (API changes, library updates).
4. Propose root causes with evidence, ranked by likelihood.
5. Sketch fixes for the top 3.
Focus on evidence, not speculation. End with a prioritized action list.
두 가지 실제 Skill, 처음부터 끝까지
두 가지 skill 패턴이 현실 사용의 80%를 포함합니다: (1) disable-model-invocation: true와 allowed-tools: Bash(git *)를 가진 사용자 호출 가능 /commit skill은 결정론적 작업용; (2) 프롬프트가 설명과 일치할 때 Claude가 작동시키는 기본 frontmatter를 가진 자동 호출 /explain-code skill.
대부분의 튜토리얼은 스니펫을 보여줍니다. 여기 지금 ~/.claude/skills/에 복사해 쓸 수 있는 두 개의 완전한 파일이 있습니다.
/commit skill (사용자 호출)
테스트 프롬프트: /commit
어떤 일이 일어나는지: Claude가 git 상태를 검사하고, 메시지를 작성하고, 확인을 요청하고, 그 후에만 git commit을 실행합니다. disable-model-invocation: true는 "변경 사항을 저장해"라는 모호한 프롬프트에 절대 자동 작동하지 않음을 의미합니다 — /commit을 입력할 때만 실행합니다. allowed-tools 화이트리스트는 git 서브명령으로만 잠그고, rm -rf나 원격 푸시를 절대 실행할 수 없습니다. 우리 자신의 파이프라인에서 라이브로 배포하는 것입니다.
결정론적 커밋 후 작업(린트 실행, 타입 재생성, Slack 웹훅 핑)의 경우 Claude Code 훅을 대신 사용하세요 — skill은 확률론적이고, 훅은 매번 작동합니다.
/explain-code skill (모델 호출)
테스트 프롬프트: walk me through what auth/middleware.ts does
어떤 일이 일어나는지: 사용자가 /explain-code를 입력하지 않았다는 점을 주목하세요. Claude가 "walk me through"를 description 필드와 대조하고, skill을 찾고, 자동으로 작동시킵니다. 이게 마법입니다 — description이 라우팅을 수행합니다. model: claude-opus-4-7 필드는 기본값으로 어떤 모델을 설정했든 관계없이 이 skill을 Opus에 고정하므로 깊은 코드 설명은 항상 더 똑똑한 모델을 얻습니다. (다양한 모델로 Claude Code 실행하기에 대해 더 알아보세요.)
더 많은 실제 예제 skill은 공식 anthropics/skills 저장소와 커뮤니티 관리 awesome-claude-skills 목록을 확인하세요.
Skills vs MCP vs Subagents vs Hooks: 언제 무엇을 사용할까요?
Claude가 자동 작동하거나 슬래시 명령으로 호출해야 할 재사용 가능한 워크플로우는 Skills를 사용하세요. 라이브 외부 데이터(데이터베이스, API, 작업 디렉터리 외 파일 시스템)가 필요하면 MCP 서버를 사용하세요. 다단계 계획을 Claude가 새로운 컨텍스트에 위임해야 하면 subagent를 사용하세요. 항상 작동해야 하는 결정론적 이벤트(사전 커밋, 사후 도구 사용)에는 훅을 사용하세요 — 절대 확률론적이지 않습니다.
빠른 프레이밍: skill은 워크플로우, Model Context Protocol은 데이터, subagent는 계획, 훅은 이벤트입니다. 각각은 Claude Code의 다른 계층에 있고, 잘못된 계층은 잘못된 도구입니다. Anthropic의 자체 Skills explained 포스트에 따르면 이것이 그들이 원하는 프레이밍입니다.
이들은 구성됩니다. Skill은 allowed-tools을 통해 MCP 도구를 호출할 수 있습니다. 훅은 skill 완료 후 작동할 수 있습니다. Subagent는 접근 권한이 주어진 skill을 사용할 수 있습니다. 가장 깨끗한 정신 모델: 먼저 올바른 계층을 선택한 다음 이들을 쌓게 놔두세요. Skills는 워크플로우가 Claude가 선택할 수 있기를 원할 때 도달하는 컨텍스트 엔지니어링 원시 도구이고, 훅으로 자동화하는 것은 Claude가 건너뛸 수 없는 것을 원할 때입니다.
각각을 잘못 사용하는 최악의 방법: 라이브 데이터를 위한 Skills (MCP 사용); 일회성 프롬프트 템플릿을 위한 MCP (Skills 사용); 결정론적 파일 편집을 위한 subagent (훅 사용); 분기 로직을 위한 훅 (Skills 사용). Skills는 워크플로우, MCP는 데이터, subagent는 계획, 훅은 이벤트입니다. 유행어가 아니라 계층으로 선택하세요.
Skills의 위치: 개인, 프로젝트, 플러그인, 엔터프라이즈
Claude skill은 4가지 범위에 설치합니다: 개인 (~/.claude/skills/, 오직 당신만), 프로젝트 (저장소 루트의 .claude/skills/, 팀이 git으로), 플러그인 (Anthropic Marketplace나 어떤 플러그인 URL로도 배포), 엔터프라이즈 (IT가 MDM/관리자 정책을 통해 푸시). Claude는 시작할 때 4가지 모두 스캔합니다.
...