Claude Code가 내 스킬을 5번 무시했다. 1줄로 해결

Claude Code 스킬은 이름으로 부르면 완벽하게 실행되는데도 스스로는 전혀 로드되지 않을 수 있습니다. 우리 스킬은 이름을 치면 매번 실행됐습니다. 그런데 같은 작업을 평범한 말로 부탁하면 매번 건너뛰어졌습니다. 건너뛰는 모습을 지켜보고, 이유를 읽고, 문제를 고친 한 줄을 다시 썼습니다.

스킬은 요청이 맞아떨어질 때 Claude Code가 스스로 집어 드는, 저장해 둔 지침 묶음입니다. 맞는지 아닌지를 정하는 건 지침이 아니라, Claude가 고르기 전에 읽는 한 줄입니다. 아래 여섯 단계는 계속 다시 치던 프롬프트에서 스스로 로드되는 스킬까지 안내합니다. 팀이 알아채기 전에 건너뛴 스킬을 잡아내는 스무 개 요청 테스트도 함께 다룹니다.

테스트 (같은 요청, 새 세션)	스킬 로드 여부
이름으로 호출 (/release-notes)	2번 중 2번
평범한 말, 원래 description	5번 중 0번
평범한 말, 고쳐 쓴 description	5번 중 5번

스킬은 파일 하나 SKILL.md가 들어 있는 폴더입니다. 파일은 짧은 헤더(이름과 한 문장짜리 description)로 시작하고 그 뒤에 지침이 이어집니다. 함수와 비슷합니다. 호출하는 쪽은 시그니처와 docstring을 읽고, 본문은 호출될 때만 실행됩니다. 홈 폴더에 저장하면 모든 프로젝트에서 쓰고, 저장소 안에 두면 거기서 일하는 모두가 받습니다.

파일이 아니라 작업에서 출발하세요. 계속 다시 치는 프롬프트를 고르고 원하는 출력을 정확히 적습니다. 우리 경우는 주간 릴리스 노트였습니다. 월요일 이후의 커밋을 영역별로 묶고, chore는 빼고, 변경마다 풀 리퀘스트 번호가 붙은 한 줄을 씁니다. 오픈소스 Hono 레포에서 그 긴 프롬프트는 그 주 버그 수정 여덟 건에 대한 깔끔한 노트를 만들었고, 그 출력이 스킬이 맞춰야 할 목표가 됐습니다.

모든 프롬프트가 스킬을 받을 자격이 있는 건 아닙니다. 일회성 질문은 필요 없고, 다시 쓰지 않는 스킬은 Claude가 읽어야 할 줄만 하나 늘립니다. 매주 치는 프롬프트의 짧은 목록을 만들고, 맨 위에 있는 것을 첫 스킬로 삼으세요.

프로젝트에 .claude/skills/release-notes/SKILL.md를 만듭니다. 숨김 폴더 .claude 안에 skills 폴더, 스킬 이름의 폴더, 그 안에 스킬 파일이 들어가는 구조입니다. 폴더가 중요합니다. 따로 놓인 release-notes.md는 아예 로드되지 않으며, 문서도 가장 먼저 확인할 것으로 꼽습니다.

헤더는 대시 두 줄 사이에 놓인 몇 줄의 레이블이고, 파일 첫 줄에서 시작해야 합니다. 그렇지 않으면 Claude Code가 무시합니다. 우리 헤더에는 이름 release-notes와 대부분이 쓸 법한 description이 있었습니다.

---
name: release-notes
description: Generates changelog documents from repository history.
---

헤더 아래에는 새 팀원에게 줄 법한 번호 매긴 단계로 지침을 적습니다. 우리는 다섯 개였습니다. 월요일 이후의 커밋 찾기, chore와 docs 커밋 빼기, conventional commit 스코프로 묶기, 변경마다 평이한 한 줄 쓰기, 위에 짧은 요약이 있는 제목 달린 블록으로 출력하기. Anthropic은 이 부분을 짧게 유지하라고 권장합니다. 재시작할 필요는 없습니다. Claude Code는 새로 만들거나 고친 스킬을 지금 쓰는 세션에서 그대로 집어 듭니다.

