클로드 스킬이 불리지 않을 때는 설명 문장보다 앞에서 확인할 것이 있습니다. 순서는 이렇습니다. 먼저 /스킬이름으로 직접 불러 봅니다. 그게 되면 파일 위치와 첫 줄은 정상이고 문제는 설명 문장입니다. 그게 안 되면 SKILL.md의 첫 줄이 ---인지, 폴더 이름과 경로가 맞는지부터 봅니다. 이 글은 공식 문서의 문제 해결 항목을 이 순서로 다시 배열하고, 제 컴퓨터에 있는 스킬 28개의 설명 문장을 직접 재 본 숫자를 붙였습니다.
바로 앞 글 클로드 코드 스킬 만들기, 반복하는 작업을 한 번에 부르는 순서에서 만드는 법을 다뤘고, 이 글은 그다음 단계인 "만들었는데 안 불린다"만 다룹니다.
먼저 어디서 막혔는지 가르는 질문 하나
스킬이 안 불린다는 말에는 서로 다른 세 상황이 섞여 있습니다.
| 상황 | 이 경우 의미 | 먼저 볼 곳 |
|---|---|---|
/스킬이름을 쳐도 목록에 없다 | 스킬이 아예 읽히지 않음 | 위치, 첫 줄, 이름 |
/스킬이름은 되는데 말로 시키면 안 불린다 | 설명이 요청과 안 맞거나 설명이 잘림 | 설명 문장, 설명 한도 |
| 어제는 불렸는데 오늘은 안 불린다 | 설명이 밀려났거나 경로 조건이 안 맞음 | 목록 예산, paths |
세 번째는 특히 놓치기 쉽습니다. 스킬 파일은 그대로인데 그사이 스킬을 몇 개 더 만들었거나 작업 폴더를 옮겼다면 원인은 스킬 자체가 아니라 주변에 있기 때문입니다. 그래서 고치기 전에 이 표로 어느 칸인지부터 가르는 것이 시간을 줄입니다.
공식 문서도 같은 흐름으로 안내합니다. 설명에 사용자가 자연스럽게 하는 말이 들어 있는지 보고, 스킬이 사용 가능 목록에 나오는지 확인하고, 요청을 설명에 더 가깝게 바꿔 보고, 마지막으로 /스킬이름으로 직접 불러 보라는 순서입니다. 직접 불러도 안 되면 이름이 거부된 것은 아닌지 보라고 합니다.
1단계. 파일 첫 줄이 ---인가
가장 흔하고 가장 허무한 원인입니다. 클로드 코드는 파일의 첫 줄이 ---일 때만 맨 위 설정 부분을 읽습니다. 앞에 빈 줄이나 주석이 한 줄 끼어 있으면 설정 전체가 본문으로 처리됩니다.
더 헷갈리는 경우가 설정 문법이 깨진 때입니다. 공식 문서는 이 경우 스킬 본문은 읽히되 설정 값은 비어 있는 상태로 올라온다고 설명합니다. 그래서 /스킬이름으로 부르면 되는데, 클로드가 설명을 보고 고르는 단계에서는 맞출 근거가 없어 영영 안 불립니다. "수동으로는 되는데 자동으로는 안 된다"는 증상의 한 원인입니다.
설명 안에 콜론이나 따옴표 같은 기호가 섞이면 깨지기 쉬우니, 설명을 큰따옴표로 감싸거나 한 줄로 단순하게 쓰는 편이 안전합니다. 원인을 보려면 --debug로 실행하면 파싱 오류가 나온다고 문서에 적혀 있습니다.
폴더째 한 번에 점검하는 명령도 있습니다. claude plugin validate ~/.claude/skills로 개인 스킬 폴더를 검사할 수 있고, 클로드 코드 2.1.233 버전 이상이 필요하다고 문서에 나옵니다.
2단계. 위치와 이름이 맞는가
- 개인 스킬은 ~/.claude/skills/<이름>/SKILL.md, 프로젝트 스킬은 .claude/skills/<이름>/SKILL.md입니다.
- 세션을 시작할 때 없던 최상위 스킬 폴더를 새로 만들었다면 /reload-skills를 한 번 실행해야 합니다. 이미 있던 폴더 안에서 파일을 고치는 것은 재시작 없이 반영됩니다.
- 이름은 소문자·숫자·하이픈만 쓰고 64자 이하입니다. 공식 작성 안내는 플랫폼 스킬 이름에 anthropic, claude라는 단어를 넣지 못하게 하니, 폴더 이름에 이 영문 단어를 넣었다면 이름 때문에 거부된 것은 아닌지 봅니다.
프로젝트 스킬을 만들었다면 그 프로젝트 폴더에서 세션을 열었는지도 같이 봅니다. 프로젝트 위치의 스킬은 그 폴더에서 연 세션에서만 보이기 때문에, 다른 폴더에서 연 세션에서는 목록에 없는 것이 정상입니다. 개인 위치로 옮기면 모든 프로젝트에서 보입니다.
3단계. 설명 문장이 요청과 만나는가
여기부터가 "자동 호출"의 본론입니다. 클로드는 대화 중에 스킬의 이름과 설명만 보고 이 스킬을 쓸지 결정합니다. 본문은 스킬이 불린 뒤에야 읽힙니다. 그래서 본문에 아무리 좋은 내용을 써도 설명이 요청과 안 만나면 읽히지 않습니다.
공식 작성 안내가 말하는 설명 규칙은 네 가지입니다.
1. 무엇을 하는지와 언제 쓰는지를 같이 씁니다. 좋은 예로 "PDF 파일에서 글자와 표를 뽑고 양식을 채운다. PDF나 양식, 문서 추출을 말할 때 쓴다" 같은 문장이 실려 있습니다.
2. 사용자가 실제로 쓰는 단어를 넣습니다. 공식 문제 해결 항목의 첫 번째가 이것입니다.
3. 3인칭으로 씁니다. 설명이 시스템 안내문에 들어가기 때문에 "내가 도와드릴게요" 같은 말투는 호출에 문제가 된다고 경고합니다.
4. 막연한 설명(문서를 돕는다, 데이터를 처리한다)은 피합니다. 100개가 넘는 스킬 중에서 고르는 기준이라서입니다.
설명 길이는 두 가지 한도가 있습니다. 클로드 플랫폼용 안내는 설명을 1,024자 이하로 하라고 하고, 클로드 코드는 설명과 when_to_use를 합쳐 1,536자에서 자릅니다. 둘 다 "핵심 용도를 앞에 두라"는 말과 함께 나옵니다. 뒤쪽에 적은 키워드는 잘릴 수 있기 때문입니다.
제 스킬 28개의 설명 문장을 재 보니
제 컴퓨터의 개인 스킬 폴더에는 스킬 폴더가 28개 있습니다. 모두 SKILL.md 첫 줄이 ---로 시작하고 설정 부분이 정상적으로 열립니다. 설명 문장 길이를 글자 수로 재면 이렇습니다.
| 항목 | 값 |
|---|---|
| 스킬 수 | 28개 |
| 설명 글자 수 합계 | 4,902자 |
| 중앙값 | 164자 |
| 가장 짧은 설명 | 54자 (네이버 썸네일 이미지 스킬) |
| 가장 긴 설명 | 494자 (Blogger 운영 스킬) |
| 300자를 넘는 설명 | 2개 |
| 1,024자를 넘는 설명 | 0개 |
한도 면에서는 28개 모두 안전합니다. 가장 긴 494자도 1,024자의 절반 아래입니다. 이 표에서 눈에 띄는 것은 다른 두 가지입니다.
- 가장 짧은 54자 설명은 "…만들 때 반드시 쓴다. 로컬 카드 템플릿 금지"로 끝납니다. 언제 쓰는지는 있지만 무엇을 하는지는 금지 문구에 가깝습니다. 길이는 짧은데 쓸 때 상황은 분명한 쪽입니다.
- 가장 긴 설명은 영어와 한국어가 섞여 있습니다. 요청을 영어로 하든 한국어로 하든 맞아야 하는 스킬이라면 사용자가 실제로 쓰는 언어의 단어가 설명에 들어 있어야 합니다. 공식 문서의 "사용자가 자연스럽게 하는 말을 넣는다"를 제 상황에 옮기면 이렇게 됩니다.
다만 이 숫자는 "설명이 한도 안에 있다"까지만 말해 줍니다. 이 28개가 자동으로 몇 번 불렸는지는 따로 기록해 두지 않아 이 글에서 말할 수 없습니다. 길이가 짧다고 잘 불리는 것도, 길다고 안 불리는 것도 아닙니다.
4단계. 설명이 목록에서 밀려나지 않았는가
스킬이 많아지면 생기는 문제입니다. 클로드 코드는 모든 스킬의 이름과 설명을 목록으로 만들어 대화에 올립니다. 이름은 항상 들어가지만, 스킬이 많으면 설명을 일부 빼서 글자 예산에 맞춥니다. 문서에 따르면 예산은 모델 컨텍스트 창의 1%이고, 넘칠 때는 가장 적게 쓴 스킬부터 설명이 빠집니다. 설명이 빠진 스킬은 클로드가 매칭에 쓸 키워드가 없어져 자동 호출이 어려워집니다.
대처 방법도 문서에 있습니다.
| 하고 싶은 일 | 방법 |
|---|---|
| 목록 비용 보기 | /doctor, 안 쓰는 스킬 찾기는 /skill-doctor |
| 예산 늘리기 | skillListingBudgetFraction(예: 0.02) 또는 SLASH_COMMAND_TOOL_CHAR_BUDGET 환경 변수 |
| 덜 중요한 스킬 줄이기 | skillOverrides에서 "name-only"로 두면 설명 없이 이름만 올라감 |
| 설명 자체를 줄이기 | 핵심 용도를 앞에 두기, 항목당 1,536자 상한은 skillListingMaxDescChars로 조정 |
제 경우처럼 스킬이 20~30개 있고 설명이 평균 175자 안팎이면 합계가 5천 자 정도라, 이 단계가 문제인지는 모델 컨텍스트 창 크기에 따라 달라집니다. 정확한 예산은 /doctor로 보는 편이 가장 빠릅니다.
5단계. 일부러 막아 둔 설정은 없는가
두 가지 설정이 자동 호출을 막습니다.
- disable-model-invocation: true가 켜져 있으면 클로드가 그 스킬을 자동으로 못 부릅니다. 배포나 삭제처럼 사람이 직접 시작해야 하는 작업용으로 만든 설정입니다. 이 값이 켜진 스킬은 설명도 대화에 올라오지 않으니, 만든 기억이 없는데 안 불린다면 파일 맨 위를 한 번 열어 보세요. 제 스킬 28개의 맨 위에는 이 항목이 하나도 없습니다.
- paths에 글자 패턴을 적어 두면, 그 패턴에 맞는 파일을 다룰 때만 자동으로 올라옵니다. 문서는 경로가 현재 작업 폴더 기준이라, 옆에 연결한 다른 작업 폴더(git worktree 포함)의 파일에서는 켜지지 않는다고 설명합니다. 그 파일에서 쓰려면 그 폴더에서 클로드 코드를 시작하거나 /cd로 세션을 옮깁니다.
불리긴 하는데 규칙을 놓칠 때, 그리고 고친 뒤 확인하는 법
호출은 되는데 두세 번째 답부터 규칙을 안 지키는 경우도 문서가 따로 다룹니다. 원인을 세 가지로 나눕니다. 반드시 매번 지켜야 하는 규칙이라면 스킬이 아니라 훅으로 옮기라는 것이 첫째, 판단이 필요한 지침은 "테스트를 돌려라"가 아니라 "수정할 때마다 테스트를 돌려라"처럼 작업 전체에 걸리게 쓰라는 것이 둘째, 대화가 압축된 뒤에는 스킬을 다시 불러 내용을 되살리고 중요한 지침을 SKILL.md 맨 위에 두라는 것이 셋째입니다.
고친 뒤 확인하는 방법도 문서에 있습니다. 확인법은 단순합니다. 설명에 쓴 말을 그대로 포함한 요청을 새 대화에서 한 번 하고, 불리는지 봅니다. 한 번으로 판단하지 말고 비슷한 요청 서너 개를 바꿔 가며 해 보는 편이 낫습니다. 플러그인으로 배포하는 스킬이라면 claude plugin eval로 여러 요청에서 몇 번 불리는지 재는 방법이 문서에 안내되어 있습니다.
정리
안 불리는 스킬은 이 순서로 봅니다. 첫째, /스킬이름으로 부를 수 있는가. 둘째, 첫 줄이 ---이고 설정 문법이 맞는가. 셋째, 설명에 "무엇을, 언제"와 사용자가 실제로 쓰는 단어가 앞쪽에 있는가. 넷째, 스킬이 많아 설명이 밀려나지 않았는가. 다섯째, disable-model-invocation이나 paths를 걸어 두지 않았는가. 설명 문장은 길게 쓴다고 좋아지지 않으니 핵심 용도를 앞 한두 문장에 두면 됩니다.
이 글은 공식 문서를 기준으로 한 점검 순서이고, 제 스킬 28개는 설명 문장 길이와 파일 첫 줄만 재 본 것입니다.
제 스킬이 자동으로 불린 횟수나 안 불려서 고친 사례는 기록이 없어 적지 않았습니다.
설정 이름과 한도는 클로드 코드 버전에 따라 바뀔 수 있으니 고치기 전에 공식 문서를 한 번 열어 보세요. 앱에서 스킬을 켜는 방법은 클로드 스킬 설치방법, 켜기 전에 확인할 코드 실행 설정과 순서에 따로 정리해 두었습니다.