The era of hoarding AI agent skills is over. A deep dive into Claude Code and Codex mechanics reveals that the true cost of agent extensibility isn't in the individual skill file, but in the catalog overhead. As agents like Claude Opus 5.5 and gpt-6.1-sol become more autonomous, the fixed context budget for skill descriptions has become a critical bottleneck. When a catalog exceeds its allocation, the system ruthlessly drops descriptions for the least-invoked skills, turning your curated toolkit into a black box of opaque names.

The Hidden Tax on Context Windows

Testing on a Mac with Claude Code 2.1.312 and Codex CLI 0.160.1 exposed the hard limits. A catalog of approximately 80 custom skills, plus plugins and built-ins, consumed 10k tokens, hitting the documented 1% context budget exactly. With 131 skills listed, 78 had already lost their descriptions due to low invocation rates. Raising the budget to 3% restored all descriptions but ballooned the listing to 18.7k tokens. This trade-off forces a choice: can your agent find the right tool, or does it have enough room to think? The /skill-doctor tool confirms the waste, identifying 96 skills on the test machine that had never been invoked.

Naming Is the New Description

When the budget cuts descriptions, the skill's name becomes its only signal to the LLM. Tests showed that with a clear, descriptive name, Claude Code triggered the correct skill in 10 of 10 runs even without a description. However, an opaque name like hdrkit failed to trigger as a first step in any run, forcing the agent to dig through repository files to discover the skill's purpose. This proves that for long-term maintainability, semantic naming is more robust than relying on verbose descriptions that are prone to being pruned by the context manager.

Standardization and Security Risks

The fragmentation between tools is fading. Anthropic donated the Agent Skills specification to the Agentic AI Foundation on 2026-10-22, creating a portable core format. Both Claude Code and Codex now read from standardized folders, though quirks remainβ€”Codex 0.160.1 still silently loads skills from ~/.codex/skills, a legacy path not in current docs. Security is also paramount; project skills can self-grant tools via allowed-tools even in untrusted directories. Treat every third-party skill like executable code, auditing scripts and frontmatter before installation.

Key Takeaways

  • The catalog, not the skill, is the cost center; every installed skill consumes context budget on every turn.
  • Descriptions are the first thing dropped when budgets are tight; use descriptive, semantic names to ensure discoverability.
  • Use disable-model-invocation: true for skills with side effects (like deploys) to keep them out of the context budget.
  • The Agent Skills spec is now an open standard, allowing portable SKILL.md files between Claude Code and Codex.
  • Run /skill-doctor regularly to identify and remove skills that never execute.

The Bottom Line

Stop treating skill installation like a dotfiles backup. Prune your catalog aggressively, because a bloated skill list is just noise that degrades your agent's reasoning capabilities. If it doesn't run, it doesn't belong in the context.