Too many skills in Claude Code

What each thing is

1. Skill: a folder with a SKILL.md file of instructions you give Claude. Personal ones live in ~/.claude/skills/<name>/SKILL.md and apply to every project. Project ones live in .claude/skills/<name>/SKILL.md, inside the project folder.
2. Description: the description field at the top of SKILL.md. Claude uses it to decide when to reach for the skill on its own. The optional when_to_use field is added to the description in the listing and counts towards the same character limit.
3. Skill listing: Claude Code sends Claude a list with the name and the description of each skill. The documentation says every skill in the listing takes room in every message, even if Claude never uses it. The rest of the SKILL.md only comes in once the skill is used.
4. The room Claude has to read: that is the context window, how much text the model can take into account at once in a conversation. The skill listing competes for that room with the rest of the conversation.
5. Listing budget: the listing has a cap of 1% of the model’s context window. Once it goes over, Claude Code trims descriptions, starting with the skills you use least. The name stays in the listing, and the skills you use most keep their full text.
6. Cap per description: the description plus when_to_use is cut at 1,536 characters, regardless of the budget. That value changes with the skillListingMaxDescChars setting.

Why that makes Claude ignore a skill

Without the description, the words Claude uses to connect your request to that skill are gone. The chance of it reaching for the skill on its own drops. Our reading: the chance drops, it does not reach zero, and you can still call the skill by name, typing /skill-name, as long as it is not turned off.

See how much room the listing takes

Inside a Claude Code session:

/doctor

According to the documentation, /doctor shows an estimate of how much room the skill listing takes and which skills weigh the most. The Skills line of the /context command shows the size of the listing after trimming, which is what the model actually receives. In versions before 2.1.196, that line showed a number far larger than the real one; if yours looks huge, update before worrying. When the listing goes over the budget, Claude Code also writes a warning into the diagnostic file it keeps for troubleshooting, visible if you start Claude Code with --debug.

Find the skills you never use

Inside a session:

/skill-doctor

The report shows the context cost of each skill and how many times it was used, and marks the ones never used. In an interactive session, it opens on the Stats tab of the /plugin manager. In the terminal, outside a session, you get the same report as text:

claude -p "/skill-doctor"

Watch out for:

• It requires Claude Code 2.1.252 or newer.
• It does not work through Remote Control (when you drive from your phone or browser a session that runs on the computer) nor in sessions that skip looking up new features. Run it in the terminal of the machine where the session runs. If the command does not exist in your session, check the version.
• The report does not include the skills that ship with Claude Code nor the ones from your company.
• The documentation recommends starting with the skills that cost the most context.
• Our reading: "never used" comes from usage history. A rare but important skill can show up on that list. Check before you touch it.

Decide what to do with each one

The skillOverrides setting has four states for each skill:

on

Claude sees the name and the description. It shows up in the / menu.

name-only

Claude sees only the name. It shows up in the / menu.

user-invocable-only

In the menu it appears as user-only. Claude does not see it. It shows up in the / menu.

off

Claude does not see it. It does not show up in the / menu.

A skill that does not appear in skillOverrides stays as on.

The simplest way is the menu, inside a session:

/skills

Pick the skill, press Space to switch the state and Esc to save. The menu writes your choice into .claude/settings.local.json.

If you would rather write it by hand, this is the format (the names are examples). JSON is just a configuration file format: copy it exactly, with braces, quotes and commas. If the .claude/settings.local.json file already exists, do not paste the whole block over it: add only the "skillOverrides": { ... } part inside the braces that are already there, separated from the other lines by a comma. If the file does not exist, the safest path is the /skills menu, which creates the file by itself.

{
  "skillOverrides": {
    "revisar-sql": "name-only",
    "testes-api": "off"
  }
}

How to choose:

• Use name-only to free up room and keep the skill one /skill-name away. Our recommendation for rare skills you still want within reach.
• Use user-invocable-only when Claude can stop seeing the skill, but you still want to call it from the menu.
• Use off to make it disappear from everything. Calling it by its full name returns an error instead of running. It also hides the skill from anyone using Claude Code through Remote Control or the Agent SDK. Before using off, check whether another skill or routine of yours calls that skill by name. When in doubt, use name-only. Our reading: since the setting only controls visibility, the skill folder stays on disk. Removing it for real would mean deleting the folder, and this guide does not ask for that.

Careful: plugin skills do not obey skillOverrides. Manage those through /plugin.

Write the description with the main use at the start

For the skills that stay, the documentation recommends putting the main use case right at the start of the description, because each description has a cap of 1,536 characters. An example (this line sits between the two --- dashes at the top of SKILL.md, next to the name field):

description: Revisa consultas SQL, procura erros e sugere melhorias. Use quando alguém pedir para revisar uma consulta.

Raise the budget if you need to

If you really do use many skills, you can raise the listing budget in the settings. The example below doubles the cap to 2% of the context window. Put that line inside your settings file, without deleting what is already there:

{
  "skillListingBudgetFraction": 0.02
}

The documentation also mentions the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable, which fixes the budget at a number of characters. It is for people who already work with environment variables; if you do not, ignore it. Our reading: a larger budget keeps more descriptions whole, but the listing then takes more room in every message. Our recommendation: trim before you raise it.

Summary to keep

1. Run /doctor and see how much room the listing takes.
2. Run /skill-doctor and find the skills never used.
3. In /skills, leave the rare ones as name-only and use off only for the ones you can do without.
4. Put the main use at the start of each description.
5. Only raise the budget if room is still short.

Myth and truth

• Myth: "an installed skill is a working skill". Truth: if the listing goes over the budget, its description may be trimmed, and Claude may not know when to use it.
• Myth: "a skill I never use costs nothing". Truth: according to the documentation, every skill in the listing takes room in every message.
• Myth: "turning it off deletes the skill". Truth: off only hides it. Our reading: the folder stays on disk. To turn it back on, switch the state back in /skills or delete the line from the settings file.

Source

Claude Code Docs, Skills, read on November 13, 2026. Educational and independent content, not affiliated with Anthropic.