스킬을 하나 추가합니다. 작동합니다. 열 개를 더 추가하면, 첫 번째 스킬이 조용히 작동을 멈춥니다. 파일도 같고, 설명도 같고, 요청도 같습니다. 오류가 발생하지 않았으므로 수정할 것도 없습니다.

이것은 프롬프트(Prompt) 문제가 아닙니다. 예산(Budget) 문제이며, Claude Code는 관련된 모든 수치를 드러냅니다.

Claude가 실제로 보는 것

Claude Code는 모델이 무엇을 사용할 수 있는지 알 수 있도록 스킬 이름과 설명 목록을 컨텍스트(Context)에 로드합니다. 목록에는 항상 모든 스킬 이름이 포함됩니다. 압박을 받는 부분은 설명(Description)입니다.

두 가지 제한 사항이 중첩됩니다:

1. 항목당 제한. description과 when_to_use 텍스트의 결합은 목록에서 1,536자에서 잘립니다(Truncated). when_to_use는 description 뒤에 추가되며 동일한 한도에 포함됩니다.
2. 모든 항목에 걸친 제한. 전체 목록은 모델 컨텍스트 창(Context window)의 1%로 확장되는 문자 예산을 가집니다.

두 번째 제한 사항은 스킬이 8개에서 30개로 늘어날 때 변화하는 요소입니다. 당신의 설명이 나빠진 것이 아니라, 밀려난 것입니다.

무엇이 가장 먼저 삭제되는가

목록이 넘치면, Claude Code는 호출 빈도가 가장 낮은 스킬부터 설명을 삭제합니다. 가장 많이 사용하는 스킬은 전체 텍스트를 유지합니다.

이 순서를 주의 깊게 읽으십시오. 디버깅할 때 당신이 원하는 것과 정반대이기 때문입니다. 작동을 멈춘 스킬은 정의상 당신이 호출하지 않았던 스킬이며, 따라서 설명을 잃을 1순위가 됩니다. 이는 해당 스킬이 트리거될 가능성을 더욱 낮게 만듭니다. 일종의 래칫(Ratchet, 역전 방지 장치) 효과입니다.

목록에 설명이 없는 스킬은 여전히 존재하며 이름으로 호출할 수도 있습니다. 다만 무엇을 위한 것인지 광고하지 않을 뿐이므로, Claude가 스스로 요청과 매칭할 수 없게 됩니다.

추측 대신 측정하기

두 가지 명령어가 있으며, 각각 다른 질문에 답합니다.

/doctor는 목록의 컨텍스트 비용과 가장 큰 기여 항목에 대한 추정치를 제공합니다. 여기서부터 시작하십시오. 어떤 스킬이 예산을 잡아먹고 있는지 알려주며, 이는 무엇을 줄일지 결정하기 전에 당신에게 필요한 정보입니다.

/context에는 예산이 적용된 후의 리스팅 크기를 보고하는 Skills 행이 있어, 모델이 실제로 받는 것과 일치합니다. 이는 이전 습관을 가지고 있다면 중요합니다: v2.1.196 이전에는 해당 행이 모든 설명의 전체 텍스트를 계산하여 설정된 예산보다 훨씬 큰 값을 보여줄 수 있었습니다. Skills 행이 놀라울 정도로 크다고 기억하며 그것을 보기 시작하지 않았다면, 다시 살펴보십시오.

리스팅이 예산을 초과하는 경우, Claude Code는 --debug로 볼 수 있는 경고 메시지를 디버그 로그에 기록합니다.

해결 방법 3가지

출처에서 다듬기: 사용 사례를 전면에 배치하기. 각 항목은 예산과 관계없이 1,536자로 제한되며, 잘림(truncation)은 끝부분을 가져갑니다. 따라서 문장 순서가 스타일적이기보다 기능적이게 됩니다: 구체적인 트리거 케이스는 첫 번째 문장에 포함되어야 하며, 주의사항과 배경 정보는 비용이 가장 적게 드는 마지막 부분에 배치해야 합니다. 단일 스킬에서 1,536자로 제한된다면, 해당 스킬의 설명은 스킬 본문이 해야 할 일을 하고 있다는 의미입니다.

