Claude Code Is Secretly Disabling You

You meticulously curated 50 skills for your Claude Code assistant, transforming it into a personalized powerhouse. You integrated tools for data analysis, content generation, and intricate workflow automations, confident in your ultimate AI companion. Yet, lately, your assistant feels… limited. Its once expansive capabilities seem diminished, as if a silent force is actively working against your meticulously built setup, actively disabling your skills without your explicit knowledge.

A recent, poorly documented update to Claude Code is indeed the culprit. Version 2.1.129 quietly introduced a new, critical setting: `skillListingBudgetFraction`. This feature, largely unnoticed by the broader user base, silently caps the total metadata for all your installed skills to a mere 1% of Claude Code’s crucial context window. If your combined skill descriptions exceed this tiny budget, the system ruthlessly drops the descriptions of less-used skills, rendering them effectively useless. This occurs without any clear, actionable notification, leaving you bewildered why your assistant suddenly fails to perform specific tasks.

This isn't just an inconvenience; it represents a critical discovery for power users who depend on a deep and diverse skill set for their daily workflow. Many have spent weeks troubleshooting what they perceived as performance degradation or individual skill failures, unaware of the systemic change undermining their AI assistant’s core functionality. Claude Code offers only a fleeting, easily missed warning message at startup, such as "Skill listing will be truncated 10 descriptions dropped (full descriptions kept for most-used skills) (1.3%/1% of context)," leaving most users completely in the dark about the true problem.

The implications extend beyond mere functionality. An unmanaged context window, burdened by excessive skill metadata, leads directly to higher token usage and increased API costs, silently draining your resources. Alongside `skillListingBudgetFraction`, Claude Code also introduced `skillListingMaxDescChars`, defaulting to 1536 characters, which truncates individual descriptions before the overall budget is applied. This layered approach to skill management further complicates diagnosis for the unaware.

Fortunately, you don't have to tolerate this silent sabotage. We've uncovered the hidden mechanisms behind this change and identified simple, effective fixes. These include adjusting the `skillListingBudgetFraction` in your `settings.json`, utilizing the `/skills` slash command, or trimming individual skill descriptions to 150 characters. Soon, you'll regain full command over your AI assistant, putting you back in control of every skill you painstakingly installed.

Claude Claude Code 2.1.129 quietly introduced a critical setting, `skillListingBudgetFraction`, designed to manage the AI's operational efficiency. You find this new parameter within your `settings.json` file, where it defaults to a restrictive 1%. This fraction dictates the maximum portion of Claude's context window allocated to describing your installed skills, directly impacting which ones remain fully accessible.

Anthropic implemented this as a deliberate feature to optimize the AI's performance. The rationale targets 'skill bloat,' a common issue where a multitude of installed skills can degrade the context window's effectiveness and lead to unexpected behavior. By capping skill metadata, Claude ensures core functionality remains responsive without being overwhelmed by excessive descriptions. This is a proactive measure to prevent performance degradation.

Practically, a 1% budget translates to approximately 1,500 tokens. Given that a typical token represents about four characters, this budget permits only a few hundred words of combined skill descriptions. For instance, increasing the budget 2% consumes roughly 3,000 extra tokens per session. When your collective skill metadata surpasses this allowance, Claude Code prioritizes frequently used skills, keeping their full descriptions while often dropping less-utilized ones entirely, effectively disabling your skills.

The context window is a finite and crucial resource for any large language model. It represents the AI's short-term memory, holding all the information it needs to process a given query and generate coherent responses. Overloading this window with verbose skill descriptions reduces the space available for actual conversational data, leading to less capable responses and significantly increased token costs. Managing this skill listing budget is essential for maintaining optimal AI assistant performance and cost efficiency.

When your curated metadata for your installed skills, which includes descriptions and parameters, surpasses the 1% context window budget, Claude Code initiates a silent culling process. Version 2.1.129 introduced this sophisticated mechanism, first truncating individual skill descriptions exceeding 1536 characters via `skillListingMaxDescChars`. If the cumulative data still exceeds the budget, the system proceeds to drop entire skills.

This isn't a random purge. Claude Code intelligently prioritizes your most-used skills, ensuring their full descriptions remain intact and accessible. Conversely, the least-used skills are entirely dropped from the context, effectively disabling your skills without direct user intervention. This design aims to optimize the context window for relevant interactions.

Compounding the issue, Claude Code announces this culling with only a subtle startup warning message. This brief notification, often appearing as "Skill listing will be truncated X descriptions dropped...", is easily missed amidst other system logs or during rapid application launches. Users frequently remain unaware their assistant has become less capable until they attempt to invoke a vanished skill.

