Claude Code의 스킬이 자동으로 발화되지 않는 진짜 이유 — 미문서 설정 skillListingMaxDescChars(기본

Claude Code에서 스킬(Skills)을 직접 만들었는데, 막상 대화에서 관련 작업을 요청해도 자동으로 발화되지 않는다. 특히 일본어로 말을 걸면 기동하지 않는다. 이런 경험은 없으신가요?

저(ゆるくさ)도 같은 부분에서 몇 번이나 막혔습니다. 흔히 권장되는 회피책은 "영어로 작성한 description 뒤에 일본어 트리거어를 추가한다"는 것이지만, 이것만으로는 조건에 따라 조용히 작동하지 않게 됩니다.

원인을 규명하기 위해, 수중에 설치되어 있는 Claude Code 본체(@anthropic-ai/claude-code의 번들 실체)를 실제로 조사했습니다. 그 결과, 공식 문서에는 아직 기재되지 않은 2가지 설정이 스킬의 자동 발화를 배후에서 좌우하고 있다는 것을 알게 되었습니다. 이 기사는 실기에서 확인한 사실과 settings.json에서 할 수 있는 구체적인 대처법을 정리한 것입니다.

Claude Code는 각 스킬의 description을 모은 "스킬 목록"을 모델에게 매 턴 전달합니다. 모델은 그 목록을 읽고, 지금의 대화에 어떤 스킬이 적합한지를 판단합니다. 즉, description의 내용이 모델에게 전달되지 않는다면 그 스킬은 후보에조차 오르지 않습니다.

여기에 2가지 상한선이 작용하고 있습니다. 둘 다 실기 바이너리에서 존재를 확인했습니다.

하나의 스킬의 description을 목록에 올릴 때의 글자 수 상한입니다. 바이너리 내의 설정 스키마에는 다음과 같이 적혀 있습니다.

Per-skill description character cap in the skill listing sent to Claude (default: 1536). Descriptions longer than this are truncated. Raise to opt in to higher per-turn context cost.

번역하면 "Claude에게 보내는 스킬 목록에서의, 1개 스킬당 설명문의 글자 수 상한(기본 1536). 이보다 긴 설명문은 잘립니다. 높이면 매 턴의 문맥 비용(context cost)이 증가하는 것을 감수하고 확장할 수 있습니다."

즉, 1536자를 초과한 부분은 말없이 잘려 나갑니다. 경고도 나오지 않습니다.

스킬 목록 전체에 할당되는 문맥 창(context window)의 비율입니다.

Fraction of the context window (in characters) reserved for the skill listing sent to Claude (default: 0.01 = 1%). When the listing exceeds this, descriptions are shortened to fit. Raise to opt in to higher per-turn context cost.

"Claude에게 보내는 스킬 목록을 위해 확보하는 문맥 창(글자 수 환산)의 비율(기본 0.01 = 1%). 목록이 이를 초과하면, 수용할 수 있도록 설명문이 단축됩니다. 높이면 매 턴의 문맥 비용(context cost)이 증가하는 것을 감수하고 확장할 수 있습니다."

스킬의 수가 많으면 목록 자체가 이 1%의 틀 안에 들어오도록 압축됩니다. 즉, 스킬이 늘어날수록 1개당 설명문에 사용할 수 있는 글자 수는 실질적으로 더욱 줄어듭니다.

여기까지 이해하면 흔히 있는 회피책의 약점이 보입니다.

영어로 작성한 긴 description 뒤에 일본어 트리거어를 덧붙인다고 가정해 봅시다. 합계가 1536자를 초과하면, 잘림 현상은 끝부분부터 발생하기 때문에 나중에 추가한 일본어 부분이 가장 먼저 사라집니다. 결과적으로 설정하려 했던 트리거어가 모델에게 전달되지 않아, "가끔 발화하지 않는다", "일본어일 때 기동하지 않는다"라는 증상이 재발합니다.

게다가 잘림 현상은 무언(無言)으로 이루어집니다. description을 길고 정성스럽게 작성할수록 이 함정에 빠지기 쉬워집니다.

제가 확인한 절차입니다. Claude Code의 본체는 대체로 다음 위치에 있습니다(환경에 따라 경로는 달라집니다).

# nvm을 사용하고 있는 경우의 예
BIN=$(find ~/.nvm -path '*claude-code*' -name 'claude' | head -1)
# 2개의 기본값이 존재하는지
...

설정값을 해결하는 함수도 settings.json의 값이 있으면 그쪽을 우선하고, 없으면 기본값으로 폴백(fallback)하는 형태로 존재합니다(대략 skillListingMaxDescChars ?? 1536)

, skillListingBudgetFraction ?? 0.01` (이러한 분기)입니다.

주의: 버전에 따라 내부 단축명(q75 등)은 변경될 수 있습니다. 확실한 것은 skillListingMaxDescChars / skillListingBudgetFraction라는 설정 키(key) 이름과 스키마에 기재된 기본값입니다. 단축명이 아닌 키 이름으로 검색하는 것을 권장합니다.

이 두 가지는 settings.json에서 명시적으로 변경할 수 있는 설정입니다. description을 반드시 길게 작성하고 싶거나 스킬의 수가 많은 경우에는 상한선을 높이는 것이 정공법입니다.

{
"skillListingMaxDescChars": 4096,
"skillListingBudgetFraction": 0.03
...
}

단, 스키마 설명에도 나와 있듯이, 이것은 "매 턴의 컨텍스트 비용(context cost)이 증가하는 것을 감수하고 범위를 넓히는" 설정입니다. 스킬 목록은 매 턴 전송되므로, 높인 만큼 토큰 소비가 증가합니다. 무턱대고 크게 설정하지 말고 필요한 범위 내에서 높여주세요.

비용을 늘리지 않고 수정하고 싶다면, 설정을 건드리기 전에 다음 사항을 먼저 검토하는 것이 우선입니다.

• 트리거(trigger)에 효과적인 단어를 앞부분에 배치하기: 잘림(truncation)은 끝부분부터 발생하므로, 중요 단어를 앞으로 배치하면 상한선 내에서도 살아남을 수 있습니다. description의 맨 앞에 배치하세요.
• description을 짧게 만들기: 1536자에 비해 설명문이 너무 길지 않은지 확인하세요. 장식적인 서론보다는 이 스킬이 무엇을 위한 것인지, 어떤 상황에서 사용하는지를 간결하게 작성하세요.
• 사용하지 않는 스킬 줄이기: 스킬의 수가 많을수록 1%의 할당량이 압박을 받습니다. 자주 사용하지 않는 것은 비활성화하세요.

"이 설정을 바꾸면 발화율이 몇 % 올라간다"라고는 말할 수 없습니다. 발화 여부는 모델의 판단이며, 수중에 확률을 엄밀하게 측정할 방법이 없기 때문입니다. 이 글에서 말할 수 있는 것은, **"설명문이 잘리면 트리거 단어가 모델에 도달하지 못하는 경로가 분명히 존재한다"**라는, 실기에서 확인된 사실까지입니다. 발화하지 않는 원인 중 하나를 설정으로 해결할 수 있다는 것이 요점입니다.

• 스킬의 자동 발화는 description을 모은 "스킬 목록"을 모델이 읽고 결정한다.
• 스킬의 설명문은 기본 1536자에서 말없이 잘린다 (skillListingMaxDescChars).
• 스킬 목록 전체는 컨텍스트 창(context window)의 기본 1% 내에 수용되며, 스킬이 많으면 더욱 압축된다 (skillListingBudgetFraction).
• 따라서 "영어 설명문 끝에 일본어를 추가하는 것"은, 합계가 상한을 초과하면 일본어 쪽부터 삭제되어 조용히 실패한다.
• 대처법은 settings.json에서 상한을 높이거나(비용 증가 감수), 중요 단어를 앞부분에 배치하고, 설명문을 짧게 하며, 스킬 수를 줄이는 것이다.

스킬의 description 작성 방식이나 실제로 발화하기 쉬운 스킬을 구성하는 방법은 시행착오가 그대로 품질로 나타납니다. 제가 자신의 스킬을 정리하며 쌓아온 구체적인 레시피(발화하기 쉬운 description 패턴, 자주 사용하는 스킬 사례, 설정 템플릿)는 Claude Code Skills 실전 레시피 모음(¥500)에 정리해 두었습니다.

또한, 스킬이나 hook을 포함한 Claude Code의 안전한 초기 설정은 무료로 공개 중인 cc-safe-setup에 정리해 두었으니 함께 참고해 주시기 바랍니다.