Skills로 Claude 확장하기
Claude Code에서 Claude의 기능을 확장하는 skills를 생성, 관리, 공유합니다. 커스텀 슬래시 명령어를 포함합니다.
Skills는 Claude가 할 수 있는 것을 확장합니다. SKILL.md 파일에 지시사항을 작성하면, Claude가 이를 자신의 툴킷에 추가합니다. Claude는 관련이 있을 때 skills를 사용하거나, /skill-name으로 직접 호출할 수도 있습니다.
참고:
/help나/compact같은 내장 명령어는 interactive mode를 참조하세요.
커스텀 슬래시 명령어가 skills로 통합되었습니다.
.claude/commands/review.md파일과.claude/skills/review/SKILL.md의 skill 모두/review를 생성하며 동일하게 동작합니다. 기존.claude/commands/파일들은 계속 작동합니다. Skills는 추가 기능을 제공합니다: 지원 파일을 위한 디렉토리, 사용자 또는 Claude가 호출할지를 제어하는 frontmatter, 그리고 관련이 있을 때 Claude가 자동으로 로드하는 기능.
Claude Code skills는 여러 AI 도구에서 작동하는 Agent Skills 오픈 표준을 따릅니다. Claude Code는 이 표준을 호출 제어(invocation control), 서브에이전트 실행(subagent execution), 동적 컨텍스트 주입(dynamic context injection) 같은 추가 기능으로 확장합니다.
역주:
- Plugin: Claude Code의 확장 기능(skills, hooks, CLAUDE.md 등)을 하나로 패키징해서 다른 프로젝트나 팀과 공유할 수 있는 배포 단위입니다.
- Command: skills 이전에 사용하던 커스텀 슬래시 명령어 방식입니다.
.claude/commands/폴더 에.md파일로 저장합니다. 현재는 skills로 통합되었지만, 기존 command 파일도 계속 작동합니다.
시작하기
첫 번째 skill 만들기
이 예제는 시각적 다이어그램과 비유를 사용해 코드를 설명하도록 Claude를 가르치는 skill을 만듭니다. 기본 frontmatter를 사용하므로, 무언가가 어떻게 동작하는지 물어볼 때 Claude가 자동으로 로드하거나, /explain-code로 직접 호출할 수 있습니다.
1단계: skill 디렉토리 만들기
개인 skills 폴더에 skill을 위한 디렉토리를 만듭니다. 개인 skills는 모든 프로젝트에서 사용할 수 있습니다.
mkdir -p ~/.claude/skills/explain-code
2단계: SKILL.md 작성하기
모든 skill에는 두 부분으로 구성된 SKILL.md 파일이 필요합니다: Claude가 언제 skill을 사용할지 알려주는 YAML frontmatter(--- 마커 사이)와, skill이 호출될 때 Claude가 따르는 지시사항이 담긴 markdown 콘텐츠. name 필드는 /슬래시-명령어가 되고, description은 Claude가 해당 skill을 언제 자동으로 로드할지 결정하는 데 도움을 줍니다.
~/.claude/skills/explain-code/SKILL.md 파일을 만듭니다:
---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---
When explaining code, always include:
1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?
Keep explanations conversational. For complex concepts, use multiple analogies.
3단계: skill 테스트하기
두 가지 방법으로 테스트할 수 있습니다:
Claude가 자동으로 호 출하도록 description과 일치하는 질문을 합니다:
How does this code work?
또는 직접 호출합니다 skill 이름으로:
/explain-code src/auth/login.ts
어느 쪽이든, Claude는 설명에 비유와 ASCII 다이어그램을 포함해야 합니다.
skill 저장 위치
skill을 어디에 저장하느냐에 따라 누가 사용할 수 있는지가 결정됩니다:
| 위치 | 경로 | 적용 범위 |
|---|---|---|
| Enterprise | managed settings 참조 | 조직 내 모든 사용자 |
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | 내 모든 프로젝트 |
| Project | .claude/skills/<skill-name>/SKILL.md | 해당 프로젝트만 |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md | 플러그인이 활성화된 곳 |
여러 레벨에서 같은 이름의 skill이 있으면, 높은 우선순위의 위치가 우선합니다: enterprise > personal > project. Plugin skills는 plugin-name:skill-name 네임스페이스를 사용하므로, 다른 레벨과 충돌하지 않습니다. .claude/commands/에 파일이 있다면 동일하게 동작하지만, skill과 command가 같은 이름이면 skill이 우선합니다.
중첩 디렉토리 자동 탐색
하위 디렉토리의 파일을 작업할 때, Claude Code는 중첩된 .claude/skills/ 디렉토리에서 skills를 자동으로 탐색합니다. 예를 들어, packages/frontend/에서 파일을 편집하고 있다면, Claude Code는 packages/frontend/.claude/skills/에서도 skills를 찾습니다. 이는 패키지별로 고유한 skills를 가진 모노레포 구성을 지원합니다.
각 skill은 SKILL.md를 진입점으로 하는 디렉토리입니다:
my-skill/
├── SKILL.md # 메인 지시사항 (필수)
├── template.md # Claude가 출력할 때 참고하는 양식
├── examples/
│ └── sample.md # 예상 형식을 보여주는 예제 출력
└── scripts/
└── validate.sh # Claude가 실행할 수 있는 스크립트
SKILL.md는 메인 지시사항을 담고 있으며 필수입니다. 나머지 파일들은 선택 사항이며, 더 강력한 skills를 만들 수 있게 해줍니다:
template.md- Claude가 출력할 때 참고하는 양식examples/- 원하는 출력 형식의 예제scripts/- Claude가 실행할 수 있는 스크립트- 기타 상세한 레퍼런스 문서
SKILL.md에서 이 파일들을 언급해두면, Claude가 각 파일의 용도와 언제 참조해야 하는지 파악할 수 있습니다.
추가 디렉토리의 skills
--add-dir로 추가된 디렉토리 내의 .claude/skills/에 정의된 skills는 자동으로 로드되고, 실시간 변경 감지가 적용됩니다. 따라서 세션 중에 편집해도 재시작 없이 반영됩니다.