This intelligent prioritization marks a significant departure from older Claude Code versions. Previous iterations relied on a cruder, undocumented character limit that simply cut off skill descriptions without any usage-based logic or transparent feedback. The current system, detailed further in resources like the official Claude Code settings - skillListingBudgetFraction, offers a more nuanced but equally opaque management of your AI's capabilities, leaving many power users unknowingly operating with a diminished toolset.

AI operates on a token economy, a fundamental concept where every piece of data processed carries a direct cost. `skillListingBudgetFraction`, the setting secretly disabling your skills, directly translates into this digital currency. It dictates how much of your valuable context window goes towards describing your installed capabilities.

Consider the context window as Claude Code’s short-term memory, a finite space for processing information during each session. Every element within this window consumes tokens: your chat history, the system's instructions, and critically, the descriptions of your 50 installed skills. This consumption occurs with every single interaction.

Skill descriptions, often verbose and detailed, are not static metadata. Claude Code injects them into the context window for every new session, regardless of whether you invoke that specific skill. This constant transmission ensures the AI understands its available tools, but it also creates a persistent token drain.

Doubling the `skillListingBudgetFraction` from its default of 1% 0.02 (or 2%) might seem like a minor adjustment. However, this seemingly small increase translates to roughly 3,000 extra tokens consumed in every single session. For users with frequent interactions, these costs accumulate rapidly.

Imagine running 100 sessions a day. That 3,000-token overhead quickly balloons into 300,000 additional tokens daily, equating to millions over a month. This hidden token tax directly impacts your API bill, turning perceived utility into an unexpected financial burden.

Therefore, skill management transcends mere functionality. It becomes a critical aspect of financial cost control for power users. Ignoring the `skillListingBudgetFraction` means you are effectively paying for descriptions of skills you might not even be actively using.

Every additional character in a skill description, every unneeded skill enabled, contributes to this ongoing token expenditure. While trimming descriptions to 150 characters offers one mitigation, the core issue lies in the total allocated budget.

This unseen cost, silently levied with each interaction, underscores the importance of understanding Claude Code’s underlying mechanics. You manage your skills not just to optimize performance, but to protect your wallet from a continuous, often hidden, outflow of tokens.

Informed management of your AI assistant now includes a careful eye on the token budget. Failing to address this can lead to a significant, unacknowledged financial overhead for those who rely heavily on Claude Code's expanded capabilities.

You possess three distinct strategies to reclaim control from the `skillListingBudgetFraction` secretly disabling your skills. These methods offer a spectrum of control, from raw power modification to meticulous optimization, ensuring your Claude Code assistant operates at its full potential.

Power users can directly override the default `1%` budget by editing Claude Code's `settings.json` file. Navigate to your configuration directory, then open `settings.json` to locate or add the `skillListingBudgetFraction` entry. Setting this value to `0.02` effectively doubles your skill metadata budget to `2%` of the context window. This allows significantly more skill descriptions to remain active, preventing their capabilities from being dropped.

Implement this change by adding or modifying the following line within your `settings.json` file: ```json "skillListingBudgetFraction": 0.02 ```

Understand the critical trade-off: increasing the budget directly translates to higher token consumption. A `0.02` setting, for instance, adds approximately `3K` extra tokens to every single session. Factor this hidden cost into your API usage, especially if you engage Claude Code frequently throughout your workday.

For a more token-efficient approach, leverage the `/skills` slash command directly within Claude Code. This command provides an interactive list of all your installed `50` skills, allowing you to review their usage and disable those you rarely invoke. Culling unused skills remains the most cost-effective strategy, freeing up context window space without incurring additional token charges.

Embrace conciseness by trimming your skill descriptions to their essential purpose. Aim for descriptions under `150 characters` to maximize the number of skills that fit within the default `1%` budget. This meticulous approach ensures each active skill consumes minimal context, preventing descriptions from being silently truncated while still conveying core functionality.

Your optimal strategy depends on your usage patterns and budget. Power users prioritizing comprehensive functionality may accept the token cost of a higher `skillListingBudgetFraction`. Casual users will find the `/skills` command an immediate, zero-cost fix. For ultimate control and efficiency, combine judicious culling with precise, minimalist descriptions.

Beyond the initial `skillListingBudgetFraction` setting, a second, equally critical parameter works in tandem to manage your AI assistant's capabilities: `skillListingMaxDescChars`. This setting dictates the maximum character count for *individual* skill descriptions, preventing overly verbose entries from consuming the entire context window prematurely. Its default value sits at 1536 characters.

`skillListingMaxDescChars` performs a crucial pre-computation step. Before Claude Code even considers the overall `skillListingBudgetFraction`, it first truncates any skill descriptions exceeding this 1536-character limit. This ensures that no single skill, no matter how detailed its metadata, can unilaterally exhaust your allocated token budget.

