🔧 Claude Code Skills — 트러블슈팅 가이드(Troubleshooting skills)

🔧 Claude Code Skills — 트러블슈팅 완전 가이드

스킬이 작동하지 않을 때 단계별 진단과 해결법

📌 이 글의 핵심 요약

• 먼저 Skills Validator로 구조 문제를 확인하고, 그다음 세부 디버깅을 진행하세요.
• 스킬이 트리거되지 않는 원인은 거의 항상 description에 있습니다.
• SKILL.md는 반드시 named 디렉토리 안에 있어야 하고, 파일명은 정확히 SKILL.md여야 합니다.
• 잘못된 스킬이 실행된다면 description을 더 구체적으로 작성하세요.
• 런타임 오류는 의존성 설치, 실행 권한(chmod +x), 경로 구분자(슬래시)를 확인하세요.

스킬이 기대대로 동작하지 않을 때, 문제는 대부분 몇 가지 예측 가능한 카테고리에 해당됩니다. 원인을 알면 대부분의 수정은 간단합니다.

🔕

트리거 안 됨

스킬이 있는데 Claude가 사용하지 않음

🚫

로드 안 됨

스킬 목록에 아예 표시되지 않음

🔀

엉뚱한 스킬 실행

다른 스킬이 대신 활성화됨

⚔️

우선순위 충돌

내 스킬이 무시되고 다른 스킬이 실행됨

🔌

플러그인 스킬 없음

설치했는데 스킬이 보이지 않음

💥

런타임 오류

로드는 됐지만 실행 중 실패

---

STEP 0. 먼저 Skills Validator 실행하기

어떤 문제든 가장 먼저 Skills Validator를 실행하세요. 구조적 문제를 자동으로 감지해줘서, 불필요한 디버깅 시간을 크게 줄일 수 있습니다.

Terminal

# uv로 설치 (OS에 따라 설치 방법이 다를 수 있음)
uvx agent-skills-verifier

# 스킬 디렉토리에서 실행하거나 경로 지정
uvx agent-skills-verifier ~/.claude/skills/pr-review

Validator가 통과됐는데도 문제가 있다면, 아래 항목들을 순서대로 확인하세요.

---

1. 🔕 스킬이 트리거되지 않을 때

스킬이 존재하고 유효성 검사도 통과했는데 Claude가 사용하지 않는다면, 원인은 거의 항상 description입니다. Claude는 의미 기반(Semantic Matching)으로 매칭하기 때문에, 요청과 description 사이의 의미 중첩이 충분해야 합니다.

🔕 스킬이 트리거되지 않음

원인

description이 실제 사용 표현과 의미적으로 겹치지 않음

해결

• 내가 실제로 Claude에게 입력하는 표현을 description에 추가
• "help me profile this", "why is this slow?", "make this faster" 등 다양한 표현으로 테스트
• 트리거되지 않는 표현이 있다면 해당 키워드를 description에 포함

description 개선 전후 비교

# ❌ 트리거가 잘 안 되는 description
description: Analyzes code performance.

# ✅ 트리거가 잘 되는 description — 실제 표현 다수 포함
description: Analyzes code performance and finds bottlenecks.
             Use when profiling code, investigating slow behavior,
             optimizing functions, or when asked "why is this slow",
             "help me profile", or "make this faster".

---

2. 🚫 스킬이 로드되지 않을 때

"what skills are available"라고 물어봤을 때 스킬이 목록에 없다면 구조 문제입니다. 두 가지를 반드시 확인하세요.

❌ 잘못된 구조

~/.claude/skills/
└── SKILL.md ← 루트에 직접!
└── skill.md ← 소문자 오류!

✅ 올바른 구조

~/.claude/skills/
└── pr-review/ ← named 디렉토리
    └── SKILL.md ← 정확한 파일명

🚫 스킬이 로드되지 않음

체크 1

SKILL.md가 named 디렉토리 안에 있는지 확인. skills 루트에 파일이 바로 있으면 인식하지 못합니다.

체크 2

파일명이 정확히 SKILL.md인지 확인. SKILL은 대문자, md는 소문자여야 합니다.

명령어

claude --debug 실행 후 스킬 이름이 포함된 에러 메시지를 찾으면 원인이 바로 보입니다.

Terminal — 디버그 모드 실행

# 디버그 모드로 실행해서 로딩 오류 확인
claude --debug

# 출력 중 스킬 이름이 포함된 라인을 찾기
claude --debug 2>&1 | grep -i "pr-review"

