당신은 스킬을 작성했습니다. 설명은 명확합니다. 당신은 스킬이 수행하는 정확한 기능을 요청하지만, Claude는 다른 것을 찾습니다.

설명을 네 번째로 다시 작성하기 전에, Claude가 전체 내용을 제대로 보았는지 확인하십시오. 모델이 읽기 전에 스킬 메타데이터를 잘라내는 두 가지 별개의 제한이 있으며, 이 두 가지 모두 조용히 작동합니다.

두 제한은 동일한 제한이 아닙니다

Claude Code는 턴(turn)이 시작될 때 스킬의 리스팅 (listing) — 이름과 설명 — 을 컨텍스트(context)에 로드합니다. 이 리스팅은 Claude가 무엇이 존재하는지 알 수 있게 해주는 방식입니다. 여기에는 두 가지 독립적인 캡(cap)이 적용됩니다:

1. 항목당 제한 (A per-entry cap). 각 스킬의 description + when_to_use 텍스트 합계는 1,536자로 제한됩니다. 이를 초과하면 뒷부분이 잘립니다. 이는 리스팅에 여유 공간이 얼마나 남아있는지와 관계없이 적용됩니다.
2. 공유 리스팅 예산 (A shared listing budget). 모든 항목을 합쳐 컨텍스트 윈도우(context window)의 일부 — 1% — 를 할당받으며, 문서화된 폴백(fallback) 값은 8,000자입니다. 리스팅이 이 할당량을 초과하면, Claude Code는 호출 빈도가 가장 낮은 스킬부터 설명을 삭제하기 시작합니다. 가장 자주 사용하는 스킬은 전체 텍스트를 유지하지만, 사용 빈도가 낮은 나머지 스킬들은 이름만 남게 됩니다.

실패 모드는 서로 다르게 나타납니다. 항목당 제한에 걸리면 하나의 스킬이 트리거 가이드의 끝부분을 잃게 되며, 이는 종종 당신이 중요하게 생각하는 예외 사례(edge cases)를 나열하는 부분입니다. 30개의 스킬이 설치된 상태에서 공유 예산에 걸리면, 스킬 전체가 설명 없는 이름으로 변하며, 이는 Claude가 당신의 요청과 매칭할 정보가 아무것도 없음을 의미합니다.

추측하는 대신 직접 확인하세요

두 가지 명령어가 이를 직접 보고합니다.

/doctor는 스킬 리스팅의 컨텍스트 비용(context cost)에 대한 추정치를 제공하고 가장 큰 비중을 차지하는 항목을 알려줍니다. 이는 하나의 장황한 스킬이 다른 모든 스킬에 필요한 예산을 잡아먹고 있다는 사실을 알아내는 가장 빠른 방법입니다.

/context에는 예산이 적용된 후의 리스팅 크기를 보고하는 Skills 행이 있습니다. 따라서 모델이 실제로 받는 내용과 일치합니다. (v2.1.196 이전에는 해당 행이 모든 설명의 전체 텍스트를 계산하여 설정된 예산보다 훨씬 크게 표시할 수 있었으므로, 이 숫자가 쓸모없었다고 기억하신다면 이제는 그렇지 않습니다.)

또한 리스팅이 예산을 초과하면 디버그 로그에 경고가 기록됩니다. 터미널에서 확인하려면 --debug 옵션으로 실행하세요.

노브(Knobs) 돌리기

진단 결과 예산 제약(budget-constrained)이 있다고 나오면, 세 가지 방법이 있습니다. 제가 가장 먼저 시도할 순서대로 나열하면 다음과 같습니다:

출처에서 다듬기. 핵심 사용 사례를 첫 문장에 배치하세요. 설명은 끝부분부터 잘리기 때문에, 본인이 작성한 텍스트의 순서가 무엇이 살아남을지를 결정합니다. 이는 무료이며, 어차피 매칭 성능도 개선됩니다.

개별 항목(per-entry)에도 설정이 있으며, 여기서 두 가지 주요 출처가 그것을 무엇이라고 부르는지에 대해 의견이 다릅니다. 문서 페이지에서는 이를 skillListingMaxDescChars라고 명명합니다. 반면, 게시된 설정 스키마는 동일한 메커니즘을 정의하며, 기본값은 1,536자로, maxSkillDescriptionChars라는 이름으로 되어 있습니다.

제가 최근에 반대 방향으로 잘못 알았던 경험이 있어서 이 점을 지적합니다. 저는 한 출처를 확인했는데 기대했던 이름을 찾지 못했고, 그 설정이 존재하지 않는다고 결론 내렸습니다. 하지만 실제로 존재합니다. 만약 하나의 이름만 검색해서 아무것도 나오지 않는다면, 해당 결정(설정이 없다)을 내리기 전에 다른 출처도 반드시 확인해 보세요.

작동하는 디버깅 순서

스킬이 트리거되지 않을 때, 이 순서를 따르면 글을 다시 쓰는 것보다 원인을 더 빨리 찾을 수 있습니다:

1. /doctor를 실행합니다. 만약 리스팅 예산 초과 상태라면, 이것부터 먼저 수정하세요. 설명 내용에 대해서는 중요하지 않습니다. 이미 잘려 나갔다면 어떤 내용을 담고 있든 상관없습니다.
2. 스킬의 description + when_to_use가 1,536자에 가까운지 확인합니다. 만약 그렇다면, 끝부분의 세부 내용은 사라집니다.
3. 설명의 첫 문장만 읽어보세요. 이것이 과업(

저는 Claude Code, Cursor, Codex를 위한 프로덕션 준비 완료된(production-ready) 규칙(rules), 스킬(skills), 훅(hooks) 패키지인 Rulestack을 구축하면서 이 글들을 작성하고 있습니다. 또한 이와 같은 짧은 발견 사항들을 Bluesky의 @ai-shop.bsky.social에 게시하고 있습니다. 만약 이것이 여러분이 겪고 있는 종류의 문제라면 팔로우해 주세요.