Claude Code 스킬: 만드는 법과 예시, 모범 사례

Claude Code 스킬이란

같은 지시 사항이나 체크리스트, 여러 단계로 된 절차를 계속 채팅에 붙여 넣고 있다면, 또는 CLAUDE.md의 일부가 사실을 적은 글에서 절차로 커졌다면 스킬을 만들 때예요. 스킬은 다른 AI 도구도 읽는 개방형 Agent Skills 표준(agentskills.io)을 따르고, Claude Code는 여기에 실행 제어, 서브에이전트 실행, 프롬프트 안의 실시간 셸 출력 같은 기능을 더해요.

• 실행하는 방법은 두 가지예요. 요청이 description과 맞으면 Claude가 로드하거나, 직접 /skill-name을 입력해요.
• 쓰기 전까지는 비용이 거의 들지 않아요. 컨텍스트에는 이름과 설명만 있고, 본문은 스킬이 실행될 때 로드돼요. 직접 실행할 때만 쓰도록 설정한 스킬은 설명조차 목록에 올라가지 않아요.
• 커스텀 슬래시 명령어는 이제 스킬이에요. .claude/commands/<name>.md도 계속 동작하지만, 스킬 폴더에는 보조 파일도 담을 수 있어요. Claude Code 슬래시 명령어를 참고하세요.
• Claude Code에는 /simplify, /loop, /batch, /debug 같은 번들 스킬도 함께 들어 있어요.

스킬 vs CLAUDE.md vs 서브에이전트 vs 플러그인 vs MCP

Claude Code 스킬 만드는 법

1. 둘 위치 정하기

   나만 모든 프로젝트에서 쓸 스킬은 ~/.claude/skills/<name>/에, 그 저장소에서 일하는 모두가 쓸 스킬은 저장소의 .claude/skills/<name>/에 두고 커밋하세요. 폴더 이름이 곧 명령어가 돼요. summarize-changes면 /summarize-changes예요.

2. SKILL.md 작성하기: 설명 먼저, 그다음 지시 사항

   frontmatter는 파일 맨 위 --- 줄 사이에 들어가요. 권장 항목은 description 하나뿐이에요. 용도와 사람들이 실제로 쓸 법한 말을 앞에 두세요. 그 아래에 지시 사항을 Markdown으로 쓰세요. ` !command `로 시작하는 줄은 그 명령어를 먼저 실행하고 출력을 붙여 넣으므로, 스킬이 실제 상태를 바탕으로 동작해요.

   ---
   description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
   ---
   
   ## 현재 변경 사항
   
   !`git diff HEAD`
   
   ## 지시 사항
   
   위 변경 사항을 두세 개의 글머리 기호로 요약하고, 빠진 오류 처리, 하드코딩된 값,
   업데이트해야 할 테스트처럼 위험할 수 있는 부분을 나열해.

3. 두 가지 방법으로 테스트하기

   커밋하지 않은 변경이 있는 git 프로젝트에서 claude를 시작하세요. "뭘 바꿨어?"라고 물어 Claude가 스스로 스킬을 쓰는지 확인하고, 이어서 /summarize-changes를 입력해 직접 실행해 보세요. 세션 중에 추가한 스킬은 자동으로 로드돼요. 보이지 않으면 /reload-skills를 실행하세요.

4. 누가 실행할 수 있는지 정하기

   배포나 메시지 전송처럼 부작용이 있는 스킬에는 disable-model-invocation: true를 추가해 나만 시작할 수 있게 하세요. Claude만 로드해야 하는 배경 지식에는 user-invocable: false를 추가하세요. 입력은 슬래시 명령어 가이드에서 본 것처럼 $ARGUMENTS로 넘겨요.

5. 공유하기

   .claude/skills/를 저장소에 커밋하거나, 여러 저장소나 팀에서 쓰려면 스킬을 플러그인으로 패키징하세요.

출처: Claude Code 문서, Extend Claude with skills

Claude Code 스킬 예시

1. 맞는 파일일 때만 로드되는 참조 스킬

   참조 스킬에는 Claude가 작업하면서 적용할 컨벤션을 담아요. paths를 지정하면 glob에 맞는 파일을 다룰 때만 자동으로 로드돼요.

   ---
   description: API design conventions for this codebase. Use when writing or reviewing HTTP endpoints.
   paths: ["src/api/**"]
   ---
   
   API 엔드포인트를 작성할 때:
   - RESTful한 이름과 복수형 리소스를 사용해
   - 오류는 { error: { code, message } } 형태로 반환해
   - 요청 본문은 src/api/schemas/의 스키마로 검증해

2. 보조 파일이 있는 작업 스킬

   SKILL.md는 짧게 두고 나머지는 다른 파일을 가리키세요. Claude는 SKILL.md가 지시할 때만 checklist.md를 읽고, bump.sh는 읽지 않고 실행하므로, 세부 내용은 필요해질 때까지 비용이 들지 않아요.

   release/
   ├── SKILL.md          # 단계와, 다른 파일을 언제 읽을지
   ├── checklist.md      # SKILL.md가 가리킬 때만 로드됨
   └── scripts/
       └── bump.sh       # 실행만 되고 컨텍스트로 읽히지 않음

