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. In a monorepo it also picks up .claude/skills/ from every parent folder up to the repository root, so skills defined at the root work in every package.
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, skill-creator, or doc-coauthoring 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 --skill frontend-design -g -y
npx skills add anthropics/skills --skill skill-creator -g -y
npx skills add anthropics/skills --skill doc-coauthoring -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 want changes reviewed. A skill in the repo changes through commits and pull requests, so the team sees and approves every edit to the instructions Claude follows.
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 --skill webapp-testing -y
# Or write your own team skill
mkdir -p .claude/skills/code-review && $EDITOR .claude/skills/code-review/SKILL.md
# Then commit the folder
git add .claude/skills/
git commit -m "chore: add shared team skills"
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 |
| Change history | Per machine | Git history, reviewed in pull requests |
| Same name in both | Wins | Ignored where a personal copy exists |
| Install flag | -g | (none) |
How to check what's installed where
Inside Claude Code, type /: every skill Claude can see right now appears in the list, whatever its scope. With the skills CLI you can list each scope separately:
# Skills installed in the current project
npx skills list
# Only global skills
npx skills ls -g
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: share code-review skill with the team"
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 --skill frontend-design -y
# Commit the result
git add .claude/skills/frontend-design
git commit -m "chore: add frontend-design skill for team use"
Then remove your global copy (npx skills remove --global <name>, or delete the folder in ~/.claude/skills/). If you keep both under the same name, your personal copy wins on your machine and you won't see the version your team uses.
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?
Your personal (global) skill wins. Claude Code resolves name clashes as enterprise over personal, and personal over project: with deploy in both ~/.claude/skills/ and the project's .claude/skills/, /deploy runs the personal one. Give team skills names that won't collide with personal ones.
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?
Not under the same name: when a personal and a project skill share a name, Claude Code runs the personal one, so the project copy is ignored on your machine. If the team needs its own version, give it its own name (for example team-deploy) and commit it.
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.