이름으로 테스트합니다. 슬래시를 치고, 메뉴에서 스킬을 고르고, 엔터를 누릅니다. 새 세션에서 우리 스킬은 커밋 로그를 읽고, 수정 사항을 영역별로 묶고, 원하던 그대로 노트를 매번 작성했습니다. 문제는 여러분과 팀 모두가 그 이름을 기억해야 한다는 점입니다.

팀원은 스킬 이름을 치지 않습니다. 새 세션을 열고 여러분에게 부탁하듯 부탁합니다. 그러니 그걸 테스트하세요. 새 세션(아무것도 로드되지 않은 새 대화)을 열고 여러분의 말로 작업을 부탁합니다. 반드시 새 세션이어야 합니다. 이미 쓴 스킬은 대화에 남아 있어서, 그 세션에서의 테스트는 아무것도 증명하지 못하기 때문입니다.

우리는 "이번 주에 뭘 배포했어?"라고 쳤습니다. Claude는 직접 커밋 로그를 실행하고 스킬의 흔적 없이 자기 방식으로 요약을 썼습니다. 답이 나쁘진 않았지만 실행마다 달랐습니다. 한 번은 월요일부터 세었고, 다른 한 번은 마지막 릴리스 태그부터 세면서 스킬이라면 뺐을 docs 변경까지 끌어왔습니다. 새 세션 다섯 번 모두에서 스킬은 건너뛰어졌습니다.

다섯 번의 실행은 통계가 아니라 데모입니다. 그래도 이름으로는 되는데 평범한 말에서는 매번 건너뛰는 스킬은 제 역할을 못 합니다. 게다가 2단계의 이름 테스트를 통과했으니, 들여다볼 생각조차 하지 않게 됩니다.

한 단어라도 바꾸기 전에 세 가지를 확인합니다.

1. **/skills**는 세션이 볼 수 있는 모든 스킬을 나열합니다. 여러분 것을 찾아보세요. 우리 스킬은 목록에 있고 켜져 있었지만, 환경에는 277개의 스킬이 있었고 우리 것보다 먼저 "release"에 맞는 플러그인 스킬이 여럿 있었습니다.
2. **claude --debug**는 Claude Code가 무엇을 로드하는지 자세한 로그로 남깁니다. skills 줄을 찾아보세요. 우리 로그에는 프로젝트 스킬이 로드됐다는 내용과 함께, 스킬 목록이 예산을 넘었다는 경고가 있었습니다. 그래서 일부 description은 잘립니다.
3. **claude plugin validate .claude/skills**는 헤더 형식이 올바른지 확인합니다. 이건 중요합니다. 깨진 헤더라도 스킬은 이름으로는 실행되지만, Claude는 더 이상 스스로 맞춰 볼 수 없습니다. 우리 것은 통과했습니다.

확인	알려 주는 것	우리 결과
/skills	스킬이 보이고 켜져 있는가?	목록에 있고 켜짐 (스킬 277개)
--debug	로드됐는가? 목록이 잘렸는가?	로드됨, 목록 예산 초과 경고
plugin validate	헤더가 파싱되는가?	통과

파일이 로드됐고 헤더도 유효하다면 원인은 description입니다. Claude는 스킬을 로드하기로 결정하기 전까지 여러분의 지침을 읽지 않습니다. 스킬마다 한 줄, 이름과 description을 읽고 여러분의 말과 맞춰 봅니다. 우리 것은 "generates changelog documents from repository history"였고, 요청은 "이번 주에 뭘 배포했어"였습니다. 두 문장에는 겹치는 단어가 하나도 없습니다. Claude는 우리 지침을 읽은 적이 없습니다. 한 줄을 읽었고, 그 줄이 우리 말을 쓰지 않았던 겁니다.

예산 경고는 Claude Code가 맞추려고 description을 줄인다는 뜻이고, 가장 덜 쓴 스킬부터 줄이는데 갓 만든 스킬은 가장 덜 쓰인 스킬입니다. 여러분 것이 살아남았는지 확인하세요. 우리 것은 살아남았습니다. 스킬 자체의 단어를 쓴 요청에서는 로드됐기 때문입니다.

description은 파일이 아니라 누군가 부탁하는 순간을 위해 쓰세요. 스킬이 무엇을 하는지, 언제 쓰는지, 사람들이 실제로 치는 말을 적습니다. 우리 것은 이렇게 됐습니다.

description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.

