Claude Code에서 스킬 — Claude에게 반복 작업 절차를 등록해 두는 일종의 '레시피 카드' — 을 만들었는데, /skill-name 명령어를 입력해도 아무 반응이 없거나 자동으로 실행되지 않는 경우가 있습니다. 대부분은 파일 위치, 이름, 또는 내용 형식에서 생기는 작은 실수가 원인입니다. 이 글에서는 오류 유형별로 원인을 찾아 고치는 방법을 순서대로 안내합니다. 예상 소요 시간은 약 10~15분입니다.
시작 전 준비물 확인
이 글을 따라 하려면 다음 조건이 갖춰져 있어야 합니다.
- Claude Code가 이미 설치되어 있어야 합니다. 설치가 안 된 상태라면 먼저 공식 문서의 설치 안내를 참고하세요.
- 터미널 — 명령어를 입력하는 검은 창 — 을 기본적으로 열고 닫을 수 있어야 합니다.
- 일부 번들 스킬(아래에서 설명)은 Claude Code v2.1.145 이상이 필요합니다. 버전 확인 방법은 아래에서 다룹니다.
용어 빠른 풀이
- 스킬(Skill) — Claude Code에 등록해 두는 맞춤 명령어 레시피.
SKILL.md파일 하나로 만듭니다. - SKILL.md — 스킬의 내용을 담는 마크다운 파일. 이름이 정확히
SKILL.md여야 합니다. - frontmatter — 앞부분 메타정보 — 파일 맨 위에
---로 감싸서 쓰는 설정 영역. 스킬 이름·호출 방식 등을 지정합니다. - 번들 스킬(Bundled Skills) — Claude Code가 기본으로 내장하고 있는 스킬.
/debug,/code-review,/run,/verify,/batch,/loop,/claude-api등이 있습니다. - 개인 스킬 폴더 —
~/.claude/skills/경로. 어느 프로젝트에서도 쓸 수 있는 스킬을 두는 곳입니다. - 프로젝트 스킬 폴더 — 특정 프로젝트 안의
.claude/skills/경로. 그 프로젝트에서만 작동합니다. - disableBundledSkills — 번들 스킬 전체를 끄는 설정 항목 이름입니다.
1단계 — 파일 위치가 올바른지 확인하기
스킬이 인식되지 않는 가장 흔한 원인은 SKILL.md 파일이 잘못된 위치에 있는 것입니다. Claude Code는 두 곳에서만 스킬을 자동으로 찾습니다.
- 개인 스킬 폴더 (모든 프로젝트에서 사용):
~/.claude/skills/스킬이름/SKILL.md - 프로젝트 스킬 폴더 (해당 프로젝트에서만 사용):
프로젝트루트/.claude/skills/스킬이름/SKILL.md
예를 들어 summarize-changes라는 스킬을 모든 프로젝트에서 쓰고 싶다면, 파일 경로는 반드시 아래와 같아야 합니다.
~/.claude/skills/summarize-changes/SKILL.md터미널에서 다음 명령어를 입력해 파일이 실제로 존재하는지 확인하세요.
ls ~/.claude/skills/summarize-changes/이렇게 보이면 성공: SKILL.md가 목록에 표시됩니다. 아무것도 보이지 않거나 "No such file or directory" 오류가 나오면, 경로가 잘못된 것입니다. 디렉터리를 새로 만들고 파일을 올바른 위치로 옮기세요.
mkdir -p ~/.claude/skills/summarize-changes
mv /잘못된경로/SKILL.md ~/.claude/skills/summarize-changes/SKILL.md참고로, 과거에 사용하던 .claude/commands/ 폴더에 파일을 둔 경우에도 계속 작동합니다. 공식 문서에 따르면 두 형식 모두 지원됩니다. 다만 새 스킬은 .claude/skills/ 아래에 두는 것이 권장되는 방식입니다.
2단계 — 파일 이름이 정확히 SKILL.md인지 확인하기
파일 이름은 대소문자까지 정확히 SKILL.md여야 합니다. skill.md, Skill.md, SKILLS.md처럼 조금이라도 다르면 Claude Code가 인식하지 못합니다.
터미널에서 아래 명령어로 실제 파일 이름을 확인하세요.
ls -1 ~/.claude/skills/summarize-changes/이렇게 보이면 성공: 목록에 SKILL.md가 정확히 이 대소문자로 표시됩니다. 이름이 다르다면 아래 명령어로 바꾸세요.
mv ~/.claude/skills/summarize-changes/skill.md \
~/.claude/skills/summarize-changes/SKILL.md⚠️ 주의: macOS는 기본적으로 파일 시스템이 대소문자를 구분하지 않는 경우가 많아, skill.md와 SKILL.md가 같아 보일 수 있습니다. 그러나 Claude Code 자체는 정확한 대소문자를 기준으로 파일을 읽으므로, 반드시 SKILL.md로 저장하세요.
3단계 — frontmatter 형식이 올바른지 확인하기
스킬 파일 맨 위에 frontmatter를 넣을 경우, 형식이 조금이라도 틀리면 스킬 전체가 무시될 수 있습니다. frontmatter는 선택 사항이지만, 쓴다면 아래처럼 ---로 정확하게 감싸야 합니다.
frontmatter를 쓰지 않아도 스킬은 작동합니다. 스킬 이름은 디렉터리 이름에서 자동으로 정해집니다. 예를 들어 ~/.claude/skills/summarize-changes/SKILL.md라면 명령어는 자동으로 /summarize-changes가 됩니다. frontmatter 작성이 복잡하게 느껴진다면, 처음에는 frontmatter 없이 본문만 작성해 보세요.
4단계 — Claude Code 버전 확인하기
공식 문서에 따르면 /run, /verify, /run-skill-generator 같은 번들 스킬은 Claude Code v2.1.145 이상이 필요합니다. 버전이 낮으면 해당 명령어가 보이지 않거나 작동하지 않습니다.
터미널에서 아래 명령어로 현재 버전을 확인하세요.
claude --version이렇게 보이면 성공: 2.1.145 이상의 숫자가 표시됩니다. 버전이 낮다면 아래 명령어로 업데이트하세요.
npm install -g @anthropic-ai/claude-code업데이트 후 터미널을 완전히 닫았다가 다시 열어야 새 버전이 적용됩니다.
5단계 — 번들 스킬이 꺼져 있는지 확인하기
/debug, /code-review, /run 같은 번들 스킬 — Claude Code가 기본으로 제공하는 스킬들 — 이 보이지 않을 때는, 설정에서 disableBundledSkills 항목이 켜져(활성화되어) 있을 수 있습니다. 이 항목이 활성화되면 번들 스킬 전체가 숨겨집니다.
설정 파일은 보통 ~/.claude/settings.json 또는 프로젝트 루트의 .claude/settings.json에 있습니다. 파일을 열어 아래 항목이 있는지 확인하세요.
"disableBundledSkills": true이 값이 true로 되어 있다면 false로 바꾸거나 해당 줄을 삭제하면 번들 스킬이 다시 나타납니다. 설정 파일을 수정한 뒤에는 세션을 재시작하세요.
자주 막히는 지점 & 해결
스킬 이름에 특수문자나 대문자를 쓴 경우
스킬 디렉터리 이름은 소문자 영문과 하이픈(-)만 사용하는 것이 안전합니다. SummarizeChanges나 summarize_changes처럼 대문자나 언더스코어(_)를 쓰면 명령어가 예상과 다르게 만들어지거나 인식되지 않을 수 있습니다. 디렉터리 이름은 summarize-changes처럼 소문자 하이픈 형식으로 짓는 것이 권장됩니다.
세션을 재시작하지 않은 경우
⚠️ 중요: 스킬 파일을 새로 만들거나 수정한 뒤에는 반드시 Claude Code 세션을 완전히 종료하고 다시 시작해야 변경 사항이 반영됩니다. 파일을 저장했더라도 현재 세션이 열려 있으면 이전 상태를 계속 사용합니다. 터미널에서 exit 또는 Ctrl+C로 세션을 끄고 다시 claude를 입력해 새 세션을 여세요.
추가 디렉터리에서 스킬을 불러오도록 설정한 경우
공식 문서에 따르면, 기본 두 위치 외의 경로에 있는 스킬은 설정을 통해 별도로 지정해야 합니다. 스킬 파일을 기본 폴더가 아닌 곳에 두었다면, 설정 파일에서 해당 경로를 추가로 등록했는지 확인하세요. 구체적인 설정 항목 이름은 사용 중인 Claude Code 버전의 공식 문서에서 확인하는 것이 가장 정확합니다.
SKILL.md 내용이 비어 있거나 설명이 너무 짧은 경우
스킬 파일 본문에 아무 내용도 없거나 한 줄짜리 짧은 설명만 있으면, Claude가 해당 스킬을 언제 써야 할지 판단하지 못해 자동 실행이 되지 않을 수 있습니다. 스킬이 어떤 상황에서 쓰이는지, 어떤 순서로 작업해야 하는지를 본문에 충분히 작성해 주세요.
점검 후에도 해결되지 않을 때
위 다섯 단계를 모두 확인했는데도 스킬이 작동하지 않는다면, 아래 방법을 시도해 보세요.
- 터미널을 완전히 닫고 새 창을 열어 Claude Code를 다시 시작합니다.
/help를 입력해 현재 세션에서 인식된 명령어 목록을 확인합니다. 내가 만든 스킬 이름이 보이는지 살펴보세요.- 스킬 파일을 가장 간단한 형태 — frontmatter 없이 본문 한 단락만 — 로 줄여서 다시 테스트해 보세요. 복잡한 설정보다 단순한 파일이 먼저 작동하는지 확인하는 것이 문제를 좁히는 데 도움이 됩니다.
- 개인 스킬 폴더(
~/.claude/skills/)에 테스트용 스킬을 하나 새로 만들어 인식되는지 확인합니다. 새 스킬이 인식된다면, 기존 스킬의 파일 내용이나 이름에 문제가 있는 것입니다.
성공 신호: /skill-name을 입력했을 때 Claude가 스킬에 적힌 지시 내용대로 응답하거나, 자동 실행 설정(invocation: auto)을 한 경우 관련 맥락에서 Claude가 먼저 스킬을 언급하고 실행하면 정상적으로 작동하는 것입니다.
다음 단계 — 스킬을 더 잘 활용하기
스킬이 정상적으로 인식된 뒤에는 다음 기능을 활용해 보세요.
- 지원 파일 추가: 스킬 디렉터리 안에 참고 파일(예: 체크리스트
checklist.md)을 함께 두면, SKILL.md에서 해당 파일을 불러와 쓸 수 있습니다. - 번들 스킬 활용: 직접 만들지 않아도
/debug,/code-review,/run같은 번들 스킬이 기본으로 제공됩니다. 먼저 이 스킬들을 써보고, 필요한 부분을 맞춤 스킬로 보완하는 방법을 권장합니다. - 프로젝트 전용 스킬: 특정 프로젝트에만 적용할 절차가 있다면, 개인 폴더가 아닌 프로젝트 루트의
.claude/skills/아래에 스킬을 만들어 두세요.