Skills 문제 해결

Skills 문제 해결

핵심 요약

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

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

Skills Validator 사용하기

가장 먼저 시도해 볼 것은 claude plugin validate 명령입니다. 셸에서 개인 skill의 경우 claude plugin validate ~/.claude/skills를, 프로젝트 skill의 경우 claude plugin validate .claude/skills를 실행하세요. 이 명령은 Claude Code v2.1.233 이상이 필요합니다.

validator는 frontmatter가 파싱되지 않는 SKILL.md 파일을 찾아내므로, 다른 문제를 디버깅하는 데 시간을 쓰기 전에 해당 문제를 파악할 수 있습니다. 위 영상에서는 uv로 설치하는 별도의 verifier를 보여줍니다.

Skill이 트리거되지 않는 경우

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

Claude는 의미 기반 매칭(semantic matching)을 사용하므로, 요청이 설명의 의미와 겹쳐야 합니다. 겹치는 부분이 충분하지 않으면 매칭되지 않습니다. 다음과 같이 해보세요:

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

Skill이 로드되지 않는 경우

Claude에게 "사용 가능한 skill이 무엇인지" 물었을 때 skill이 나타나지 않는다면, 다음 구조적 요구 사항을 확인하세요:

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

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

잘못된 Skill이 사용되는 경우

Claude가 잘못된 skill을 사용하거나 skill들 사이에서 혼동하는 것처럼 보인다면, 설명이 너무 비슷할 가능성이 큽니다. 설명을 구별되게 만드세요. 최대한 구체적으로 작성하면 Claude가 언제 해당 skill을 사용할지 판단하는 데 도움이 될 뿐만 아니라, 이름이 비슷한 다른 skill과의 충돌도 방지할 수 있습니다.

Skill 우선순위 충돌

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



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

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

Plugin Skill이 나타나지 않는 경우

플러그인을 설치했는데 해당 skill이 보이지 않나요? /plugin을 실행하여 Installed 아래에 플러그인이 나열되어 있고 활성화되어 있는지 확인한 다음, Errors 탭을 확인하세요. 이번 세션 중에 설치했다면 /reload-plugins를 실행하세요.

그 후에도 skill이 나타나지 않는다면, 플러그인 구조가 잘못되었을 수 있습니다. Skill은 .claude-plugin/ 내부가 아니라 플러그인 루트의 skills/ 디렉터리에서 로드됩니다. 셸에서 플러그인 디렉터리에 대해 claude plugin validate를 실행하여 매니페스트와 각 skill의 frontmatter를 확인하세요.

런타임 오류

skill이 로드되지만 실행 중에 실패합니다. 흔한 원인 몇 가지는 다음과 같습니다:

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

빠른 문제 해결 체크리스트

• 트리거되지 않나요? 설명을 개선하고 트리거 문구를 추가하세요.
• 로드되지 않나요? 경로, 파일 이름, YAML 구문을 확인하세요.
• 잘못된 skill이 사용되나요? 설명을 서로 더 구별되게 만드세요.
• 가려지고 있나요? 우선순위 계층 구조를 확인하고 필요하면 이름을 변경하세요.
• Plugin skill이 보이지 않나요? /plugin에서 오류를 확인한 다음 /reload-plugins를 실행하세요.
• 런타임 실패인가요? 종속성, 권한, 경로를 확인하세요.

레슨 되돌아보기

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

코스 마무리

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