[DOCS] Skills docs omit the v2.1.178 truncation warning's "how many descriptions are affected" count in `/doctor`
Documentation Type
Incomplete documentation
Documentation Location
https://code.claude.com/docs/en/skills
Section/Topic
"Skill descriptions are cut short" troubleshooting subsection (under "Troubleshoot skills"), and the "Skill descriptions are loaded into context..." paragraph that points to /doctor for the truncation breakdown.
Current Documentation
From skills.md (the troubleshooting section that points the reader at /doctor):
### Skill descriptions are cut short Skill descriptions are loaded into context so Claude knows what's available. All skill names are always included, but if you have many skills, descriptions are shortened to fit the character budget, which can strip the keywords Claude needs to match your request. The budget scales at 1% of the model's context window. When it overflows, descriptions for the skills you invoke least are dropped first, so the skills you actually use keep their full text. Run /doctor to see whether the budget is overflowing and which skills are affected.
From settings.md (the skillListingBudgetFraction row, line 281), the count is already mentioned:
...Raise to keep more descriptions visible at the cost of more context per turn. /doctor shows the current truncation count and which skills are affected. Requires Claude Code v2.1.105 or later
The v2.1.178 changelog (line 19) says:
Improved the skill listing truncation warning to show how many skill descriptions are affected
What's Wrong or Missing?
The v2.1.178 changelog ships a change that adds a count of "how many skill descriptions are affected" to the /doctor skill-listing truncation warning. The settings.md description of skillListingBudgetFraction was updated to mention the count, but the more reader-facing skills.md troubleshooting page was not.
A. The troubleshooting paragraph is missing the count the v2.1.178 change adds
The "Skill descriptions are cut short" troubleshooting section is the natural landing spot for a user who is debugging the warning. It says /doctor shows "whether the budget is overflowing and which skills are affected," but it does not mention the new "how many descriptions are affected" count that the v2.1.178 warning surfaces. The count is the headline number the warning was improved to expose, and the troubleshooting page never tells the reader to look for it.
B. The two descriptions of the same warning now disagree on what /doctor reports
settings.md line 281 says /doctor shows the "current truncation count and which skills are affected." The corresponding skills.md troubleshooting paragraph omits the count. A user who reads both pages will not realize they describe the same output, and a user who reads only skills.md will not know the count exists.
Suggested Improvement
Update the skills.md troubleshooting section so it matches the v2.1.178 behavior and stays consistent with the settings.md description. The minimal change is to add the count to the existing sentence:
Before:
Run /doctor to see whether the budget is overflowing and which skills are affected.
After:
Run /doctor to see the current truncation count, which skills are affected, and whether the budget is overflowing. {/ min-version: 2.1.178 /}From v2.1.178, the warning shows the number of descriptions affected in addition to the affected skill names.
If the page adopts a per-bullet layout for the /doctor output, the same information can be expressed as two sentences:
Run /doctor to see which skills are affected and whether the budget is overflowing. {/ min-version: 2.1.178 /}From v2.1.178, the warning also reports the number of descriptions affected.
Either way, the page should not contradict settings.md line 281, which already documents the count.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/skills | 793-795 | "Skill descriptions are cut short" troubleshooting section; sentence pointing to /doctor does not mention the new count |
| https://code.claude.com/docs/en/settings | 281 | skillListingBudgetFraction row — already documents the count, no change needed; cite as the canonical description |
| https://code.claude.com/docs/en/changelog | 19 | v2.1.178 entry is the source of the new count |
Total scope: 1 page affected (1 passage).
Changelog version: v2.1.178 (June 15, 2026), "Improved the skill listing truncation warning to show how many skill descriptions are affected".
Background: A prior release (v2.1.62, changelog line 620) removed the same warning as a startup notification and pointed users to /doctor for "the full breakdown." The v2.1.178 change is an improvement to that /doctor output, and skills.md is the page that points users to /doctor in the first place.