이 페이지의 목차
확인 2026-10-18근거 자료 1건갱신 2026-10-26언급 12곳
이 페이지의 목차
확인 날짜 안내

확인 날짜: 2026-10-18 (공식 문서 Claude Code 스킬, 원본 날짜 미상, 수집일 기준)

스킬이 기대대로 돌지 않을 때 증상별로 확인할 순서다. 원본 Troubleshooting 절과 관련 절을 모았다.

준비물(필요한 것)#

필요한 것내용
문제가 된 스킬의 SKILL.md스킬 폴더 안의 지시 파일. 맨 위 frontmatter(---로 감싼 설정 블록)의 description(언제 쓰는 스킬인지 적은 설명)을 고치게 된다(1·2절) Claude Code 스킬
Claude Code 세션스킬이 놓인 프로젝트에서 연 세션. /skill-name, /doctor, /context, /skill-doctor, /reload-skills 같은 명령을 그 안에서 실행한다 Claude Code 스킬
디버그 실행파싱 오류·거부된 이름을 보려면 claude --debug로 세션을 연다(1·4·5절) Claude Code 스킬
버전 조건이 있는 명령을 쓴다면claude plugin validate는 v2.1.233 이상, /add-dir로 하위 디렉터리 스킬을 바로 올리려면 v2.1.257 이상(1·5절) Claude Code 스킬

설치 절차는 이 페이지의 원본이 다루지 않는다. 스킬을 처음 만드는 단계라면 업무 절차를 스킬로 만들기부터 본다.

증상별 점검표#

증상먼저 볼 것
기대할 때 Claude가 스킬을 안 쓴다설명 키워드, 목록에 있는지, YAML(용어 사전) 오류, 이름 거부
원치 않을 때 자꾸 쓴다설명을 더 구체적으로, disable-model-invocation: true
처음엔 따르다 나중에 안 따른다매번 규칙인지, 일회성 표현인지, 컴팩션이 있었는지
스킬이 많아 설명이 잘린다목록 예산 1%, /skill-doctor, name-only
/ 메뉴에 스킬이 없다이름의 금지 문자, 하위 디렉터리 스킬 로드 시점
개인 스킬 폴더가 사라졌다~/.claude/skills/.trash/
스킬 호출이 통째로 실패한다! 명령의 실패 코드·권한 규칙

1. 트리거되지 않는다#

  1. description에 사용자가 자연스럽게 말할 키워드가 있는지 본다.
  2. What skills are available?로 물어 목록에 나오는지 확인한다.
  3. 요청을 설명과 더 가깝게 바꿔 말해 본다.
  4. 사용자가 부를 수 있는 스킬이면 /skill-name으로 직접 부른다.
  5. /skill-name도 인식되지 않으면 Claude Code가 이름을 거부했는지 본다(아래 5).

근거: Claude Code 스킬

  • frontmatter YAML이 깨지면 메타데이터 없이 본문만 로드된다. /skill-name은 되지만 Claude가 description과 맞춰 볼 수 없다. --debug로 실행해 파싱 오류를 본다. claude plugin validate .claude/skills(개인은 ~/.claude/skills)로 파싱 안 되는 SKILL.md를 찾는다(v2.1.233 이상). Claude Code 스킬
  • 플러그인 스킬이면 프롬프트를 하나씩 확인하지 말고 tool_used: Skill 채점 기준을 단 평가 케이스를 만들어 설명을 바꿀 때마다 claude plugin eval로 트리거 빈도를 잰다. Claude Code 스킬 → 업무 절차를 스킬로 만들기

2. 너무 자주 트리거된다#

  1. 설명을 더 구체적으로 쓴다.
  2. 직접 부를 때만 돌게 하려면 disable-model-invocation: true를 단다.

근거: Claude Code 스킬

3. 처음엔 따르다가 나중에 안 따른다#

맞는 경우부터 본다. Claude Code 스킬

  • 매번 지켜야 할 규칙을 건너뛰었다: 규칙을 훅으로 옮긴다. 훅은 Claude가 스킬을 따르든 말든 이벤트마다(예: 파일 편집 전마다) 돈다. 스킬과 함께 두려면 스킬의 hooks frontmatter에 정의한다. 그 훅은 스킬을 부른 때부터 세션 끝까지 적용된다.
  • 판단해서 적용할 지침을 건너뛰었다: 작업 전체에 적용되게 고쳐 쓴다. "테스트를 돌려라"가 아니라 "편집할 때마다 테스트를 돌려라". 스킬은 부를 때 대화에 한 번 더해지고, 이후 턴에 파일을 다시 읽지 않는다.
  • 대화가 컴팩션됐다: 스킬을 다시 불러 전체 내용을 복원한다. 컴팩션 뒤에는 스킬 앞부분만 남을 수 있으므로(스킬당 앞 5,000토큰, 전체 25,000토큰 예산, 최근 호출부터) 가장 중요한 지시를 SKILL.md 위쪽에 둔다. → 장기 작업 컨텍스트 관리

