Most projects work well with 10-25 active skills. Below 10, you are probably leaving repeated workflows un-automated. Above 30, skill discovery becomes unreliable and the library needs curation to stay effective. The number is secondary. The quality of each skill is what drives outcomes.

TL;DR: Target 10-25 active skills per project. Each skill description consumes approximately 100 tokens at session startup. Above 30 skills, descriptions compete for classifier attention and false-trigger rates increase. Agent Engineer Master ships client skill libraries with a maximum of 25 active project skills, supplemented by 5-10 user-level skills for cross-project tasks. Curation at the 30-skill threshold is not bureaucracy. It is performance maintenance.

Is there a hard limit on how many skills I can install?

No hard limit exists. Claude Code loads any number of skills from .claude/skills/. The practical ceiling is set by two factors: token budget and classifier reliability.

Token budget. Each skill's description consumes approximately 100 tokens at session startup (AEM internal measurement, 2026). A project with 40 active skills uses 4,000 tokens of startup budget just on skill metadata. The total system context budget sits around 15,000 characters. At 40 skills, metadata alone consumes roughly 27% of that budget before any conversation context loads.

Classifier reliability. Claude matches incoming requests to skills based on description similarity. When more descriptions are loaded, more of them are plausible matches for any given request. Above approximately 30 skills, the matching process becomes less precise, with adjacent-but-wrong skills triggering at higher rates and correct skills triggering less consistently.

Both constraints are soft: you will not hit a wall at exactly skill 31. You will notice gradual degradation in matching accuracy and increased context overhead as the count grows past 30.

When do I start noticing problems from too many skills?

Four observable signals that your skill count needs attention:

Skills triggering on the wrong prompts. A code review skill activates when you ask for a PR description. A documentation skill activates when you ask for a commit message. These false triggers mean descriptions are too similar or too broad. More skills mean more description overlap.

The /skills list is too long to scan quickly. If you need to scroll to find a skill, team members will stop looking and use prompts instead. A skill library that requires a lookup table to navigate has defeated its own purpose.

Team members bypass skills for prompts. The most reliable signal. When the people the skills were built for stop using them, the library has a usability problem. Adding more skills makes this worse, not better.

Session context feels crowded. Tasks that ran well before now produce shorter, less complete outputs. The skill descriptions are consuming budget that used to go to conversation context.

"The single biggest predictor of whether an agent works reliably is whether the instructions are written as a closed spec, not an open suggestion." — Boris Cherny, TypeScript compiler team, Anthropic (2024)

The same principle applies to the library: a small library of precisely scoped skills outperforms a large library of broadly scoped ones. Twenty skills with tight, specific descriptions and clear output contracts will consistently outperform 50 skills with vague descriptions and overlapping triggering conditions.

What is the right number for a typical project?

The ranges by project type, from commission data at Agent Engineer Master:

Solo developer: 8-15 skills. The core developer workflows (commit formatter, PR description, code review, documentation generator) plus 4-6 project-specific skills. No more than 5 user-level skills to keep the total session count below 20.

Small team (3-8 developers): 12-20 project-level skills shared via the repo. These should cover the team's recurring workflows: code review with team-specific criteria, PR description format, release notes, incident response, architecture review. User-level skills are individual and vary by developer.

Larger teams or complex projects: 20-25 project-level skills. At this scale, the skills benefit from a named owner per skill who is responsible for maintenance and quality. Without ownership, skills go stale.

In every case, the number that matters is not the total installed count but the count of skills that run weekly. A skill that last ran three months ago belongs in an archive folder, not in the active library.

How do I know when to retire a skill vs keep it?

Use a three-month rule. Any skill that has not been invoked in the last 3 months is a candidate for archiving. The test: would you miss it if it were gone? If the answer is no, move it to .claude/skills/_archive/skill-name/SKILL.md. Claude Code does not load skills from nested subdirectories, so archiving inside a subfolder removes it from startup cost without deleting it.

For skills that see irregular but important use (quarterly architecture review, annual dependency audit), keep them at user level where they are available but not consuming project-specific context budget.

The opposite signal: a skill that runs 20+ times per week is a candidate for improvement, not archiving. High usage means high ROI from quality investment. If a skill runs that frequently and still has a mediocre output contract, every run is leaving value on the table.

For more on organizing and maintaining a skill library, see How Do I Organize Multiple Skills in a Project? and How Do Skills Load Into Claude's Context Window?.

Frequently Asked Questions

Does the 30-skill threshold apply to combined user-level plus project-level skills? Yes. Claude loads all skill descriptions into the same context window at startup, regardless of level. A project with 15 project-level skills and 20 user-level skills has 35 skills loaded in that session. The 100-token-per-skill cost and the classifier reliability effects apply to the combined count.

Should I start with 5 skills or 20 skills when setting up a new project? Start with 5 and add from there. The first skills to build are the ones that address your highest-frequency friction: commit formatting, PR descriptions, code review. Get those right before expanding. A skill library built incrementally from real usage is more useful than one designed from scratch to be comprehensive.

What happens if I delete a skill from .claude/skills/ while a session is running? The skill stays available for the rest of the session. Claude loaded it at startup and holds it in context. The deletion takes effect the next session. This is expected behavior, not a bug.

Can I have different skill sets for different branches of the same project? Not directly. Claude Code loads skills from the .claude/skills/ directory of the repo root, not from branch-specific directories. Teams that need branch-specific skill variants use naming conventions (skill-name-v2) or conditional logic within a skill's steps.

Is 5 skills too few? For a solo developer working on a simple project, 5 focused skills can be sufficient and may be better than 20 mediocre ones. The test is whether each skill earns its context cost through regular use. Five well-built, frequently used skills deliver more value than 25 vague ones that rarely trigger correctly.

Last updated: 2026-05-01