Claude Code 스킬 제대로 불리게 쓰기

Claude Code 스킬(SKILL.md)을 만들어 두었는데 쓰이지 않습니다. 화면에는 오류가 없고, 물어보면 '네, 그 스킬이 있습니다' 라고 합니다. 스킬이 쓰이지 않는 까닭이 폴더 한 칸이나 파일 이름의 s 하나일 수 있습니다.

이 책은 스킬이 목록에 오르는지 · 불리는지 · 지시를 따르는지를 Claude 의 말이 아니라 시작할 때의 스킬 목록과 Skill 도구 호출 기록으로 세어 확인합니다.

이런 일을 하고 계신다면

· 스킬을 만들었는데 / 를 눌러도 안 보인다

· 스킬은 보이는데 Claude 가 안 쓴다

· 스킬이 여러 개라 엉뚱한 것이 불린다

· 스킬 설명을 길게 자세히 쓰고 있다

· 스킬을 메모장으로 저장해 왔다

이 책에 들어 있는 것

레시피 열네 개 · 열다섯 단계 · 104쪽

01 스킬은 '있다' 가 아니라 목록 · 호출 · 따름, 세 번 따로 셉니다

02 스킬 하나 — 열다섯 번 중 열다섯 번 불렸습니다 (기준선)

03 폴더를 한 칸만 잘못 둬도 — 스킬이 오류 없이 사라집니다 (0/9)

04 파일 이름의 s 한 글자 — skills.md 는 읽히지 않습니다 (0/6)

05 머리말(---) 한 줄이 틀리면 — 목록에서 빠집니다 (구분선 · 탭 · 따옴표)

06 다른 스킬이 여덟 개 있을 때 — 설명이 구체해야 불립니다 (18/18 · 16/18 · 0/18)

07 돌려 말하면 — 모호한 설명은 열여덟 번 중 한 번 불렸습니다

08 description 이 길면 — 2500자는 열다섯 번 중 다섯 번만 불렸습니다

09 자동 호출을 끄는 두 줄 — 서로 반대로 먹습니다

10 SKILL.md 를 메모장 ANSI 로 저장하면 — 목록엔 오르는데 지시를 따르지 못합니다

11 name: 에 무엇을 적어도 — 스킬 이름은 폴더 이름입니다

12 안 불리는 스킬 응급처치 — CLAUDE.md 한 줄이면 0/18 이 18/18 이 됩니다

13 어떤 스킬이 불렸는지 훅으로 남기기 — 기록이 Claude 의 기록과 3/3 같습니다

14 Claude 없이 폴더를 훑어 — 조용히 빠질 스킬 열한 가지를 미리 찾습니다

15 찾고 · 고치고 · 다시 불러 보니 — 목록에 없던 다섯 가지가 모두 올랐습니다

조용히 사라진 것을 다 실었습니다

· 폴더 안의 폴더 · 파일만 · skill 단수 — 스킬이 오류 없이 목록에서 빠짐 (0/9)

· skills.md · SKILL.txt · README.md — 파일 이름이 틀리면 읽히지 않음 (0/6)

· 머리말의 구분선 · 줄 앞 탭 · 닫히지 않은 따옴표 — 목록 0/9

· 모호한 설명 + 돌려 말한 질문 — 열여덟 번 중 한 번만 불리고 엉뚱한 스킬(todo)이 불림

· 2500자 설명은 열다섯 번 중 다섯 번만 불림 · cp949 SKILL.md 는 목록엔 오르지만 지시를 따르지 못함 (0/9)

· CLAUDE.md 한 줄이면 0/18 이 18/18 로 · 점검기가 조용히 빠질 스킬 열한 가지를 Claude 없이 찾음

스킬은 목록 · 호출 · 따름, 세 번 따로 셉니다

Claude 의 답이 아니라 시작할 때의 스킬 목록(init), Skill 도구 호출 기록(stream-json), 답의 첫머리로 판정했습니다.

고치기 전과 후에 같은 질문으로 불러 비교했습니다.

전부 실제로 돌려 확인했습니다

2026년 10월 12일, Windows 10 · Claude Code 2.1.286 에서 레시피 열네 개를 세 판 만들어 돌렸습니다.

기록이 남은 호출 701번. 본문의 검은 상자는 그때 나온 화면 그대로이고, 부록의 코드도 실제로 돌아간 파일 그대로입니다.

사례마다 연습 폴더 밖의 새 폴더에서 불렀고, 내 사용자 설정은 읽지 않았습니다. 모델은 haiku 이며 Windows 10 에서만 시험했습니다.

이런 분께

· Claude Code 스킬을 만들어 쓰는 분

· 스킬이 열 개 이상 쌓인 분

· 팀에 스킬을 나눠 주려는 분

포함 파일

PDF (A4 · 104쪽) · EPUB (모바일 · 리더용)

두 가지가 ZIP 하나에 들어 있습니다.

「Claude Code 실전」 시리즈입니다. 이 책은 Anthropic 과 관계가 없는 개인의 사용기입니다.