This two-stage process provides a sophisticated, albeit poorly communicated, approach to skill management. First, Claude Code shortens individual skill descriptions to fit within the `skillListingMaxDescChars` limit. Next, the system aggregates the truncated metadata, checking its total size against the `skillListingBudgetFraction`. If the combined metadata still exceeds the budget, Claude Code then drops full descriptions for lower-priority skills, as observed in versions like Claude Claude Code 2.1.129.

While Anthropic initially rolled out these changes with minimal fanfare, this multi-layered approach represents a meaningful upgrade. It intelligently protects essential keywords and critical functionality embedded within the start of a skill's description from being silently truncated, a significant improvement over simply dropping entire skills. Understanding these settings is vital for power users looking to optimize their experience with Claude Code by Anthropic | AI Coding Agent, Terminal, IDE. You gain greater control over what remains functional in your AI toolkit.

Previously, Claude Code’s skill system operated under an opaque, undocumented character limit, estimated around 15,000 characters. This invisible ceiling meant that once users amassed a significant number of skills, or skills with lengthy descriptions, some would simply vanish from their active context without warning. Power users, meticulously crafting their AI assistants with dozens of custom tools, frequently found their most valuable utilities silently disabled, leading to profound frustration and wasted development effort. This silent sabotage undermined trust and efficiency.

Claude Claude Code 2.1.129 marked a decisive shift, introducing the more structured `skillListingBudgetFraction` and `skillListingMaxDescChars` settings. This crucial update arrived amidst broader enhancements within Claude Claude Code 2.1, which also delivered critical platform features like native slash command integration and robust hot-reloading capabilities. The change aimed to bring order to a burgeoning ecosystem, transitioning away from arbitrary, unseen limits to a more explicit, albeit complex, resource management model for skill metadata.

Implementing these new budget controls, though initially controversial due to their quiet introduction and the subsequent "disabling your skills" effect, represents a necessary evolution for a platform experiencing rapid growth. As Claude Code matures and its user base expands, a robust and predictable skill management system becomes paramount to ensure both stability and optimal performance. This was a direct, albeit initially poorly communicated, response to the prior chaos of skills silently disappearing and consuming excessive context window tokens.

Importantly, the skill system forms the fundamental backbone of Claude Code’s extensibility, with critical third-party tools relying heavily on its functionality. Solutions like Better Stack’s MCP server, which offers enhanced management and deployment of custom skills, directly leverage this underlying architecture. The integrity and predictability of skill listing are therefore not merely user conveniences but foundational elements for the entire Claude Code ecosystem, underpinning its utility, reliability, and future development trajectory.

Beyond the intricate dance of `skillListingBudgetFraction` and `skillListingMaxDescChars`, understanding Claude Code's entire context window is paramount for mastering your AI assistant. This context window functions as the AI's immediate working memory, the sum of all information it actively considers when generating responses or executing tasks. Every character in this window incurs a token cost and directly influences performance.

Skills, even with their metadata carefully managed, represent only one segment of this crucial memory. Other vital components constantly fill this space, each vying for the AI's attention and consuming valuable tokens. These include your ongoing conversation history, the contents of any currently open files, instructions specified within the project's `CLAUDE.md` file, and its adaptive auto memory.

Efficiently managing this combined context is not merely about preventing skills from silently vanishing; it directly impacts the AI's coherence, speed, and operational expenses. A bloated context window can lead to slower responses, irrelevant tangents, and significantly higher API costs with every interaction. Every token you send contributes to your bill.

Adopt several best practices to optimize your context. Be precise with your prompts, providing only necessary details. Close irrelevant files when you are not actively working on them, preventing their full contents from being continuously streamed into the context. Regularly clear conversation history when starting new, unrelated tasks to reset the AI's focus.

Consider leveraging the CLAUDE.md file for project-wide instructions or persona definitions, but keep it concise. Its contents persist across sessions, providing consistent guidance without needing repetition in every prompt. However, resist the urge to pack it with extraneous information that could dilute the AI's focus.

Active monitoring of your token consumption is critical for cost control and performance tuning. Claude Code offers built-in tools to help you visualize this usage. Execute the /cost command within your chat interface to immediately retrieve a summary of your current session's token expenditure.

For a more granular and persistent overview, community-developed tools like `ccusage` provide advanced analytics. These utilities allow you to track token usage over time, identify resource-intensive workflows, and pinpoint areas where context optimization can yield the most significant benefits. Mastering your context means mastering your AI.

