The Claude Code skill discovery classifier treats project-level and user-level skills equally. AEM's skill engineering work across production libraries confirms this: both levels appear in the system prompt at session startup, both consume the same ~100 tokens per skill (Claude Code documentation, 2025), and both compete for the same skill-listing character budget, which scales dynamically with the context window and defaults to roughly 15,000 characters (Claude Code documentation, 2025). The classifier does not check your skill's passport. It reads the description.

TL;DR: Installation level does not directly affect discovery reliability. The reliability differences appear indirectly: the combined size of both libraries can push the total past the degradation threshold, naming collisions between personal workflow skills and project-specific skills create trigger conflicts, and users rarely audit the combined library the way they audit one level in isolation.

Does the Discovery Classifier Treat Project-Level and User-Level Skills Differently?

No. Both are loaded into the system prompt using the same mechanism, and both become available for the same classifier evaluation on each incoming prompt. The classifier sees a flat list of skill descriptions regardless of their source directory. Installation path is invisible to the classifier at evaluation time.

What does differ is the loading order. Project-level skills typically load before user-level skills in the system prompt context (source: Claude Code official documentation, 2024). Based on the "Lost in the Middle" research by Nelson Liu et al. (ArXiv 2307.03172, 2023), earlier context positions receive more consistent attention from large language models. A project-level skill that appears at position 5 in the context has slightly more reliable trigger attention than a user-level skill that appears at position 22.

In a small library of 10-15 total skills, this ordering difference is negligible. In a library of 30-40 total skills approaching the degradation threshold, earlier-loaded skills maintain trigger reliability more consistently.

Where Do Measurable Reliability Differences Actually Appear?

Three mechanisms produce measurable reliability differences in practice: combined library size pushing the total skill count past the degradation threshold, naming collisions between levels loading duplicate descriptions into the classifier at the same time, and description overlap between personal and project skills compounding false-positive activation rates.

Combined library size: If a developer has 18 user-level skills installed personally and works on a project with 15 project-level skills, the session starts with 33 skills total. The degradation threshold sits at 25–30 skills, above which description truncation and classifier inconsistency increase measurably (AEM production library audits, 2025). The combined library is already in the degradation zone even though neither individual library exceeds it.

In team environments we've audited, this is the most common reliability problem we find: each developer's user-level library is sized appropriately at 12-15 skills, each project has 10-15 project-level skills, and the combined count per session lands between 22-30. No one noticed because neither library was reviewed as a combined unit.

Naming collisions across levels: A developer might have a personal user-level skill named "reviewing-code" for their own coding workflow and be on a project that has a project-level skill also named "reviewing-code" with different instructions. Claude Code resolves the collision by loading both, which creates a split description signal in the classifier. The result is inconsistent activation: sometimes the personal skill wins, sometimes the project skill wins, and sometimes both half-fire.

Description overlap without naming collision: Even without identical names, a personal "writing-clean-commits" skill and a project "formatting-commit-messages" skill can have descriptions that the classifier scores similarly for the same prompts. At library sizes above 25, overlapping user-level and project-level descriptions compound the false-positive rate measurably (AEM production library audits, 2025).

"When you give a model an explicit output format with examples, consistency goes from ~60% to over 95% in our benchmarks." — Addy Osmani, Engineering Director, Google Chrome (2024)

The consistency principle applies here. A combined library where descriptions are explicit and non-overlapping produces consistent classifier results. A combined library where user-level and project-level descriptions overlap produces the 60% consistency baseline.

How Should You Manage the Combined Library Across Both Levels?

Treat the combined library as the operational unit: audit both levels together quarterly, assign skills to levels by scope rather than convenience, and name user-level skills specifically enough that they cannot collide with project-level naming patterns. These three practices address all three reliability failure modes.

  • Audit combined, not separately: The combined library is the operational library. Reviewing each level in isolation misses the interaction effects. Once a quarter, list all active skills from both levels and run the combined character count, check for naming collisions, and check for description overlap.
  • Assign tasks to levels deliberately: Project-level skills cover everything specific to this project's conventions, quality bar, and tooling. User-level skills cover your personal workflow across projects: how you structure commits, how you prefer to see code explanations, which output formats you work with fastest. When a skill's scope is ambiguous, default to project level.
  • Name skills with level context in mind: User-level skill names should be personal-workflow-specific enough that they do not collide with project naming patterns. "my-commit-format" is unambiguous. "code-reviewer" collides with half the project-level skill libraries in existence.