항상 이름으로 호출하는 스킬을 비활성화하기. skillOverrides는 스킬 자체의 프런트매터(frontmatter)가 아닌 설정에서 스킬 가시성을 제어합니다. 따라서 공유 리포지토리에 커밋하여 편집하고 싶지 않은 스킬에 적합한 방식입니다. 항목을 `

이유를 알게 된 후에 예산을 늘리세요. skillListingBudgetFraction은 컨텍스트 윈도우 (context window)의 비율(2%의 경우 0.02)을 지정하거나, SLASH_COMMAND_TOOL_CHAR_BUDGET을 통해 고정된 문자 수를 설정합니다. 항목당 최대 글자 수 제한은 skillListingMaxDescChars로 별도 설정할 수 있습니다.

실제로 서로 다른 스킬이 아주 많을 때는 예산을 늘리는 것이 올바른 선택입니다. 하지만 서로 중복되는 6개의 스킬을 가지고 있다면 예산을 늘리는 것은 잘못된 선택입니다. 왜냐하면 그중 하나를 선택하는 대신 6개 모두에 대해 매 세션마다 컨텍스트 비용을 지불하게 되기 때문입니다.

중복 문제

이는 예산 증액으로도 해결할 수 없는 실패 모드(failure mode)를 시사합니다. 만약 두 스킬이 동일한 요청에 대해 그럴듯하게 답변할 수 있다면, 리스팅(listing)은 이제 동전 던지기처럼 확률에 맡겨지게 되며, 모델은 오직 이름과 설명만으로 이를 결정하게 됩니다.

가장 저렴한 테스트 방법은 다음과 같습니다: 사용자의 언어로 요청 사항을 적은 다음, 두 설명을 모두 읽고 당신이라면 어느 것을 선택할지 스스로 물어보세요. 만약 당신이 망설여진다면, Claude도 망설일 것입니다. 두 스킬을 하나로 합치거나, 더 자주 선택되지 않는 쪽의 설명에 부정적인 케이스(negative case) — "X용이 아님, 이를 위해서는 /y를 사용하세요" — 를 추가하세요. 해당 스킬이 누구를 위한 것이 '아닌지'를 말해주는 문장은, 그 스킬이 무엇을 하는지에 대해 설명하는 다른 문장보다 리스팅 예산(listing budget)을 들일 가치가 훨씬 높습니다.

설명이 중요한 또 다른 곳

자동 압축(Auto-compaction)은 토큰 예산 내에서 호출된 스킬들을 유지합니다. 대화가 요약될 때, Claude Code는 요약문 뒤에 각 스킬의 가장 최근 호출 내용을 다시 부착합니다. 이때 각 스킬의 처음 5,000 토큰을 유지하며, 총합 25,000 토큰의 예산을 가집니다. 이 예산은 가장 최근에 호출된 스킬부터 채워집니다.

따라서 많은 스킬을 호출한 긴 세션의 경우, 압축 과정에서 오래된 스킬들은 완전히 제외될 수 있습니다. 만약 스킬의 동작이 처음부터 나타나지 않는 것이 아니라 세션 중간에 증발하는 것처럼 보인다면, 이는 리스팅 예산과는 다른 메커니즘의 문제이며, 해당 스킬을 다시 호출(re-invoking)하는 것이 해결책입니다.

요약

요약

• 각 항목별 설명(Descriptions)은 1,536자로 제한되며 컨텍스트 창의 약 1%에 달하는 리스팅 예산을 공유합니다.
• 오버플로우가 발생하면 가장 적게 호출된 스킬부터 설명을 삭제하므로, 사용 빈도가 낮은 스킬이 더 조용해집니다(quiet skill makes quieter).
• /doctor는 가장 큰 기여 요소를 찾고, /context 스킬 행은 예산 소진 후의 크기를 보여줍니다.
• skillOverrides에서 `