Claude Code /doctor 돌렸더니 경고가 나왔다

진단 한번 해볼까 싶어서 /doctor 돌렸습니다.

그랬더니 이런 게 나왔습니다.

Skill listing will be truncated
48 descriptions dropped (full descriptions kept for
most-used skills) (3.1%/1% of context): plan-tune,
design-html, qa, +45 more
    run /skills to disable some, or raise
    skillListingBudgetFraction (currently 1%) in
    settings.json

처음엔 그냥 넘겼는데 48개가 잘린다고?

---

무슨 뜻이냐

Claude Code는 대화 시작할 때마다 설치된 스킬 목록을 컨텍스트에 로드합니다.

근데 컨텍스트에 쓸 수 있는 예산이 있고 스킬이 많아지면 설명 텍스트가 그 예산을 넘습니다.

초과분은 그냥 잘립니다.

현재 내 설정은 전체 컨텍스트의 1%만 스킬 목록에 쓰도록 되어 있는데 스킬이 너무 많아서 48개 설명이 날아가고 있는 상황이었습니다.

---

해결법 A: 예산 비율 올리기

settings.json에서 skillListingBudgetFraction 값을 올리면 됩니다.

{
  "skillListingBudgetFraction": 0.03
}

기본값 0.01(1%)에서 0.03(3%) 정도로 올리면 잘리던 스킬 설명들이 다시 로드됩니다.

파일 위치는 ~/.claude/settings.json 또는 프로젝트의 .claude/settings.json.

단, 이러면 매 세션마다 스킬 설명에 쓰는 토큰이 늘어납니다. /doctor 출력에도 나와 있듯이 약 6k 토큰 정도. 자주 쓰는 스킬이 많다면 이쪽이 맞습니다.

---

해결법 B: 안 쓰는 스킬 비활성화

/skills

이 명령어를 치면 설치된 스킬 목록이 나옵니다. 거기서 실제로 안 쓰는 것들을 꺼버리면 됩니다.

gstack 23개, superpowers 여러 개 설치해놓고 실제로 매일 쓰는 건 5개도 안 될 수 있습니다.

안 쓰는 거 꺼두는 게 깔끔합니다. 컨텍스트 낭비도 없고 /doctor도 조용해집니다.

---

뭘 선택해야 하냐

스킬을 많이 쓴다 → A (예산 비율 올리기)

스킬이 많이 깔려 있지만 실제로 쓰는 건 몇 개 없다 → B (비활성화)

둘 다 해도 됩니다.

---

"most-used skills"는 어떻게 결정되나

Claude Code는 내가 실제로 호출한 스킬을 추적합니다.

자주 쓴 스킬은 설명 전체를 컨텍스트에 유지하고 거의 안 쓴 스킬은 설명을 잘라냅니다.

즉, 절단이 완전히 무작위는 아닙니다. 어느 정도 지능적으로 동작합니다.

하지만 여기서 함정이 있습니다.

새로 설치한 스킬, 또는 그동안 안 쓰다가 갑자기 써보려는 스킬은 설명이 이미 날아가 있을 수 있습니다.

/skillname 형태로 명령어를 쳐도 Claude가 인식을 못 하는 상황이 생깁니다. "그런 스킬 없는데요" 식의 반응이 나오면 이 경우일 가능성이 높습니다.

그래서 /skills에서 불필요한 스킬을 비활성화한 뒤에는 반드시 /doctor를 다시 돌려서 경고가 사라졌는지 확인하는 게 맞습니다.

---

실제로 어떻게 확인하나

순서대로 하면 됩니다.

• /doctor 실행 → 현재 절단 상태 확인, 어떤 스킬이 잘리고 있는지 목록 확인
• /skills 실행 → 설치된 전체 스킬 목록과 현재 활성 상태 확인
• 실제로 자주 쓰는 스킬이 뭔지 파악
• 쓰지 않는 스킬은 토글로 비활성화
• /doctor 다시 실행 → 경고가 사라졌는지 검증

settings.json은 두 군데에 있을 수 있습니다.

• 유저 레벨: ~/.claude/settings.json — 모든 프로젝트에 적용
• 프로젝트 레벨: .claude/settings.json — 해당 프로젝트에만 적용

두 파일이 동시에 존재하면 프로젝트 설정이 유저 설정을 덮어씁니다. skillListingBudgetFraction을 올리려면 어느 레벨에서 적용할지 먼저 결정해야 합니다. 전역으로 바꾸고 싶으면 ~/.claude/settings.json, 프로젝트별로 다르게 가져가고 싶으면 .claude/settings.json.

---

한 줄 정리

/doctor 경고는 무시해도 동작은 하지만 잘린 스킬은 Claude가 인식을 못 합니다.

쓰는 스킬이 제대로 로드되고 있는지 한번 확인해보는 게 맞습니다.