4. 설명이 잘린다 (스킬이 많을 때)#

  • Claude Code는 스킬 이름과 설명 목록을 컨텍스트에 싣는다. 이름은 항상 다 들어가지만, 스킬이 많으면 목록 문자 예산(모델 컨텍스트 창의 1%)에 맞추려고 일부 설명을 뺀다. 가장 덜 부르는 스킬부터 빠지므로 자주 쓰는 스킬은 설명이 남는다. 설명이 빠지면 Claude가 요청과 맞춰 볼 키워드가 사라진다. Claude Code 스킬
  • 확인: /doctor는 목록의 컨텍스트 비용과 큰 기여 항목을 추정한다. /context의 Skills 행은 예산 적용 뒤 크기다. 넘치면 --debug 로그에 경고가 남는다. Claude Code 스킬
  • 대처: Claude Code 스킬
    • /skill-doctor로 끌 만한 스킬을 찾는다. 컨텍스트 비용이 큰 것부터.
    • 우선순위 낮은 스킬은 skillOverrides에서 "name-only"로 둬 설명 없이 이름만 싣는다.
    • description·when_to_use를 줄이고 핵심 용도를 앞에 둔다(항목당 1,536자 상한, skillListingMaxDescChars).
    • 예산 자체를 키운다: skillListingBudgetFraction(예: 0.02 = 2%) 또는 SLASH_COMMAND_TOOL_CHAR_BUDGET(고정 문자 수).

→ 컨텍스트 비용

5. / 메뉴에 없다#

  • 이름의 금지 문자: 폭 없는 공백·제어 문자, 아이콘 폰트 같은 사용자 정의 영역 문자, 텍스트 방향을 바꾸는 문자, 줄 바꿈 없는 공백·연속 공백·앞뒤 공백, <·>가 이름에 있으면 거부된다. 폴더·파일 이름이 거부되면 로드되지 않으니 이름을 바꾼다. claude --debug 로그에서 [names]를 찾으면 어느 이름이 거부됐는지 나온다. Claude Code 스킬
  • 하위 디렉터리 스킬: 시작 위치보다 아래 .claude/skills/의 스킬은 시작 때 로드되지 않고, Claude가 그 폴더 파일을 처음 읽거나 고칠 때 로드된다. 그 전에는 메뉴에도 없고 이름으로 부를 수도 없다. 빨리 쓰려면 /add-dir <경로>(v2.1.257 이상). Claude Code 스킬
  • 예약 이름: synced라는 이름(대소문자 무관)은 엔터프라이즈·개인·프로젝트 위치에서 건너뛰고, anthropic-skills이거나 anthropic-skills:로 시작하는 이름은 플러그인 밖에서 로드되지 않는다. Claude Code 스킬
  • 세션 중 새로 만든 최상위 스킬 디렉터리: /reload-skills. Claude Code 스킬

6. 개인 스킬 폴더가 사라졌다#

~/.claude/skills/.trash/를 본다. claude.ai 동기화는 별도 synced 하위 폴더에 내려받으며, 사용자가 만든 폴더를 옮기거나 지우지 않는다. v2.1.280 이전에는 ~/.claude/skills/의 manifest.json 파일이 거기 적힌 스킬 폴더를 .trash/ 아래로 옮겼다. 복원하려면 타임스탬프 폴더에서 ~/.claude/skills/로 되돌린다. 휴지통 항목은 기본 30일 뒤 지워진다. Claude Code 스킬

7. 스킬 호출이 통째로 실패한다 (동적 컨텍스트)#

  • !`명령` 하나가 실패하면 그 자리만이 아니라 스킬 호출 전체가 중단되고, Claude는 그 호출의 스킬 내용을 보지 못한다. 메시지는 Shell command failed for pattern "...". 기본 bash에서는 0이 아닌 종료 코드가 모두 실패다(검색·비교 명령의 종료 코드 1은 예외). 문제를 찾으면 1로 끝나는 점검 스크립트처럼 0이 아니게 끝날 것으로 예상되는 명령에는 || true를 붙인다. Claude Code 스킬
  • 주입 명령은 렌더 중에 권한을 묻지 않는다. 권한 규칙에 비춰 거부되면, 그리고 자동 모드 밖에서는 허용이 아닌 모든 결과에서 Shell command permission check failed for pattern "..."로 중단된다. 막히지 않게 하려면 allowed-tools로 미리 허용한다. Claude Code 스킬 → 권한 모드
  • 각 명령은 Bash 도구 기본 타임아웃 2분 아래에서 돌고, 세션 셸의 현재 작업 디렉터리에서 실행된다. 경로는 ${CLAUDE_SKILL_DIR}·${CLAUDE_PROJECT_DIR}로 고정한다. Claude Code 스킬

됐는지 확인하는 법#

고친 뒤 아래로 확인한다. 모두 본문 각 절에 나온 방법을 모은 것이다.

  • 목록에 올라왔는지: What skills are available?로 물어 스킬이 나오는지 본다(1절 2번). Claude Code 스킬
  • 직접 불리는지: 사용자가 부를 수 있는 스킬이면 /skill-name으로 불러 본다. 인식되지 않으면 claude --debug 로그에서 [names]를 찾아 이름이 거부됐는지 본다(1·5절). Claude Code 스킬
  • frontmatter가 파싱되는지: --debug로 파싱 오류를 보거나, claude plugin validate .claude/skills(개인은 ~/.claude/skills, v2.1.233 이상)로 파싱 안 되는 SKILL.md를 찾는다(1절). Claude Code 스킬
  • 설명이 잘리지 않는지: /doctor가 목록의 컨텍스트 비용을 추정하고, /context의 Skills 행이 예산 적용 뒤 크기를 보여 준다. 넘치면 --debug 로그에 경고가 남는다(4절). Claude Code 스킬
  • 트리거 빈도(플러그인 스킬): tool_used: Skill 채점 기준을 단 평가 케이스를 claude plugin eval로 돌려 잰다(1절). Claude Code 스킬
  • "나중에 안 따르는" 문제(3절): 원본에는 고친 뒤 확인하는 방법이 따로 없다. 매번 지켜야 할 규칙은 훅으로 옮기면 Claude가 스킬을 따르든 말든 이벤트마다 돈다(3절). 훅이 실제로 도는지는 Claude Code 훅 문제 해결을 본다.

관련#