How Many Agent Skills Can I Install? Token Cost Explained
2026-10-30
Short answer: Claude Code and Codex don't limit how many skills you install, but every skill you install costs context on every turn. Each skill's name and description sit in the agent's context, about 100 tokens per skill by Anthropic's estimate. Each tool caps that listing: by default 1% of the model's context window in Claude Code and 2% in Codex. Past the cap, descriptions are shortened or dropped, and the agent gets worse at picking the right skill.
This guide covers how that cost works, the documented limits in each tool (as of Oct 30, 2026), how to measure your own setup, and how to trim it.
How a skill uses context: three levels
Skills load in stages, which the Agent Skills spec and Anthropic's docs call progressive disclosure. Only the first stage costs you anything before the skill is used:
| Level | When it loads | Token cost (Anthropic's figures) |
|---|---|---|
| 1. Metadata: name and description | Always, at startup | About 100 tokens per skill |
| 2. Instructions: the SKILL.md body | When the skill is triggered | Under 5,000 tokens recommended |
| 3. Resources: references/, scripts/, assets/ | Only when read or run | None until accessed. A script's output enters context, not its code. |
So the number to watch is the first row multiplied by the number of skills you have. By Anthropic's rough figure, 50 installed skills put about 5,000 tokens of names and descriptions in front of the model on every turn, whether or not any of them is used. A skill with a long description costs more than the average.
Once a skill is used, its instructions stay. In Claude Code, the SKILL.md content enters the conversation as one message and stays there on later turns. After the conversation is compacted, Claude Code re-attaches the most recent use of each skill, keeping the first 5,000 tokens of each, within a combined 25,000-token budget. If you have used many skills in one session, the older ones can drop out.
The documented limits, tool by tool
| Tool | Documented limit | What happens past it |
|---|---|---|
| Claude Code | Skill listing budget of 1% of the model's context window. Each skill's description plus when_to_use text is capped at 1,536 characters. | Every skill name stays listed. Descriptions are dropped, starting with the skills you use least, and a warning goes to the debug log. |
| Codex | Skill list uses at most 2% of the model's context window, or 8,000 characters when the window size is unknown. | Codex shortens descriptions first. For large skill sets it may leave some skills out of the list and show a warning. |
| Claude API | Up to 20 skills per request. Total upload under 30 MB uncompressed. | The request can't include more than 20 skills. |
| claude.ai | No number of skills documented. | Toggle skills on or off in Customize > Skills. Disabled skills aren't available to Claude. |
| VS Code (GitHub Copilot) | No number or budget documented. | Its docs say the three-level loading lets you install many skills without consuming context. |
Both budgets can be changed. In Claude Code, set skillListingBudgetFraction (for example 0.02 for 2%), or set the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable to a fixed number of characters. The 1,536-character cap per skill is the skillListingMaxDescChars setting. In Codex, set skills.max_context_tokens, up to 10,000 tokens. A bigger budget means more of your context goes to the listing, so it's usually better to trim the list first.
When too many skills hurt triggering
The agent decides whether to use a skill by matching your request against its description. Anthropic's best-practices guide says Claude uses the description "to choose the right Skill from potentially 100+ available Skills". That makes the description the part of a skill you can least afford to lose.
An overflowing listing removes exactly that. Claude Code's docs say dropping descriptions "removes the keywords Claude needs to match your request". Codex shortens descriptions, so the end of a long one is cut. The symptom is a skill that worked when you had ten installed and stops firing when you have two hundred, even though nothing in it changed.
Two other costs grow with the count. First, the listing competes with everything else in the context window, which Anthropic calls "a public good": your conversation, files and other instructions all share it. Second, skills that cover the same job with similar descriptions give the agent two near-identical matches, and it may pick the one you didn't want. If a skill isn't firing, our guide Skill Not Triggering? Fixes for Claude Code, Cursor & Codex covers the other causes.
How to see what your skills cost
• Claude Code: run /context. Its Skills row shows the listing's size after the budget is applied, so it matches what the model receives (from v2.1.196; older versions over-counted). Run /doctor for an estimate of the listing's cost and its biggest contributors.
• Claude Code: run /skill-doctor to see what each skill costs and how often it is used. It flags skills in the listing that have never been invoked and says where to turn them off.
• Codex: run /skills to see what is installed, and watch for the warning that some skills were left out of the list.
• Before you install: Skill Store 33 shows an approximate token size on each skill's page, so you can see how big a skill is before you add it.
How to trim your skill list
1. Turn off skills you don't use. In Claude Code, open /skills, highlight a skill and press Space to cycle its state, or set it in the skillOverrides setting: "off" hides it completely, "name-only" lists it without a description, and "user-invocable-only" keeps it in the / menu but out of the listing. In Codex, add a [[skills.config]] entry with the skill's path and enabled = false to ~/.codex/config.toml, then restart Codex.
2. Make manual-only skills manual. If you only ever call a skill by name, add disable-model-invocation: true to its frontmatter. In Claude Code, the description then stays out of context until you invoke it. VS Code supports the same field. In Codex, set allow_implicit_invocation: false under policy in the skill's agents/openai.yaml, and $skill-name still works.
3. Shorten descriptions, and lead with the use case. The spec allows 1,024 characters, but a short description that names the task and the words people actually type matches better than a long one, and it survives truncation.
4. Move bulk out of SKILL.md. Anthropic recommends keeping the body under 500 lines. Put long reference material in separate files and point to them from SKILL.md: they cost nothing until the agent reads them.
5. Scope skills to projects. A skill in your personal folder (~/.claude/skills/ or ~/.agents/skills/) loads in every project. One that only matters to one repo belongs in that repo's .claude/skills/ or .agents/skills/ folder.
6. Fetch skills when needed instead of installing them all. An agent connected to an MCP server that serves skills can look one up when a task comes up, so the skill only enters context when it's needed. Our guide How to Load Agent Skills from an MCP Server (SEP-2640) explains the options, and Skill Store 33's server below works this way for search.
FAQ
Is there a maximum number of agent skills I can install?
Claude Code and Codex set no fixed number. They cap the space the skill listing can take instead: by default 1% of the model's context window in Claude Code and 2% in Codex. The Claude API allows up to 20 skills per request.
How many tokens does an agent skill use?
Anthropic puts the always-loaded part, a skill's name and description, at about 100 tokens per skill. The SKILL.md body (Anthropic recommends under 5,000 tokens) loads only when the skill is used, and bundled files load only when read.
Do skills I never use still cost tokens?
Yes, a little. Every skill in the listing adds its name and description to the context on every turn, used or not. A skill set to manual-only (disable-model-invocation: true) keeps its description out of the listing in Claude Code.
Why does my agent ignore some skills when I have a lot installed?
When the listing goes over its budget, Claude Code drops some descriptions and Codex shortens them, and may leave some skills out. Without the description, the agent has fewer words to match your request against.
Let your agent search Skill Store 33
Skill Store 33 runs a public MCP server at https://mcp.ss33.ai. Connect it once and your agent can search about 60,000 skills by task, read what each one does, and fetch the one that fits. In Claude Code, run:
claude mcp add --transport http skill-store https://mcp.ss33.ai
Without an account your agent gets 5 searches a minute. A free account gives you a key with 60 searches a minute: create one on your account page, then add it to the connection as an Authorization: Bearer <key> header.
Sources
• Anthropic, Agent Skills overview (token cost table, claude.ai): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
• Anthropic, Skill authoring best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
• Anthropic, Using Agent Skills with the API: https://platform.claude.com/docs/en/build-with-claude/skills-guide
• Claude Code, Skills (listing budget, /skill-doctor, skillOverrides, compaction): https://code.claude.com/docs/en/skills
• Claude Help Center, Using Skills in Claude: https://support.claude.com/en/articles/12512180-using-skills-in-claude
• Codex, Build skills: https://learn.chatgpt.com/docs/build-skills
• VS Code, Agent Skills: https://code.visualstudio.com/docs/copilot/customization/agent-skills
• Agent Skills specification: https://agentskills.io/specification
This article was created with the help of AI (AI-Assisted). Every config key and command was checked against the official docs in the Sources list. ReadyAI is accountable for the content.