스킬 문제 해결

스킬 문제 해결 · 4 min

스킬이 예상대로 작동하지 않을 때, 문제는 보통 몇 가지 예측 가능한 범주에 속합니다. 이 영상은 트리거되지 않는 스킬부터 우선순위 충돌, 런타임 실패까지 각 범주를 살펴보고, 체계적인 문제 해결 접근 방식을 제공합니다. 또한 스킬 검증기 도구와 로딩 문제를 진단하기 위해 claude --debug를 사용하는 방법도 배우게 됩니다.

한국어 대본

00:00스킬이 작동하지 않을 때 문제는 대개 몇 가지 범주 중 하나에 해당합니다.
00:08스킬이 트리거되지 않거나, 로드되지 않거나, 충돌이 발생하거나, 런타임에 실패하는 경우입니다.
00:14하지만 좋은 소식이 있습니다! 대부분의 수정은 꽤 간단합니다. 몇 가지를 살펴보겠습니다.
00:20먼저 Agent Skills Verifier 명령을 실행해 볼 수 있습니다.
00:25운영 체제에 따라 설치 단계는 달라지지만,
00:30UV를 사용하는 것이 가장 빠르고 쉽게 설치할 수 있어 권장됩니다.
00:35설치가 끝나면 스킬 디렉터리로 이동하거나 어디서든 이 명령을 실행하세요.
00:41스킬은 존재하고 validator도 통과했지만, 예상할 때 Claude가 사용하지 않는 경우입니다.
00:47음, 원인은 거의 항상 설명입니다.
00:52Claude는 시맨틱 매칭을 사용하므로 요청이 설명의 의미와 겹쳐야 합니다.
00:57겹치는 부분이 충분하지 않으면 매칭되지 않습니다.
01:01요청을 표현하는 방식과 설명을 비교해 보세요.
01:04사용자가 실제로 말할 법한 트리거 문구를 추가하세요.
01:07표현을 바꿔 테스트하세요.
01:09이 프로파일링을 도와주세요.
01:10왜 이렇게 느립니까?
01:12더 빠르게 만들어 주세요.
01:12이 중 어느 문구라도 트리거되지 않으면 해당 키워드를 설명에 추가하세요.
01:15Claude에게 사용 가능한 스킬을 물었을 때 스킬이 나타나지 않는다면 다음 항목을 확인하세요.
01:23스킬은 올바른 구조로 올바른 위치에 있어야 합니다.
01:25`skill.md` 파일은 스킬 루트가 아니라 이름으로 된 디렉터리 안에 있어야 합니다.
01:30파일 이름은 정확히 `skill.md`여야 하며, skill 부분은 대문자, md는 소문자여야 합니다.
01:37여기서는 목록에서 하나씩 지워 나가는 중입니다. 이해했습니까? 하나씩 지웁니다.
01:40`claude --debug`를 실행해 로딩 오류를 확인하세요.
01:43스킬 이름이 언급된 메시지를 찾으세요.
01:46때로는 이것만으로 문제가 해결됩니다.
01:50Claude가 잘못된 스킬을 사용하거나 혼란스러워한다면,
01:53설명이 서로 너무 비슷할 가능성이 높습니다.
01:57서로 구별되도록 만드세요.
01:58최대한 구체적으로 작성하면 Claude가 스킬을 사용할 시점을 결정하는 데 도움이 될 뿐 아니라,
02:03이름이나 표현이 비슷한 다른 스킬과 충돌하는 것도 막을 수 있다는 점을 기억하세요.
02:07개인 스킬이 무시된다면,
02:09엔터프라이즈 스킬이나 우선순위가 더 높은 스킬에 같은 이름이 있을 수 있습니다.
02:13그러니 이를 조사해 보세요.
02:16엔터프라이즈 코드 리뷰가 보이는데 개인 코드 리뷰도 있다면,
02:20엔터프라이즈 스킬이 매번 우선됩니다.
02:23따라서 조금 더 구별되는 이름으로 스킬 이름을 바꾸면 됩니다.
02:28엔터프라이즈 스킬에 대해서는 관리자에게 문의하세요.
02:30하지만 아마 첫 번째 방법이 더 효과적일 가능성이 큽니다.
02:35플러그인을 설치했는데 스킬이 보이지 않습니까?
02:38캐시를 삭제하세요.
02:39Claude Code를 재시작한 뒤 다시 설치하세요.
02:41그래도 스킬이 나타나지 않는다면 플러그인 구조가 잘못되었을 수 있습니다.
02:46이럴 때 validator 도구를 사용하면 됩니다.
02:49스킬은 로드되지만 실행 중에 실패하는 경우입니다.
02:52스킬이 외부 패키지를 사용한다면 해당 패키지가 설치되어 있어야 합니다.
02:55이 정보를 설명에 추가하세요.
02:58스크립트에는 실행 권한이 필요합니다.
03:00Windows에서도 어디서나 슬래시(`/`)를 사용하세요.
03:06간단한 점검표를 살펴보겠습니다.
03:08트리거되지 않습니까? 설명과 트리거 문구를 개선하세요.
03:12로드되지 않습니까? 경로, 파일 이름, YAML 구문을 확인하세요.
03:16잘못된 스킬이 사용됩니까? 설명을 조금 더 구별되게 만드세요.
03:19다른 스킬에 가려지고 있습니까? 우선순위를 확인하고 필요하면 이름을 바꾸세요.
03:24플러그인이 보이지 않습니까? 캐시를 삭제하고 다시 설치하세요.
03:27런타임에 실패합니까? 종속성, 권한, 검사 결과를 확인하세요.

