Claude Code loads skills from two locations. The folder you choose determines who gets the skill and when Claude sees it. At AEM, install scope is the first decision in every skill engineering commission.

TL;DR: Project-level skills go in .claude/skills/ inside your project directory. They commit to git, load automatically when a teammate clones the repo, and exist only inside that project. User-level skills go in ~/.claude/skills/ in your home directory. They load in every Claude Code session on your machine, across every project you open.

What does install location actually control?

Install location determines scope, not capability. A project-level and a user-level skill with identical SKILL.md files behave the same once loaded. The difference is which sessions they appear in: project-level loads only inside that specific project directory, while user-level loads in every Claude Code session on your machine. Claude's standard context window is 200,000 tokens (Claude Help Center, Anthropic, 2025), and skill descriptions pre-load at startup so Claude knows what tools are available without consuming budget for full instructions.

Project-level path: .claude/skills/your-skill-name/SKILL.md

This directory lives inside your project. Commit it to git and every teammate who clones the repo gets the skill with no additional setup. No Slack messages with zip files. No manual install steps in the README. The skill is part of the codebase, versioned alongside the code it supports.

Project-level skills load only when Claude Code opens that specific project. Open a different project, and they disappear. A deployment skill tuned to your staging environment should not appear when you are editing a personal side project.

User-level path: ~/.claude/skills/your-skill-name/SKILL.md

This directory lives in your home folder. Claude Code loads it in every session: work projects, personal repos, quick scripts, all of them. User-level skills are your personal toolbox that travels with your machine.

Each skill description costs roughly 100 tokens at session startup, loaded into Claude's context as part of the metadata layer (Claude Code architecture docs, 2024). This cost is identical regardless of install level.

When should you use project-level skills?

Use project-level when the skill knows something specific to the codebase. This covers skills that reference your team's naming conventions, branching format, or staging environment. Project-level skills commit to git, so every teammate who clones the repo gets the skill automatically, with no manual install step. Because 93% of professional developers use Git as their primary version control system (Stack Overflow Developer Survey, 2024), project-level skills travel automatically to every machine that clones the repo, with no manual install required.

  • A code review skill that enforces your team's naming conventions.
  • A commit message generator formatted for your branching strategy (JIRA-1234/fix-payment-validation).
  • A documentation skill that requires specific JSDoc fields your project uses.

These skills are useless outside the project context. There is no reason to install them globally.

The more important argument for project-level on team work: version control through normal code review. When the skill lives in the repo, updating it means opening a PR. Teammates review the change. That review process is quality control for the skill itself, not overhead.

In Agent Engineer Master commissions, we see what happens when teams skip this. A developer builds a strong review skill, installs it at user level, and distributes a copy to teammates via Slack. Six weeks later, each person has a slightly different version. The team's code review quality is consistent in name only, and no one knows why it keeps diverging.

When should you use user-level skills?

Use user-level when the skill is about your workflow, not any specific project. A debugging checklist, a function annotation habit, a research template: these are personal patterns that apply on every codebase. The skill lives in your home directory and loads in every Claude Code session you open. Developers with AI coding assistance complete tasks 55.8% faster than those without (Peng et al., arXiv 2302.06590, 2023). User-level is the right home for these patterns.

  • A skill that annotates complex functions before you read them.
  • A debugging checklist you run identically on every codebase.
  • A research skill for summarizing technical documents.

These are personal productivity patterns, not project assets. They should follow you everywhere.

"Developers don't adopt AI tools because they're impressive, they adopt them because they reduce friction on tasks they repeat every day." -- Marc Bara, AI product consultant (2024)

A practical test: explain the skill to a new teammate. If they say "I'd want that too," it belongs at project level. If they say "that's a personal thing," it belongs at user level. The distinction is usually obvious in practice.

What happens when both levels define a skill with the same name?

Project wins. Always. If your project has code-review/SKILL.md and your home directory also has code-review/SKILL.md, Claude Code loads the project version. The user-level version is silently ignored for the duration of that session. This is intentional: project conventions should override personal defaults without requiring any manual configuration. Each skill description is capped at 1,536 characters in the context index (code.claude.com documentation, 2025), and the project entry occupies that slot.

This precedence is correct. Project conventions should override personal defaults. If your team runs a stricter review standard than your personal default, the project skill should win without you needing to think about it.

Most people learn this the hard way when their skill "stops working" after joining a new project. It didn't stop working. It was overridden by a project-level version with the same name.

The fix: run /skills in any Claude Code session. The output lists every loaded skill with its source directory. One command shows you exactly what is loaded and where it came from.

How do user-level skills fit into version control?

They don't, unless you set it up yourself. Skills in ~/.claude/skills/ sit outside any project repo, so Git never touches them. There is no automatic history, no rollback, and no backup when you move to a new machine. If you delete a user-level skill, it is gone. LLM performance degrades over 30% when relevant content appears mid-context (Liu et al., arXiv 2307.03172, 2023). That makes well-maintained, version-controlled skill files worth the setup effort.

No history, no rollback, no automatic backup. If you delete ~/.claude/skills/my-skill/, it is gone.

The standard pattern for developers who want version control on personal skills: keep user-level skills in a private dotfiles repo and symlink them into ~/.claude/skills/. You get full history, replication in one git clone when moving to a new machine, and clean checkpoints before making major changes.

For teams, the simpler answer: use project-level for anything shared, and treat user-level as genuinely personal. Team members get project skills automatically on clone. User-level skills require each person to install manually, which is the right friction for personal tools.

One thing install level does not control: security isolation. Both project-level and user-level skills run with the same permissions inside a Claude Code session. Install location determines loading scope, not access control.

For the mechanics of how Claude loads all installed skills at session start, see How Do Skills Load Into Claude's Context Window?. For guidance on how many skills to maintain across both levels before performance starts to suffer, see How Many Claude Code Skills Should I Have in One Project?.

FAQ: Project-level vs user-level skills

For most Claude Code setups, the rule is straightforward: project-level skills are for anything the team shares, user-level skills are for personal workflow. Both levels load in every session. Project versions override user-level versions with the same name. Install path determines scope, not behavior or permissions.

Can I install the same skill at both levels? Yes. The project version takes precedence inside that project. Outside any project, Claude loads only the user-level version. This is a reasonable pattern if you have a generic personal version and a stricter project-specific version of the same skill type.

Do user-level skills load when I'm inside a project? Yes. Both levels load in every session. Project-level skills do not replace user-level ones. They only override user-level skills with matching names.

How do I see which skills are currently loaded and where they came from? Run /skills inside any Claude Code session. The output shows each loaded skill and the directory it came from.

If I have 8 user-level skills and my project has 6 more, is that too many? At 14 total, you are well inside the performant range. The threshold where curation starts to matter is around 30 skills. The early symptoms above that count are missed triggers and reduced instruction-following precision, not crashes.

Can I stop a user-level skill from loading inside one specific project? Not with a direct setting. The cleanest workaround: install a project-level skill with the same name. The project version overrides the user-level version automatically inside that project.

What if ~/.claude/skills/ does not exist yet? Create it: mkdir -p ~/.claude/skills. Claude Code creates this directory automatically when you first install a user-level skill through official tooling, but creating it manually works fine.

Does install level affect how quickly Claude Code starts? Marginally. Each skill description adds roughly 100 tokens to the session start context, regardless of install level. At low skill counts (under 30), the startup difference is not perceptible.

Last updated: 2026-05-02