This combined-library approach won't help if the reliability problem comes from individual skill description quality rather than library size or naming collisions: a poorly written description that matches too broadly or too narrowly is a description problem, not an installation-level problem, and requires rewriting the skill rather than reorganising the library.

For the mechanics of what each level loads and when, see What's the Difference Between Project-Level and User-Level Skills?. For the discovery classifier behavior that applies to both levels equally, see How Does Claude's Internal Skill Discovery Mechanism Work?.

Which Level Should You Use for Which Type of Skill?

The deciding test is audience: if another developer joining your project would benefit from the skill, it belongs at project level. If only you would benefit, it belongs at user level. This single question resolves the ambiguity in most cases and keeps the combined library scoped correctly from the start.

Project-level (.claude/skills/ in the project directory):

  • Coding conventions specific to this repository
  • PR format requirements for this team
  • Client brand voice or tone rules for this client's deliverables
  • Deployment pipeline constraints unique to this project
  • Quality bar definitions for this product

User-level (~/.claude/skills/ in the home directory):

  • Personal commit message format preferences
  • How you prefer code explained (level of detail, which abstractions to use)
  • Output format preferences (tables vs. prose, numbered lists vs. bullets)
  • Cross-project personal workflow habits (how you like to start debugging sessions)

The test: if another developer joining your project would benefit from this skill, it belongs at project level. If only you would benefit, it belongs at user level.

This pattern applies when you control both levels. For enterprise setups with managed user-level skills pushed to developer machines by IT, the "personal workflow" category expands to "team member workflow" and the same scoping logic still applies.

Frequently Asked Questions

For libraries under 25 total skills, installation level creates no measurable reliability difference: both levels load with equal priority and the classifier treats all descriptions as a flat list. The common failure scenarios involve naming collisions, combined library size crossing the degradation threshold, and the absence of any built-in priority system for conflict resolution between levels.

What happens if a user-level skill and a project-level skill have the same name?

Both load into the system prompt. Claude Code does not deduplicate by name across installation levels. The classifier sees two descriptions under similar (or identical) names and produces inconsistent activation. The fix is renaming one skill to remove the collision before the next session.

Does project-level take priority over user-level when there is a conflict?

There is no built-in priority system for the classifier. Project-level skills appear earlier in the context based on load order, which gives them a marginal attention advantage based on context position research, but this is not a formal override mechanism. Explicit description differentiation is the correct way to resolve conflicts, not relying on load order.

Can I install the same skill at both project and user level for different behavior?

You can, but it creates the naming collision problem: both skills load simultaneously, the classifier sees two descriptions under the same or similar name, and activation becomes inconsistent. If you need different behavior in the same skill for different contexts, use conditional logic within one skill rather than duplicating it across levels.

How do I see all skills from both levels combined?

The /skills command in Claude Code lists all currently loaded skills in the session. This includes both project-level and user-level skills. The list does not indicate which level each skill came from, but it shows the full active library you are operating against.

Does the token cost differ between project-level and user-level skills?

No. The metadata token cost per skill is identical regardless of installation level. Both consume approximately 100 tokens per skill at startup. The combined library's total token cost is simply the sum of all installed skills from both levels. See How Does the 100-Token Per Skill Metadata Cost Shape Library Architecture at Scale? for the full cost model.

If I archive a user-level skill, does it stop loading in project sessions?

Yes. Archiving a skill means removing it from the active skills directory. For user-level skills, moving the skill folder out of ~/.claude/skills/ to an archive location removes it from all project sessions. It does not delete the skill file, so it can be restored when needed.

Last updated: 2026-05-04