Watch on YouTube

핵심 요점

스킬 검증기 도구부터 시작하세요 — 다른 문제를 디버깅하는 데 시간을 쓰기 전에 구조적 문제를 포착해 줍니다
스킬이 트리거되지 않는다면, 원인은 거의 항상 설명(description)에 있습니다 — 실제로 요청을 표현하는 방식과 일치하는 트리거 문구를 추가하세요
스킬이 로드되지 않는다면, SKILL.md가 스킬 루트가 아닌 이름이 지정된 디렉터리 안에 있는지, 파일 이름이 정확히 SKILL.md인지 확인하세요
잘못된 스킬이 사용된다면, 설명이 너무 유사한 것입니다 — 더 구별되게 만드세요
런타임 오류의 경우, 종속성, 파일 권한(chmod +x), 경로 구분자(어디서나 슬래시 사용)를 확인하세요

스킬이 작동하지 않을 때, 문제는 보통 몇 가지 범주 중 하나에 속합니다: 스킬이 트리거되지 않거나, 로드되지 않거나, 충돌이 있거나, 런타임에 실패하는 경우입니다. 좋은 소식은 대부분의 해결책이 꽤 간단하다는 것입니다.

스킬 검증기 사용하기

가장 먼저 시도해 볼 것은 agent skills verifier 명령입니다. 설치 단계는 운영 체제에 따라 다르지만, uv를 사용하는 것이 가장 빠르게 설정하는 가장 쉬운 방법입니다.

설치가 완료되면, 스킬 디렉터리로 이동하거나 어디서든 명령을 실행할 수 있습니다. 검증기는 다른 문제를 디버깅하는 데 시간을 쓰기 전에 구조적 문제를 포착해 줍니다.

스킬이 트리거되지 않는 경우

스킬이 존재하고 검증을 통과했지만, 예상할 때 Claude가 이를 사용하지 않습니다. 원인은 거의 항상 설명(description)에 있습니다.

Claude는 의미론적 매칭을 사용하므로, 요청이 설명의 의미와 겹쳐야 합니다. 충분히 겹치지 않으면 매칭되지 않습니다. 다음을 시도해 보세요:

실제로 요청을 표현하는 방식과 설명을 비교해 보세요
사용자가 실제로 말할 만한 트리거 문구를 추가하세요
"이것을 프로파일링해 줘", "왜 이게 느려?", "이걸 더 빠르게 만들어 줘" 같은 변형으로 테스트해 보세요
어떤 변형이 트리거되지 않으면, 해당 키워드를 설명에 추가하세요

스킬이 로드되지 않는 경우

Claude에게 "사용 가능한 스킬이 뭐야"라고 물었을 때 스킬이 나타나지 않는다면, 다음 구조적 요구 사항을 확인하세요:

SKILL.md 파일은 스킬 루트가 아닌 이름이 지정된 디렉터리 안에 있어야 합니다
파일 이름은 정확히 SKILL.md여야 합니다 — "SKILL"은 모두 대문자, "md"는 소문자입니다

claude --debug를 실행하여 로딩 오류를 확인하세요. 스킬 이름이 언급된 메시지를 찾아보세요. 때로는 이것만으로도 문제를 바로 찾을 수 있습니다.

잘못된 스킬이 사용되는 경우

Claude가 잘못된 스킬을 사용하거나 스킬 간에 혼동하는 것처럼 보인다면, 설명이 너무 유사할 가능성이 높습니다. 설명을 구별되게 만드세요. 가능한 한 구체적으로 작성하는 것은 Claude가 스킬을 언제 사용할지 결정하는 데 도움이 될 뿐만 아니라, 비슷하게 들리는 다른 스킬과의 충돌도 방지합니다.

스킬 우선순위 충돌

개인 스킬이 무시되고 있다면, 엔터프라이즈 또는 더 높은 우선순위의 스킬이 같은 이름을 가지고 있을 수 있습니다.

스킬 우선순위 계층 구조 — 엔터프라이즈가 개인, 프로젝트, 플러그인 위에 강조 표시됨 — managed-settings.json 파일 이름과 함께

예를 들어, 엔터프라이즈 "code-review" 스킬이 있고 개인 "code-review" 스킬도 있다면, 엔터프라이즈 스킬이 항상 우선합니다. 선택할 수 있는 옵션은 다음과 같습니다:

스킬 이름을 더 구별되는 것으로 변경하기 (보통 더 쉬운 방법입니다)
엔터프라이즈 스킬에 대해 관리자와 상담하기

플러그인 스킬이 나타나지 않는 경우

플러그인을 설치했지만 해당 스킬이 보이지 않나요? 캐시를 지우고, Claude Code를 재시작한 다음, 다시 설치하세요.

그 후에도 스킬이 여전히 나타나지 않는다면, 플러그인 구조가 잘못되었을 수 있습니다. 이때 검증기 도구가 제 역할을 제대로 해냅니다.

런타임 오류

스킬이 로드되지만 실행 중에 실패합니다. 몇 가지 일반적인 원인은 다음과 같습니다:

누락된 종속성: 스킬이 외부 패키지를 사용한다면, 해당 패키지가 설치되어 있어야 합니다. Claude가 필요한 것을 알 수 있도록 스킬 설명에 종속성 정보를 추가하세요.
권한 문제: 스크립트에는 실행 권한이 필요합니다. 스킬이 참조하는 모든 스크립트에 chmod +x를 실행하세요.
경로 구분자: Windows에서도 어디서나 슬래시를 사용하세요.

빠른 문제 해결 체크리스트

트리거되지 않나요? 설명을 개선하고 트리거 문구를 추가하세요.
로드되지 않나요? 경로, 파일 이름, YAML 문법을 확인하세요.
잘못된 스킬이 사용되나요? 설명을 서로 더 구별되게 만드세요.
가려지고 있나요? 우선순위 계층 구조를 확인하고 필요하면 이름을 변경하세요.
플러그인 스킬이 누락되었나요? 캐시를 지우고 다시 설치하세요.
런타임 실패인가요? 종속성, 권한, 경로를 확인하세요.

레슨 되돌아보기

본인의 작업에서 이러한 문제 해결 시나리오를 경험한 적이 있나요? 어떤 해결책이 가장 많은 시간을 절약해 주었을까요?
팀과 스킬을 공유하기 전에 스킬을 검증하는 프로세스를 어떻게 설정하시겠습니까?

코스 마무리

Introduction to Agent Skills를 완료하신 것을 축하합니다! Claude Code에서 스킬을 만들고, 구성하고, 공유하고, 문제를 해결하는 방법을 배우셨습니다. 자신의 워크플로우를 위한 스킬을 만들기 시작할 때, 가장 좋은 스킬은 실제 불편한 지점에서 나온다는 것을 기억하세요 — 가장 자주 반복하게 되는 지시사항부터 시작해 보세요.