The two scopes explained
When you install a Claude Code skill, it ends up in one of two places on your filesystem. That location determines exactly when Claude can see and load it.
~/.claude/skills/
Global skills live in your home directory under ~/.claude/skills/. Because this path exists outside any project, Claude loads these skills in every session on your machine — regardless of which directory or repo you are working in.
Think of global skills as personal productivity tools you carry everywhere, similar to dotfiles or shell aliases.
.claude/skills/ (in repo root)
Project-level skills live inside your repository at .claude/skills/. Claude only loads them when running inside that specific project directory.
Because the folder is inside the repo, you can commit it to Git. Every contributor who opens the project gets the same skills without any manual setup on their end.
When to install globally
Global is the right default for most solo developers. Choose it when:
- You use the skill across multiple projects. Skills like frontend-design, systematic-debugging, or brainstorming are general enough to be useful everywhere. Installing them globally means you never need to reinstall per project.
- The skill is tied to your personal workflow, not a codebase. Skills that match the way you think and write — note-taking conventions, preferred refactoring style — belong in your global config.
- You are the only developer. On solo projects there is no team to keep in sync, so the simpler global install is sufficient.
- You are evaluating a skill before deciding whether to commit it to a project. Install globally first, use it for a week, then promote it to project level if you want teammates to share it.
How to install globally
Pass the -g flag to the Skills CLI:
# Install globally — available in every project
npx skills add anthropics/skills@frontend-design -g -y
npx skills add anthropics/skills@systematic-debugging -g -y
npx skills add anthropics/skills@brainstorming -g -y
When to install at project level
Project-level installs shine in team and production environments. Choose project scope when:
- The skill is team-shared and should be consistent. A code-review skill that enforces your team's conventions, or a security-review skill tuned to your threat model, should be the same for every developer. Committing it to the repo guarantees consistency.
- The skill is configured for your specific stack. A deploy skill that knows your Netlify site ID, your staging environment, or your monorepo structure is not portable — it only makes sense inside that repo.
- You want zero onboarding friction for new contributors. When a skill is in .claude/skills/ and committed, cloning the repo is all a new teammate needs to do. No manual install step, no Slack message saying "don't forget to install X".
- You need a pinned version. Project-level skills can hold a specific version of a skill while global installs keep up with updates. This is useful for regulated codebases where prompt behaviour must be audited and frozen.
How to install at project level
Run the install command from inside your project directory, without the -g flag:
# No -g flag = project-level install
npx skills add anthropics/skills@security-review -y
npx skills add anthropics/skills@code-review -y
# Then commit the folder
git add .claude/skills/
git commit -m "chore: add shared code-review skill"
Side-by-side comparison
A quick reference for the two scopes across the decisions that matter most:
| Property | Global | Project |
|---|---|---|
| Location | ~/.claude/skills/name/ | .claude/skills/name/ |
| Available in all projects | Yes | No — this repo only |
| Committed to Git | No | Yes (recommended) |
| Loaded automatically for teammates | No — each person installs their own | Yes — once committed |
| Ideal for | Personal productivity, cross-project tools | Team workflows, project-specific config |
| Version pinning | Harder — updates are per-machine | Easy — Git history is the version record |
| Install flag | -g | (none) |
How to check what's installed where
Run npx skills list from any directory to see all skills currently visible to Claude:
npx skills list
The output groups skills by scope. A typical result looks like this:
Global skills (~/.claude/skills/)
frontend-design v2.1.0 anthropics/skills
systematic-debugging v1.4.0 anthropics/skills
brainstorming v1.2.0 anthropics/skills
Project skills (.claude/skills/)
security-review v1.0.0 anthropics/skills
code-review v3.0.1 anthropics/skills
Skills listed under Global skills came from your ~/.claude/skills/ directory. Skills under Project skills came from the .claude/skills/ folder in your current working directory — they will not appear if you run npx skills list from a different project.
To inspect the filesystem directly:
# List global skills
ls ~/.claude/skills/
# List project skills (run from repo root)
ls .claude/skills/
Each skill is a folder containing at minimum a SKILL.md file. If the folder is missing or empty, Claude will not load that skill.
Migrating a skill from global to project
You evaluated a skill globally and now you want to lock it into a specific project for your team. There are two equivalent approaches:
Option A — Copy the folder manually
# Copy from global to project scope
mkdir -p .claude/skills/
cp -r ~/.claude/skills/code-review .claude/skills/code-review
# Commit it
git add .claude/skills/code-review
git commit -m "chore: pin code-review skill at project level"
Option B — Reinstall without the -g flag
This fetches the latest published version of the skill and installs it at project scope in one step:
# Reinstall at project level (no -g flag)
npx skills add anthropics/skills@code-review -y
# Commit the result
git add .claude/skills/code-review
git commit -m "chore: add code-review skill for team use"
After either approach, the project-level copy takes precedence over your global install when you are inside that repo. Your global install remains unchanged and continues to work in other projects.
For more on the install flow, see the full installation guide. For team setup recommendations, see Claude Code team setup.
FAQ
What happens if I have the same skill installed globally and in a project?
The project-level version takes precedence. When Claude loads skills, it checks .claude/skills/ first, then falls back to ~/.claude/skills/. This means you can override a global skill with a customised project version without touching your global install.
Should I gitignore .claude/skills/?
No — the whole point of project-level skills is to commit them so teammates get the same behaviour automatically. Only add .claude/skills/ to .gitignore if you are experimenting with skills you do not want shared.
Can I have different versions of the same skill at different scopes?
Yes. You can pin a specific version of a skill at project level while keeping a different (perhaps newer) version globally. The project version wins when you are inside that repo. This is especially useful when a skill update changes behaviour that your CI or review process depends on.
Does project scope affect teammates who don't have the skill globally?
No. Project-level skills committed to the repo are available to every contributor who clones it, regardless of what they have installed globally. This is the main advantage of project-level installs for team workflows — contributors get zero-setup access to the same skill set.