아무것도 모르는 사람도 5분이면 이해하는
Claude Code Skill의 모든 것
Everything about Claude Code Skills
explained so anyone can understand in 5 minutes
한 줄 요약: Claude에게 주는 전문 매뉴얼이다. One-line summary: A professional manual you give to Claude.
새로 온 카페 알바생(Claude)은 머리가 아주 좋지만, 우리 가게만의 레시피는 모릅니다.
☕ "아메리카노 만들어줘" → 기본적으로 잘 만듦
📋 "우리 가게 시그니처 라떼 만들어줘" → 레시피 없으면 자기 맘대로 만듦
이때 Skill = 우리 가게 레시피 매뉴얼입니다.
"원두는 이거, 우유 온도는 65도, 라떼아트는 하트 모양" — 이렇게 적어놓으면, 알바생은 매번 완벽하게 시그니처 라떼를 만들 수 있죠.
The new cafe part-timer (Claude) is very smart, but doesn't know your shop's unique recipes.
☕ "Make me an Americano" → Does it perfectly by default
📋 "Make our signature latte" → Without a recipe, improvises however they like
In this case, Skill = your shop's recipe manual.
"Use this bean, milk temp at 65°C, heart-shaped latte art" — written down once, the part-timer can make the perfect signature latte every time.
Skill의 핵심은 SKILL.md라는 마크다운 파일 하나입니다. 거기에 "이럴 때 이렇게 해라"라고 적어둔 것이죠.
The heart of a Skill is a single markdown file called SKILL.md. It's simply instructions written as "do this when that happens."
한 번 설치하면 관련 요청이 올 때 Claude가 알아서 해당 Skill을 읽고 따릅니다. 또는 /skill-name으로 직접 호출할 수도 있어요.
Once installed, Claude automatically reads and follows the Skill when relevant requests come in. You can also invoke it directly with /skill-name.
코드 리뷰, 배포 워크플로우, 이메일 작성, 브랜드 가이드 적용 등 원하는 건 뭐든 Skill로 만들 수 있습니다.
Code review, deployment workflows, email writing, brand guide application — anything you want can be turned into a Skill.
Skills는 이제 단순 파일이 아닌 디렉토리입니다. SKILL.md가 진입점이 되고, 보조 파일들을 함께 넣을 수 있습니다.
Skills are no longer just files but directories. SKILL.md serves as the entry point, and you can include supporting files alongside it.
commands/review.md와 skills/review/SKILL.md 둘 다 /review를 만들고 동일하게 작동합니다. Skills는 디렉토리 구조, frontmatter 옵션, 자동 로딩 등 추가 기능을 제공합니다.commands/review.md and skills/review/SKILL.md create /review and work the same way. Skills offer additional features: directory structure, frontmatter options, and auto-loading.| 위치Location | 경로Path | 적용 범위Scope |
|---|---|---|
| Enterprise | 관리 설정 참조 | 조직 전체Entire org |
| Personal | ~/.claude/skills/<name>/SKILL.md | 모든 프로젝트All projects |
| Project | .claude/skills/<name>/SKILL.md | 이 프로젝트만This project only |
| Plugin | <plugin>/skills/<name>/SKILL.md | 플러그인 활성화 위치Plugin activation scope |
우선순위: Enterprise > Personal > Project. 같은 이름의 Skill이 여러 위치에 있으면 우선순위가 높은 것이 사용됩니다.Priority: Enterprise > Personal > Project. If a Skill with the same name exists in multiple locations, the higher-priority one is used.
핵심 이유는 하나입니다 — 매번 같은 말 반복하기 싫으니까. One core reason — no one wants to repeat the same instructions every time.
Skill을 쓰면 Claude가 매번 같은 수준의 결과물을 만듭니다. 어제 잘했다가 오늘 이상하게 만드는 일이 없어지죠. 회사 브랜드 가이드, 코드 스타일 같은 걸 정해두면 흔들림이 없습니다.
With a Skill, Claude produces the same quality every time. No more "did it great yesterday, weird today." Lock in brand guides, code styles — rock-solid consistency.
복잡한 지시사항을 매번 입력하면 하루에 30분은 날립니다. Skill에 한 번 적어두면 그 시간이 0이 됩니다. 하루에 10번 같은 작업을 하는 사람이라면? 인생이 바뀝니다.
Typing complex instructions every time wastes 30 minutes a day. Write it in a Skill once and that time becomes zero. If you do the same task 10 times a day? Life-changing.
프롬프트만으로는 한계가 있습니다. Skill에 구체적인 스크립트와 템플릿, 참고 자료까지 넣으면 Claude의 결과물이 "프로 수준"으로 점프합니다.
Prompts alone have limits. Add specific scripts, templates, and reference materials to a Skill and Claude's output jumps to "professional level."
프로젝트의 .claude/skills/ 폴더를 버전 관리(git)에 커밋하면 팀 전체가 동일한 Skill을 사용할 수 있습니다. "우리 팀은 이렇게 일한다"를 코드처럼 관리하세요.
Commit the project's .claude/skills/ folder to version control (git) and the entire team can use the same Skills. Manage "how our team works" like code.
Claude Code에는 이미 강력한 Skills가 내장되어 있습니다. 설치 없이 /skill-name으로 바로 호출 가능합니다.
Claude Code already comes with powerful built-in Skills. Call them with /skill-name without any setup.
/help, /compact 같은 기본 명령어는 고정된 로직을 실행합니다. 반면 번들 Skills(/simplify, /batch 등)는 프롬프트 기반입니다. Claude에게 상세한 플레이북을 제공하고 도구를 활용해 작업을 조율하므로, 병렬 에이전트 생성, 파일 읽기, 코드베이스 적응이 가능합니다./help and /compact run fixed logic. Built-in Skills (/simplify, /batch, etc.) are prompt-based. They give Claude a detailed playbook and coordinate tasks using tools, enabling parallel agent creation, file reading, and codebase adaptation.| Skill 이름Skill Name | 하는 일What It Does |
|---|---|
| /simplify |
최근 변경된 파일을 코드 재사용, 품질, 효율성 관점으로 검토하고 수정합니다. 기능 구현 후 실행해 코드를 정리하세요. 3개의 검토 에이전트를 병렬로 생성(코드 재사용, 코드 품질, 효율성)하고 결과를 집계해 수정합니다. 선택적으로 포커스를 지정할 수 있습니다:
/simplify focus on memory efficiencyReviews and refactors recently changed files for code reuse, quality, and efficiency. Run it after implementing features to clean up code. Spawns 3 review agents in parallel (code reuse, code quality, efficiency), aggregates results, and applies fixes. Optionally specify focus:
/simplify focus on memory efficiency |
| /batch <instruction> |
코드베이스 전체에 대규모 변경을 병렬로 조율합니다. 변경 설명을 제공하면 코드베이스를 조사하고, 작업을 5~30개의 독립적인 단위로 분해해 승인을 요청합니다. 승인 후 각 단위별로 백그라운드 에이전트를 생성하고, 각 에이전트는 격리된 git worktree에서 작업합니다. git 저장소가 필요합니다. 예:
/batch migrate src/ from Solid to ReactOrchestrates large-scale changes across the codebase in parallel. Provide a change description, it investigates the codebase and breaks the work into 5–30 independent units for approval. Then spawns background agents per unit, each working in an isolated git worktree. Requires a git repo. Example:
/batch migrate src/ from Solid to React |
| /debug [description] |
세션 디버그 로그를 읽어 현재 Claude Code 세션을 문제 해결합니다. 선택적으로 문제 설명을 추가해 분석 초점을 맞출 수 있습니다.
Reads session debug logs to troubleshoot the current Claude Code session. Optionally add a problem description to focus the analysis.
|
SKILL.md 상단의 YAML frontmatter로 Skill의 동작을 세밀하게 제어할 수 있습니다.
The YAML frontmatter at the top of SKILL.md lets you fine-tune exactly how a Skill behaves.
| 필드 | 설명 | 필수 |
|---|---|---|
| name | Skill의 표시 이름. 생략하면 디렉토리 이름 사용. 소문자, 숫자, 하이픈만 가능 (최대 64자)Display name of the Skill. If omitted, uses the directory name. Only lowercase, numbers, and hyphens (max 64 chars). | 권장 아님Not recommended |
| description | Skill이 하는 일과 사용 시기. Claude가 이것을 보고 자동 발동 여부를 결정합니다. 가장 중요한 필드!What the Skill does and when to use it. Claude reads this to decide whether to auto-trigger it. Most important field! | 강력 권장Strongly recommended |
| argument-hint | 자동완성 중 표시되는 힌트. 예: [issue-number], [filename] [format]Hint shown during autocomplete. Example: [issue-number], [filename] [format] |
선택Optional |
| disable-model-invocation | true로 설정하면 Claude가 자동으로 Skill을 로드하지 않습니다. /deploy, /commit처럼 타이밍이 중요한 워크플로우에 사용Set to true to prevent Claude from auto-loading this Skill. Use for timing-critical workflows like /deploy or /commit. |
선택Optional |
| user-invocable | false로 설정하면 / 메뉴에서 숨겨집니다. 사용자가 직접 호출하면 안 되는 배경 지식용Set to false to hide from the / menu. Use for background knowledge that shouldn't be called directly by users. |
선택Optional |
| allowed-tools | 이 Skill이 활성화됐을 때 별도 승인 없이 사용 가능한 도구 목록. 예: Read, Grep, Glob, Bash(gh *)List of tools usable without extra approval when this Skill is active. Example: Read, Grep, Glob, Bash(gh *) |
선택Optional |
| model | 이 Skill이 활성화됐을 때 사용할 모델Model to use when this Skill is active. | 선택Optional |
| context | fork로 설정하면 격리된 subagent 컨텍스트에서 실행됩니다. 대화 기록에 접근할 수 없습니다Set to fork to run in an isolated subagent context. Cannot access conversation history. |
선택Optional |
| agent | context: fork가 설정됐을 때 사용할 subagent 유형. 기본값: general-purpose. Explore, Plan 등 내장 에이전트 또는 커스텀 에이전트Subagent type when context: fork is set. Default: general-purpose. Built-in: Explore, Plan, or custom agents. |
선택Optional |
| hooks | 이 Skill의 라이프사이클에 범위가 지정된 hooksHooks scoped to the lifecycle of this Skill. | 선택Optional |
Skill 호출 시 인수를 전달할 수 있습니다. 여러 방식으로 인수에 접근 가능합니다. You can pass arguments when invoking a Skill. Multiple ways to access them are available.
| 변수Variable | 설명Description |
|---|---|
| $ARGUMENTS | Skill 호출 시 전달된 모든 인수. Skill 내용에 없으면 ARGUMENTS: <value>로 끝에 추가됨All arguments passed when invoking the Skill. If not referenced in content, appended as ARGUMENTS: <value> at the end. |
| $ARGUMENTS[N] | 0 기반 인덱스로 특정 인수 접근. 예: $ARGUMENTS[0]은 첫 번째 인수Access a specific argument by 0-based index. Example: $ARGUMENTS[0] is the first argument. |
| $N | $ARGUMENTS[N]의 약자. 예: $0은 첫 번째, $1은 두 번째 인수Shorthand for $ARGUMENTS[N]. Example: $0 is the first, $1 is the second argument. |
| ${CLAUDE_SESSION_ID} | 현재 세션 ID. 로깅, 세션별 파일 생성에 유용 |
사용자만 호출 가능합니다. Claude가 "준비된 것 같으니 배포하자"라고 자동 실행하는 것을 방지합니다. /deploy, /commit, /send-slack-message처럼 부작용이 있거나 타이밍이 중요한 워크플로우에 사용하세요.
Only the user can invoke it. Prevents Claude from auto-running like "looks ready, let's deploy." Use for workflows with side effects or timing requirements like /deploy, /commit, /send-slack-message.
Claude만 호출 가능합니다. / 메뉴에서 숨겨집니다. 실행 가능한 명령이 아닌 배경 지식용으로 사용하세요. 예: 레거시 시스템 컨텍스트를 담은 Skill — Claude는 관련이 있을 때 자동으로 읽지만, 사용자가 직접 호출할 필요는 없습니다.
Only Claude can invoke it. Hidden from the / menu. Use for background knowledge, not executable commands. Example: a Skill with legacy system context — Claude reads it automatically when relevant, but users don't need to call it directly.
| Frontmatter 설정Frontmatter Setting | 사용자 호출User Invoke | Claude 자동 호출Claude Auto-invoke | 컨텍스트 로딩Context Loading |
|---|---|---|---|
| (기본값)(default) | 가능Yes | 가능Yes | 설명은 항상, 본문은 호출 시Description always; body on invoke |
disable-model-invocation: true |
가능Yes | 불가No | 설명 없음, 사용자 호출 시 로드No description; loaded on user invoke |
user-invocable: false |
불가No | 가능Yes | 설명은 항상, 본문은 호출 시Description always; body on invoke |
생각보다 쉽습니다. 결국 텍스트 파일 하나 쓰는 겁니다. Easier than you think. In the end, it's just writing a text file.
개인 Skill은 ~/.claude/skills/에, 프로젝트 Skill은 .claude/skills/에 디렉토리를 만듭니다.
Create a directory under ~/.claude/skills/ for personal Skills, or under .claude/skills/ for project Skills.
두 부분으로 구성됩니다: YAML frontmatter(언제 발동할지)와 마크다운 지시문(실제 작업 내용). description이 핵심입니다!
It has two parts: YAML frontmatter (when to trigger) and markdown instructions (what to do). The description is the key!
description에 사용자가 자연스럽게 말할 키워드를 포함시키세요. Claude는 description을 보고 "이 Skill을 쓸지 말지"를 결정합니다. "코드 설명", "이게 어떻게 동작해", "how does this work" 등 구체적으로 적을수록 좋습니다.description. Claude reads the description to decide "should I use this Skill?" Be specific: "explain code", "how does this work", etc.두 가지 방법으로 테스트할 수 있습니다.
Two ways to test your Skill.
복잡한 Skill은 SKILL.md에서 참조하는 보조 파일을 추가할 수 있습니다. SKILL.md는 500줄 이하로 유지하고, 상세한 참조 자료는 별도 파일로 분리하세요.
Complex Skills can include supporting files referenced from SKILL.md. Keep SKILL.md under 500 lines and separate detailed reference material into separate files.
SKILL.md 안에 "상세 API 문서는 [reference.md](reference.md) 참조"처럼 명시하면 Claude가 언제 무엇을 읽어야 하는지 알 수 있습니다.SKILL.md so Claude knows when and what to read.프로젝트 Skill은 git으로 버전 관리하면 팀 전체가 자동으로 사용할 수 있습니다.
Version-control project Skills in git so the entire team can use them automatically.
SKILL.md를 생성해줍니다. 그 파일을 검토하고 다듬으면 됩니다.SKILL.md. Just review and refine it.
SwiftUI 앱 개발에 특화된 코드 리뷰 Skill 예시입니다. disable-model-invocation: true로 사용자가 직접 호출할 때만 실행됩니다.
A code review Skill specialized for SwiftUI app development. Uses disable-model-invocation: true so it only runs when the user explicitly calls it.
Skills를 훨씬 강력하게 만들어주는 고급 기능들입니다. Advanced features that make Skills much more powerful.
!`command` 구문을 사용하면 Skill 콘텐츠가 Claude로 전송되기 전에 shell 명령어를 실행합니다. 명령어 출력이 자리 표시자를 대체하므로 Claude는 실제 데이터를 받습니다.
The !`command` syntax runs a shell command before Skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data.
ultrathink라는 단어를 포함하면 해당 Skill에서 확장 사고(extended thinking)가 자동으로 활성화됩니다.
context: fork를 추가하면 Skill이 격리된 subagent에서 실행됩니다. 대화 기록에 접근할 수 없으며, Skill 콘텐츠 자체가 subagent의 프롬프트가 됩니다.
Add context: fork to run the Skill in an isolated subagent. It cannot access conversation history; the Skill content itself becomes the subagent's prompt.
Skill에 작업을 작성하고 실행할 에이전트 유형을 지정합니다. Skill 콘텐츠가 subagent의 프롬프트가 됩니다.
Write the task in the Skill and specify the agent type to run it. The Skill content becomes the subagent's prompt.
반대 방향으로도 가능합니다. 사용자 정의 subagent가 skills 필드로 Skills를 참조 자료로 사전 로드할 수 있습니다. Subagents 문서를 참조하세요.
The reverse is also possible. Custom subagents can pre-load Skills as reference material using the skills field. See the Subagents docs for details.
monorepo 환경에서 packages/frontend/의 파일을 편집할 때 Claude Code는 packages/frontend/.claude/skills/에서도 Skills를 자동으로 찾습니다. 각 패키지가 자신만의 Skills를 가질 수 있습니다.
In a monorepo, when editing files in packages/frontend/, Claude Code also automatically looks for Skills in packages/frontend/.claude/skills/. Each package can have its own Skills.
처음 접하는 분들이 가장 많이 궁금해하는 것들 The most common questions from first-timers
.claude/commands/review.md와 .claude/skills/review/SKILL.md 둘 다 /review를 생성하고 동일하게 작동합니다. 기존 .claude/commands/ 파일은 계속 작동하니 당장 마이그레이션할 필요는 없습니다..claude/skills/) 방식의 장점: ① 디렉토리 구조로 보조 파일(템플릿, 스크립트, 예시) 추가 가능 ② frontmatter로 호출 제어(disable-model-invocation, user-invocable) ③ context: fork로 subagent 실행 ④ 같은 이름이 있을 때 Skills가 commands보다 우선순위가 높음..claude/commands/review.md and .claude/skills/review/SKILL.md create /review and work identically. Existing .claude/commands/ files continue to work — no immediate migration needed..claude/skills/) approach: ① Add supporting files (templates, scripts, examples) via directory structure ② Control invocation via frontmatter (disable-model-invocation, user-invocable) ③ Run in subagent with context: fork ④ When names conflict, Skills take priority over commands./context를 실행하면 제외된 Skills에 대한 경고를 볼 수 있습니다. SLASH_COMMAND_TOOL_CHAR_BUDGET 환경 변수로 제한을 조정할 수 있습니다./context to see warnings about excluded Skills. Adjust the limit with the SLASH_COMMAND_TOOL_CHAR_BUDGET env variable./skill-name으로 직접 호출해서 Skill 자체가 제대로 작동하는지 확인합니다.disable-model-invocation: true를 추가하세요./skill-name to invoke directly and verify the Skill itself works correctly.disable-model-invocation: true.context: fork는 명시적 실행 지침이 있는 Skill에만 의미가 있습니다. "이 API 규칙을 사용하세요" 같은 참조용 Skill에 사용하면 subagent가 지침을 받지만 실행할 내용이 없어 의미 없는 결과를 반환합니다.context: fork only makes sense for Skills with explicit execution instructions. Using it on a reference Skill like "use these API rules" causes the subagent to receive instructions but have nothing to execute, returning meaningless results.disable-model-invocation: true 추가. 사용자만 호출 가능합니다./permissions에서 Skill(deploy *) 같은 거부 규칙을 추가하면 Claude가 해당 Skill을 호출할 수 없습니다./permissions에서 Skill을 거부 규칙으로 추가하면 Claude가 어떤 Skill도 자동 호출할 수 없습니다.disable-model-invocation: true to SKILL.md frontmatter. Only users can invoke it.Skill(deploy *) in /permissions to prevent Claude from calling that Skill.Skill as a deny rule in /permissions to prevent Claude from auto-invoking any Skill.
Skill = Claude에게 주는 영구적 업무 매뉴얼
저장 위치 = ~/.claude/skills/ 또는 .claude/skills/
핵심 파일 = SKILL.md (YAML frontmatter + 마크다운 지시문)
시작이 어려우면, Claude에게 이렇게 말해보세요:
"내 워크플로우를 .claude/skills/ 에 Skill로 만들어줘"
Skill = A permanent work manual you give to Claude
Location = ~/.claude/skills/ or .claude/skills/
Core file = SKILL.md (YAML frontmatter + markdown instructions)
If you're not sure where to start, tell Claude:
"Create my workflow as a Skill in .claude/skills/"