Anthropic의 작성 가이드는 규칙 하나를 더합니다. 3인칭("Writes")으로 쓰고, "I can help"나 "You can use this"는 쓰지 말라는 겁니다.

그런 다음 새 세션에서 같은 요청으로 입증합니다. "이번 주에 뭘 배포했어?"는 이제 Claude가 무엇이든 건드리기 전에 스킬을 로드했고, 노트는 우리 형식으로 나왔습니다. 새 세션 다섯 번 중 다섯 번입니다.

기준선도 잡아 보세요. 로컬 설정 파일의 skill override로 스킬을 끕니다(삭제하지 않고 숨깁니다). 끄면 Claude는 자기 방식의 요약으로 돌아갔고, 켜면 스킬이 로드됐습니다. 차이를 만든 건 운이 아니라 스킬입니다.

한계가 있습니다. 너무 많이 맞는 description은 스킬이 나서면 안 될 곳에서 나서게 만듭니다. 떠오르는 모든 단어가 아니라 실제로 쓰는 단어를 넣으세요.

요청 하나로 수정은 증명됐지만, 팀이 의지하는 스킬은 여러 방식으로 요청받습니다. Anthropic의 skill-creator가 이 테스트를 설명합니다. 스킬을 로드해야 하는 요청과, 로드하면 안 되는 아슬한 요청(near miss)을 섞은 스무 개의 요청입니다. 아슬한 요청은 비슷하게 들리지만 다른 일입니다. 예를 들면 "스테이징한 변경에 대한 커밋 메시지를 써줘"입니다. 각 요청을 자기만의 새 세션에서 실행하고 스킬이 로드됐는지 기록하세요. skill-creator의 스크립트는 우리 Claude Code 버전에서 스킬을 인식하지 못해서, 같은 스무 개 요청을 직접 만든 짧은 스크립트로 돌렸습니다.

description	로드해야 하는 요청 중 로드된 것	아슬한 요청 중 로드된 것
원래	10개 중 4개	10개 중 0개
고쳐 쓴 후	10개 중 10개	10개 중 0개

고쳐 쓰기 전에 스킬은 이미 "release notes", "changelog", "release"를 담은 요청에서만 로드됐습니다. 4단계의 단어 맞추기가 눈앞에서 벌어진 겁니다. 고쳐 쓴 뒤에는 로드해야 하는 모든 요청에서 로드됐고, 아슬한 요청은 여전히 모두 피했습니다.

절대 놓치면 안 되는 스킬은 강제하세요. 이름을 치거나, 훅을 추가합니다. 훅은 정해진 순간(여기서는 보내는 모든 메시지)에 Claude Code가 실행하는 작은 스크립트이며, 그 출력이 Claude에게 그 작업에 스킬을 쓰라고 알려 줍니다. 훅이 있으면 원래 description으로도 평범한 요청에서 로드됐습니다. 한계가 있습니다. 테스트를 돌릴 때마다 실제 사용량이 들고, 훅은 모든 메시지에 줄을 하나 더합니다. 정말로 실행돼야 하는 소수의 스킬에만 쓰세요. description을 바꿀 때마다 목록을 다시 돌리세요.

우리 릴리스 노트 스킬은 이름으로는 매번 작동했고, 새 세션에서 평범한 말로는 매번 건너뛰어졌으며, 고쳐 쓴 한 줄 덕에 매번 로드됐습니다. 이유는 Claude가 결정하기 전에 스킬마다 한 줄을 읽고, 여러분의 의도가 아니라 여러분의 말과 맞춰 보기 때문입니다.

스킬이 값을 하는 건 출력이 정해진 반복 작업입니다. 주간 노트, 풀 리퀘스트 설명, 릴리스 체크리스트. 일회성 질문에는 값을 못 하고, 항상 지켜져야 하는 규칙을 위한 도구도 아닙니다. 그건 훅의 일입니다. 안 쓰는 스킬 더미도 비용이 됩니다. 너무 많아지면 Claude Code가 가장 덜 쓴 것부터 description을 자르기 시작하기 때문입니다. 좋은 description은 확률을 높여 주지만, 애초에 맡지 않은 일에 스킬이 나서게 만들지는 못하며, 몇 번의 실행은 데모일 뿐이니 진짜 검증은 테스트 요청 목록입니다.

하나의 규칙: description은 그 작업을 부탁할 때 실제로 치는 말로 쓰세요.