분명히 스킬을 설치했는데 클로드 코드(Claude Code) 안에서 호출이 되지 않는 경험, 한 번쯤 겪으셨을 겁니다. 슬래시 명령에도 안 뜨고, 자동 트리거도 안 잡히고, 도대체 어디에 깔린 건지 헷갈리실 때가 있습니다. 원인은 의외로 단순한 경우가 많습니다. 설치 위치를 잘못 잡았거나, 위치는 맞지만 클로드가 인식할 수 있는 형태가 아닌 경우가 대부분입니다. 사용자 레벨과 프로젝트 레벨의 차이부터 짚고, 안 보일 때 순서대로 확인할 체크리스트까지 정리해 드립니다.
목차
먼저 알아둘 것: 스킬 설치 위치는 두 가지
클로드 코드의 스킬은 어디에 두느냐에 따라 적용 범위가 달라집니다. 어떤 작업에서든 항상 켜고 싶은 스킬과, 특정 프로젝트에서만 쓰고 싶은 스킬을 구분해서 두는 것이 핵심입니다.
| 구분 | 사용자 레벨 | 프로젝트 레벨 |
|---|---|---|
| 경로 | ~/.claude/skills/ | .claude/skills/ (프로젝트 루트) |
| 적용 범위 | 모든 프로젝트 | 해당 저장소만 |
| 버전 관리 | 본인 머신에만 존재 | Git에 커밋해 팀과 공유 |
| 권장 용도 | 개인 단축 명령, 공통 자동화 | 프로젝트 전용 워크플로우 |
| 우선순위 | 프로젝트보다 우선 | 사용자보다 낮음 |
같은 이름의 스킬이 두 위치에 모두 있으면 일반적으로 사용자 레벨이 우선합니다. 그래서 “예전에 만들어 둔 사용자 스킬이 새로 추가한 프로젝트 스킬을 가려서 안 보이는 것처럼” 보이는 일이 종종 생깁니다.
스킬이 안 보일 때 1순위로 확인할 것: 폴더와 파일명
가장 자주 놓치는 부분입니다. 클로드 코드는 스킬을 인식할 때 다음 두 가지를 엄격히 봅니다.
- 경로:
~/.claude/skills/스킬이름/또는./.claude/skills/스킬이름/형태여야 합니다..claude앞의 점,skills폴더 이름이 모두 정확해야 합니다. - 파일명: 폴더 안의 지침 파일은 반드시
SKILL.md입니다. 대소문자를 구분하므로skill.md나Skill.md로 두면 인식되지 않습니다.
폴더 구조가 한 단계 어긋나도 인식이 안 됩니다. 예를 들어 ~/.claude/skills/SKILL.md처럼 폴더 없이 바로 파일을 두면 동작하지 않습니다. 반드시 ~/.claude/skills/내스킬/SKILL.md 형태여야 합니다.
2순위 확인: SKILL.md 안의 frontmatter
파일 위치가 맞는데도 안 보인다면, SKILL.md 상단의 YAML frontmatter를 확인하실 차례입니다. 다음과 같은 형태가 기본입니다.
--- name: my-skill description: 한 줄로 짧고 명확한 설명 ---
이때 자주 발생하는 실수가 있습니다.
- description이 여러 줄로 나뉜 경우: Prettier 같은 포매터가 자동으로 줄을 나눠 버리면 클로드가 description을 끝까지 읽지 못합니다. description은 한 줄로 작성하시고, 포매터가 손대지 못하게
# prettier-ignore주석을 위에 두시는 것이 안전합니다. - name이 누락되거나 폴더명과 다른 경우: name 필드는 반드시 들어가야 하며, 보통 폴더명과 동일하게 맞추는 것이 혼란이 적습니다.
- disable-model-invocation: true가 들어 있는 경우: 이 설정이 켜져 있으면 클로드가 자동으로는 절대 호출하지 않습니다. 사용자가 슬래시 명령으로 직접 부르는 것만 가능합니다. 자동 트리거가 안 잡힌다면 이 항목이 들어 있는지 먼저 보십시오.
3순위 확인: description이 모호한 경우
frontmatter 형식이 맞아도 description이 모호하면 클로드가 “이 요청에 이 스킬을 써야 하나?”를 판단하지 못합니다. 자동 트리거를 잘 받으려면 description에 다음 요소를 넣으시는 것이 효과적입니다.
- 언제 켜야 하는지 명시: “사용자가 ○○에 대해 물을 때 항상 이 스킬을 호출합니다” 같은 능동형 문장
- 부정 제약: “직접 △△하지 말고 먼저 이 스킬을 사용합니다” 같은 금지 조건
- 구체적 키워드: 트리거가 될 만한 단어나 패턴 직접 나열
“코드 리뷰 도와주는 스킬” 같은 모호한 설명보다는, “사용자가 PR이나 diff에 대해 리뷰를 요청할 때 호출되며, 일반 답변 대신 반드시 이 스킬의 절차를 따른다” 같은 식이 훨씬 잘 잡힙니다.
4순위 확인: 세션 재시작이 필요한 변경
같은 폴더 안에서 SKILL.md 내용을 수정하는 경우는 즉시 반영됩니다. 그러나 다음과 같은 변경은 클로드 코드 세션을 다시 시작해야 인식됩니다.
- 처음
~/.claude/skills/를 만들고 첫 스킬을 추가한 경우 - 스킬 폴더 자체를 새로 추가하거나 이름을 바꾼 경우
- 플러그인을 새로 설치한 직후
“분명 깔았는데 안 떠”라는 상황의 절반은 세션 재시작으로 해결됩니다. 터미널에서 클로드 코드를 완전히 종료(Ctrl+C 또는 /exit)했다가 다시 claude 명령으로 띄워 보십시오.
5순위 확인: 너무 많은 스킬·플러그인
스킬이 일정 개수를 넘으면 클로드의 시스템 프롬프트 토큰 한도에 부딪혀 일부가 인식되지 않을 수 있습니다. 슬래시 명령 설명까지 모두 합산되기 때문에, 잘 안 쓰는 스킬은 정리하시는 것이 좋습니다. 그래도 부족하면 환경 변수 SLASH_COMMAND_TOOL_CHAR_BUDGET을 늘려 헤드룸을 확보할 수 있습니다.
설치 직후 동작 확인 루틴
스킬을 새로 추가하셨다면 다음 순서로 한 번에 점검하시는 것을 권해 드립니다.
- 1. 폴더 경로와
SKILL.md대소문자 확인 - 2. SKILL.md 상단
name,description필드 존재 여부 확인 - 3. description이 한 줄인지,
disable-model-invocation이 false 또는 미설정인지 확인 - 4. 클로드 코드 세션을 완전히 재시작
- 5. 클로드에게 “사용 가능한 스킬을 나열해 줘”라고 직접 물어 인식 여부 확인
- 6. 트리거가 될 만한 키워드를 포함한 요청을 보내 자동 호출되는지 테스트
여기까지 했는데도 안 잡힌다면 claude --debug로 다시 띄워서 어떤 스킬이 로드되고 있는지 직접 확인하십시오. 디버그 로그는 ~/.claude/debug/에 남기 때문에 추후 분석도 가능합니다.
사용자 vs 프로젝트, 어디에 두는 게 좋을까
일반적인 기준은 다음과 같습니다.
- 본인만 쓰는 단축 명령, 모든 프로젝트에서 자주 쓰는 자동화 → 사용자 레벨(
~/.claude/skills/) - 해당 저장소의 코드 컨벤션·배포 절차·테스트 시나리오 → 프로젝트 레벨(
./.claude/skills/) - 팀과 같은 동작을 보장해야 하는 모든 것 → 프로젝트 레벨에 두고 Git 커밋
- 회사 공통 도구지만 사내에 머물러야 하는 것 → 사내 Git에 별도 스킬 저장소를 두고 각 프로젝트의
.claude/skills/에 서브모듈로 연결
한 번 정해 두면 신규 합류자가 같은 환경을 그대로 받을 수 있으므로, 팀 공유가 필요한 스킬은 가능하면 프로젝트 레벨에 두시는 편이 운영하기 쉽습니다.
자주 묻는 질문
슬래시 명령으로는 부를 수 있는데 자동 트리거만 안 됩니다.
거의 확실히 description 문제이거나 disable-model-invocation: true 설정 때문입니다. description을 트리거 조건이 명확한 능동형 문장으로 다시 작성하시고, frontmatter에서 해당 옵션이 있는지 확인하십시오.
같은 스킬이 두 위치에 있는데 한쪽만 동작합니다.
우선순위 규칙상 사용자 레벨이 프로젝트 레벨보다 먼저 적용됩니다. 의도와 다르다면 한쪽을 삭제하거나 이름을 다르게 두시는 편이 안전합니다.
플러그인으로 깐 스킬은 어디에 있나요?
플러그인은 별도 캐시 경로에 저장되며 직접 손대지 않으셔도 됩니다. 안 보이면 /plugin list --installed로 활성 상태를 먼저 확인하시고, 비활성이면 다시 활성화하시거나 /plugin install로 재설치하시면 됩니다.
맥과 윈도우에서 경로가 다른가요?
홈 디렉터리(~)의 실제 경로만 다를 뿐 구조는 동일합니다. 윈도우에서는 보통 C:\Users\사용자명\.claude\skills\가 됩니다. 환경에 상관없이 폴더와 파일명 규칙은 같습니다.
정리
스킬이 안 보일 때 점검 순서는 단순합니다. 폴더 경로와 SKILL.md 대소문자 → frontmatter의 name·description → description의 명확성 → 세션 재시작 → 슬롯 한도 순으로 확인하시면 대부분 해결됩니다. 설치 위치는 본인만 쓸 것은 사용자 레벨, 팀과 공유할 것은 프로젝트 레벨로 구분해 두시는 것이 가장 깔끔합니다. 한 번 규칙만 잡아 두시면 새 스킬을 추가할 때마다 헤매지 않게 됩니다.