---

3. 🔀 엉뚱한 스킬이 실행될 때

🔀 잘못된 스킬이 활성화됨

원인

여러 스킬의 description이 너무 비슷해서 Claude가 혼동함

해결

각 스킬의 description을 더 구체적이고 명확하게 구분되게 수정합니다.
예: review ❌ → frontend-code-review / backend-code-review ✅

description이 구체적일수록 트리거 정확도가 높아지는 것은 물론, 다른 스킬과의 충돌도 예방됩니다. 특이성이 곧 신뢰성입니다.

---

4. ⚔️ 우선순위 충돌 — 내 스킬이 무시될 때

개인 스킬이 계속 무시된다면, 같은 이름의 더 높은 우선순위 스킬이 있을 가능성이 높습니다.

Enterprise 조직 관리자가 배포한 code-review 스킬 ✓ 적용됨

Personal 내가 만든 code-review 스킬 — 같은 이름으로 충돌 ✗ 무시됨

Project 저장소의 프로젝트 스킬 ✗ 무시됨

Plugins 설치된 플러그인 스킬 ✗ 무시됨

⚔️ 우선순위 충돌

원인

Enterprise 또는 더 높은 우선순위의 스킬이 같은 name을 사용 중

해결 1

내 스킬 이름을 더 구체적으로 변경 (가장 빠른 방법)
예: code-review → frontend-ts-review

해결 2

관리자에게 Enterprise 스킬 확인 후 조율 요청

---

5. 🔌 플러그인 스킬이 보이지 않을 때

🔌 설치한 플러그인 스킬이 표시되지 않음

1단계

캐시 초기화 → Claude Code 재시작 → 플러그인 재설치

2단계

여전히 안 보이면 플러그인 내부 파일 구조 문제일 수 있습니다. Skills Validator로 플러그인 구조를 검사하세요.

---

6. 💥 런타임 오류 — 로드는 됐지만 실행 실패

스킬이 목록에 나타나고 트리거도 됐지만 실행 중 오류가 발생하는 경우입니다. 원인은 세 가지 중 하나일 가능성이 높습니다.

💥 런타임 오류 3대 원인

의존성

스킬이 사용하는 외부 패키지가 설치되지 않은 경우.
해결: 필요한 패키지를 먼저 설치하고, SKILL.md description에 필수 의존성을 명시하세요.

실행 권한

스크립트에 실행 권한이 없는 경우.
해결: chmod +x scripts/your-script.sh로 권한을 부여하세요.

경로 구분자

Windows에서 백슬래시(\)를 사용한 경우.
해결: Windows 포함 모든 환경에서 슬래시(/)만 사용하세요.

런타임 오류 체크 명령어

# 스크립트 실행 권한 부여
chmod +x .claude/skills/my-skill/scripts/validate.sh

# ❌ Windows 경로 (사용 금지)
scripts\validate.sh

# ✅ 올바른 경로 (모든 OS에서 사용)
scripts/validate.sh

---

7. ⚡ 빠른 트러블슈팅 체크리스트

🔕 트리거 안 됨

• description에 실제 사용 표현의 키워드 추가
• 다양한 표현으로 테스트 후 안 되는 것만 추가

🚫 로드 안 됨

• named 디렉토리 안에 SKILL.md 있는지 확인
• 파일명 대소문자 확인 (SKILL.md)
• claude --debug로 에러 메시지 확인

🔀 엉뚱한 스킬

• description을 더 구체적이고 명확하게 수정
• 스킬 이름을 더 특이하게 변경

⚔️ 우선순위 충돌

• 스킬 이름을 더 구체적으로 변경 (빠른 해결)
• 관리자에게 Enterprise 스킬 확인 요청

🔌 플러그인 없음

• 캐시 초기화 → 재시작 → 플러그인 재설치
• Validator로 플러그인 구조 검사

💥 런타임 오류

• 외부 패키지 설치 여부 확인
• chmod +x로 스크립트 실행 권한 부여
• 경로 구분자를 슬래시(/)로 통일

문제 해결 순서: Validator 실행 → 구조 확인 → description 개선 → 우선순위 확인 → 런타임 점검. 이 순서대로 진행하면 대부분의 문제를 빠르게 찾을 수 있습니다.

트러블슈팅 핵심 원칙 ✨

스킬 문제의 90%는 description 또는 파일 구조에서 발생합니다.
Validator 먼저, 디버깅은 그다음.

체계적인 접근이 가장 빠른 해결책입니다 🚀