Quietly introducing features like `skillListingBudgetFraction` ignited a significant debate within the AI community. Users invested substantial time curating dozens of skills for their Claude Code assistants, often building intricate workflows, only to discover their sophisticated tools were silently disabling your skills. A default 1% context window cap on skill metadata, combined with the truncation logic of `skillListingMaxDescChars`, meant critical functionality vanished without clear notification. The subtle warning message at startup, easily missed by most, proved insufficient for such an impactful change.

This lack of transparent communication underscores the vital role of the developer community and independent creators. Channels like Better Stack, through their incisive "Claude Code is SECRETLY Disabling Your Skills" video, were instrumental in publicizing how Claude Code was secretly disabling your skills. These community efforts often fill critical gaps where official documentation or public changelogs fall short, providing crucial insights into hidden mechanics. Further community findings and detailed technical breakdowns, exploring the nuances of these settings, are available in this claude-code-skill-budget-research.md - GitHub Gist.

AI developers, including Anthropic, operate under immense pressure to optimize model performance and manage API costs for their vast user bases. Automatically managing the context window through features like the default 1% `skillListingBudgetFraction` prevents you from unintentionally incurring excessive token costs or degrading model responsiveness with overly verbose skill descriptions. This automatic context window management aims to deliver a smoother, more cost-effective experience for the average user, who might not delve into intricate `settings.json` configurations.

However, such powerful, automatic management must carefully balance efficiency with user agency and transparency. Silently altering core functionality, by dropping skill descriptions or truncating them, can erode user trust and severely frustrate power users who expect granular control over their highly customized AI tools. The initial undocumented nature of these changes created a perception of a "ghost in the machine," where AI assistants inexplicably underperformed or lost capabilities. This highlights a fundamental tension between a developer's need for agile optimization and a user's expectation of explicit consent and clear communication regarding changes that directly impact their experience.

The core question remains: how should companies like Anthropic navigate this tension between rapid product development and comprehensive user transparency? Should impactful new features always be opt-in, or clearly communicated with prominent dashboard alerts? Or is a default "smart" management system, even if initially opaque, ultimately preferable for the majority of users who might not ever open their `settings.json` file? Where do you draw the line between automated optimization and giving users full, documented control over their AI's skill listing budget and capabilities?

This deep dive into Claude Code's skill management system reveals a non-negotiable truth for modern AI users: proactive management of your digital assistants is now essential, not optional. The introduction of `skillListingBudgetFraction` and `skillListingMaxDescChars` by Claude Claude Code 2.1.129, initially with minimal fanfare, demonstrates how seemingly minor updates can profoundly impact your AI's capabilities. These undocumented features secretly disabling your skills and compromise workflows by capping skill metadata at 1% of the context window or truncating descriptions over 1536 characters.

Regularly auditing your skills, settings, and workflows across *all* advanced AI platforms becomes paramount. Whether you’re managing 50 installed skills in Claude Code or fine-tuning prompts in other models, understanding the underlying token economy and context window limitations is critical. Unseen defaults, like Claude Code's 1% metadata cap, can dramatically alter performance and incur unexpected costs, often only signaled by an easily missed startup warning.

Embrace the complexity inherent in these sophisticated tools. Move beyond mere installation; understand the mechanics governing your AI. Knowing how individual skill descriptions are truncated to 1536 characters, or how your total skill metadata consumes a percentage of the context window, empowers you to optimize performance and prevent silent degradation. This mastery unlocks your AI's true, unhindered potential, allowing you to leverage every one of your curated skills effectively.

To truly become a future-proofed AI power user, leverage available resources. Dive into official documentation for comprehensive insights into your AI platforms. Watch the Better Stack video, "Claude Code is SECRETLY Disabling Your Skills," for a concise explanation of these hidden mechanics. Additionally, consult community forums and the GitHub Gist for ongoing discussions, shared best practices, and workarounds to manage your AI's evolving capabilities.

What is `skillListingBudgetFraction` in Claude Code?

It's a setting in settings.json introduced in version 2.1.129 that caps the total metadata for all skills to a percentage of the context window, defaulting to 1%.

Why are my Claude Code skills suddenly not working?

If your combined skill descriptions exceed the `skillListingBudgetFraction` budget, Claude Code keeps your most-used skills and drops the descriptions for the rest, effectively disabling them from auto-triggers.

What's the best way to fix disabled Claude Code skills?

The most token-efficient fix is to run the `/skills` command and disable any you don't use. Alternatively, you can increase `skillListingBudgetFraction` in settings.json, but this will increase your token costs.

Does increasing the skill budget cost more?

Yes. Increasing the budget from 1% to 2% uses approximately 3,000 extra tokens in every single session, which can lead to significantly higher API costs over time.