Ran Claude Code /doctor and Got a Warning

I ran /doctor to do a diagnostic check.

And got this:

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

I almost ignored it, but — 48 descriptions getting dropped?

---

What Does It Mean?

Claude Code loads the list of installed skills into context at the start of every conversation.

But there's a budget for how much of the context can be used, and when you have a lot of skills, the description text exceeds that budget.

The overflow just gets cut.

My current setting allocates only 1% of the total context to the skill listing, and with so many skills installed, 48 descriptions were being dropped.

---

Fix A: Raise the Budget Fraction

Increase the skillListingBudgetFraction value in settings.json.

{
  "skillListingBudgetFraction": 0.03
}

Bumping the default 0.01 (1%) to about 0.03 (3%) brings back the truncated skill descriptions.

The file lives at ~/.claude/settings.json or your project's .claude/settings.json.

Note: this increases the tokens spent on skill descriptions every session — about 6k tokens as shown in the /doctor output. If you actively use a lot of skills, this is the right fix.

---

Fix B: Disable Unused Skills

/skills

Run this and you'll get a list of installed skills. Disable the ones you don't actually use.

If you have 23 gstack skills and several superpowers installed but only use 5 of them daily, the rest are just noise.

Turning off unused skills is cleaner — no context waste, and /doctor goes quiet.

---

Which Should You Pick?

Use a lot of skills → A (raise the budget)

Have a lot of skills installed but only use a few → B (disable unused)

Doing both is also fine.

---

How Are "Most-Used Skills" Determined?

Claude Code tracks which skills you actually invoke.

Skills you use frequently keep their full descriptions in context. Skills you rarely touch get their descriptions dropped.

So the truncation isn't completely random — it's somewhat intelligent.

But there's a catch.

A newly installed skill, or one you haven't used in a while, may already have its description dropped from context.

If you type /skillname and Claude doesn't recognize it — responds with something like "I don't see that skill" — this is likely why.

That's why after disabling unused skills in /skills, you should always run /doctor again to confirm the warning is gone.

---

How to Actually Check

Follow this sequence:

• Run /doctor — see the current truncation status and which skills are being dropped
• Run /skills — see all installed skills and their current enabled/disabled state
• Identify which skills you actually use regularly
• Disable the rest using the toggle in the /skills interface
• Run /doctor again — verify the warning disappears

The settings.json file can exist in two places:

• User level: ~/.claude/settings.json — applies to all projects
• Project level: .claude/settings.json — applies to this project only

When both exist, project settings override user settings. Decide which level you want to apply skillListingBudgetFraction at before changing it — global if you want it everywhere, project-level if you want different settings per project.

---

One-Line Summary

The /doctor warning doesn't break anything, but truncated skills are invisible to Claude.

Worth checking that the skills you actually use are loading properly.