3. 자기 서브에이전트에서 실행되는 스킬

   context: fork는 스킬을 프롬프트로 삼아 서브에이전트(여기서는 읽기 전용인 Explore 타입)를 시작해요. 서브에이전트는 내 대화를 보지 못하므로 지시 사항만으로 완결되어야 해요. background: false를 설정하지 않으면 백그라운드에서 실행돼요.

   ---
   description: Audit dependencies for known vulnerabilities and outdated majors
   context: fork
   agent: Explore
   disable-model-invocation: true
   ---
   
   패키지 매니저의 audit을 실행하고, high나 critical 결과를 수정 버전과 함께 모두 나열한 뒤
   뒤처진 메이저 버전을 보고해. 파일은 바꾸지 마.

플러그인과 마켓플레이스에서 스킬 설치하기

다른 사람이 만든 스킬은 대개 플러그인에 담겨 와요. Claude Code는 대화형 세션을 처음 시작할 때 Anthropic의 공식 마켓플레이스(claude-plugins-official)를 등록해요. /plugin으로 둘러보거나, /plugin install skill-creator@claude-plugins-official처럼 바로 설치할 수 있어요. 팀이나 커뮤니티 마켓플레이스는 먼저 /plugin marketplace add owner/repo로 추가하세요.

• 플러그인 스킬의 이름은 /plugin-name:skill-name 형태예요.
• 공식 마켓플레이스에는 플러그인마다 턴당 컨텍스트 비용과 호출할 때의 비용이 표시돼요.
• skill-creator 플러그인은 스킬 작성을 돕고, 스킬이 있을 때와 없을 때의 결과를 비교하는 평가도 실행해요.
• 저장소나 플러그인의 스킬은 믿기 전에 먼저 읽어 보세요. allowed-tools는 스킬이 실행되는 턴의 도구를 미리 승인할 수 있어요.

모범 사례, 그리고 Claude가 스킬을 무시할 때

• 설명은 매칭을 위해 쓰세요. 하는 일과 사용자가 쓰는 표현을 앞에 두세요. 목록에서는 설명과 when_to_use를 합쳐 1,536자에서 잘려요.
• 가장 중요한 지시 사항은 위쪽에 두세요. 대화가 압축되면 Claude Code는 호출된 스킬의 앞부분만 남길 수 있어요. 다시 호출하면 복원돼요.
• 스킬 파일은 이후 턴에서 다시 읽히지 않으므로, 작업 전체에 해당하는 지침("편집할 때마다 테스트를 실행해")으로 쓰세요. 절대 건너뛰면 안 되는 규칙은 훅에 두세요.
• 토큰 사용량을 줄이려면 절차를 CLAUDE.md에서 스킬로 옮기고, 직접 실행하는 스킬에는 disable-model-invocation: true를 설정하고, /skill-doctor로 컨텍스트를 쓰면서도 잘 쓰이지 않는 스킬을 확인하세요.
• 실행되지 않나요? 설명에 맞는 키워드가 있는지 확인하고, "쓸 수 있는 스킬이 뭐야?"라고 물어보고, claude plugin validate .claude/skills를 실행해 파싱되지 않는 frontmatter를 찾으세요.
• 너무 자주 실행되나요? 설명을 더 좁히거나, disable-model-invocation: true로 스킬을 수동 실행으로 바꾸세요.

스킬은 Claude Code에 방법을 가르치고, Crewmark는 매시간 할 일을 줘요.

스킬 라이브러리가 있으면 세션마다 유능해지지만, 여전히 내가 요청하기를 기다려요. Crewmark는 Claude Code, Codex, DeepSeek Harness, OpenCode 세션을 직무, 목표, 근무 시간을 가진 AI 직원으로 바꾸고, 하트비트로 깨워서 보드의 다음 이슈를 가져가게 해요. 프로젝트의 스킬도 로드된 상태로요.

1. 스킬은 저장소에 두기

   직원의 세션은 내 세션처럼 .claude/skills/와 CLAUDE.md를 읽으므로, 릴리스 스킬이나 리뷰 체크리스트도 함께 따라가요.

2. 하트비트로 일을 시작하게 하기

   근무 시간 동안 직원은 15분, 30분, 60분마다 같은 대화에서 깨어나 다음 이슈를 가져가요. Claude Code를 능동적으로 만드는 방법을 참고하세요.

3. 이슈를 배정하고 메시지에 답하기

   보드에 일을 올리면 직원은 진행하면서 댓글을 남기고, 결정이 필요하면 메시지를 보내요. AI 직원이란도 읽어 보세요.

Claude Code 스킬 자주 묻는 질문