---
title: "Where your skill lives changes how it behaves"
description: "Claude Code skills exist at three scopes: project-level .claude/skills, user-level ~/.claude/skills, and distributable plugins. Learn precedence, conflict."
tldr: "Claude Code skills can be scoped to a project (.claude/skills), a user account (~/.claude/skills), or distributed as plugins. Project skills override user skills; plugins are loaded last. Choose project skills for team workflows, user skills for personal tools, and plugins for distribution."
url: "https://aigentic.blog/project-vs-user-vs-plugin-skills"
publishedAt: "2026-04-23T13:00:36.383Z"
updatedAt: "2026-04-23T13:00:36.383Z"
category: "skills"
tags: ["claude-code","skills","workflows","tooling","productivity"]
---

# Where your skill lives changes how it behaves

> Claude Code skills can be scoped to a project (.claude/skills), a user account (~/.claude/skills), or distributed as plugins. Project skills override user skills; plugins are loaded last. Choose project skills for team workflows, user skills for personal tools, and plugins for distribution.

A skill in Claude Code is a reusable, named instruction or workflow that Claude can invoke within the IDE. Skills encapsulate domain logic, tool integrations, or multi-step processes into discrete units that persist across sessions and can be shared or scoped to specific contexts. Claude Code supports three skill scopes, each with its own lifecycle, precedence rules, and intended use case: project-level skills stored in `.claude/skills/`, user-level skills in `~/.claude/skills/`, and plugin skills distributed through package managers or registries.

Understanding the scope hierarchy and when to use each is essential for building maintainable, collaborative workflows. Scope conflicts are resolved by precedence: project skills override user skills, and both are overridden by plugin skills loaded at runtime. This post breaks down the three scopes, their trade-offs, and the decision framework for choosing the right one.

## Project-level skills: team and repository workflows

Project-level skills live in `.claude/skills/` at the root of a repository. They are version-controlled alongside code, making them part of the repository's persistent state. Any developer who clones the repo inherits the same skill definitions.

Each skill is a YAML or JSON file with a `name` field, `description`, and a `triggers` section that defines when Claude should invoke it. Project skills are ideal for workflows specific to a codebase: linting rules, deployment procedures, testing patterns, or domain-specific code generation. Because they are checked into version control, they can be reviewed in pull requests, updated in lockstep with code changes, and enforced across a team.

The lifecycle of a project skill is tied to the repository. When a developer checks out a branch, the skills on that branch are available. When a skill is deleted or modified, the change is tracked in git history. This makes project skills the right choice for:

- Standardized workflows that all team members must follow
- Skills that evolve with the codebase (e.g., a skill that generates API docs for a specific schema)
- Onboarding: new developers inherit the team's skill set automatically
- Audit and compliance: skill definitions are part of the repository record

The trade-off is that project skills require repository access and coordination. A developer cannot add a project skill without write access to the repo, and changes must go through the normal review process.

## User-level skills: personal toolkit and cross-project reuse

User-level skills live in `~/.claude/skills/` on the developer's machine. They are not version-controlled and are not shared with other developers unless explicitly exported. User skills persist across all projects and sessions on that machine.

User skills are ideal for personal workflows that apply across multiple repositories: code formatting preferences, custom linting rules, personal documentation templates, or integrations with external tools (e.g., a skill that logs code changes to a personal wiki). Because they are local and not shared, they can be experimental or idiosyncratic without affecting teammates.

The lifecycle of a user skill is independent of any repository. A developer can add, modify, or delete a user skill at any time. If the developer switches machines, user skills do not automatically transfer; they must be manually exported or re-created. This makes user skills the right choice for:

- Personal productivity tools that don't need to be shared
- Experimental workflows before they are promoted to project or plugin scope
- Cross-project utilities that are too niche for a plugin
- Tools that depend on local environment variables or machine-specific configuration

The trade-off is isolation. User skills are not discoverable by teammates, and there is no central record of what skills exist across a team. If a user skill is valuable, it may need to be migrated to project or plugin scope to be shared.

## Plugin skills: distribution and ecosystem

Plugin skills are distributed through package managers, registries, or direct installation. They are not stored in `.claude/skills/` or `~/.claude/skills/` but are loaded by Claude Code at runtime from a plugin manifest or package metadata.

Plugin skills are ideal for reusable, general-purpose workflows that benefit many users or teams: integrations with third-party APIs, language-specific linters, framework-specific generators, or domain-specific tools. Because they are packaged and versioned, they can be installed, updated, and removed like any other dependency.

The lifecycle of a plugin skill is managed by the plugin system. A developer installs a plugin (e.g., via npm, pip, or a Claude Code registry), and the skills defined in that plugin become available. Updates to the plugin are installed separately from the codebase. This makes plugin skills the right choice for:

- Reusable tools that benefit many teams or projects
- Integrations with external services or APIs
- Language or framework-specific tooling
- Skills that need to be versioned and updated independently of any single repository

The trade-off is complexity. Creating and distributing a plugin requires packaging, versioning, and maintenance. Plugin skills are also loaded last in the precedence order, so they can be overridden by project or user skills if needed.

## Precedence and conflict resolution

When multiple scopes define a skill with the same name, Claude Code resolves the conflict using a fixed precedence order:

1. Project-level skills (highest priority)
2. User-level skills
3. Plugin skills (lowest priority)

This means a project skill named `lint` will override a user skill or plugin skill with the same name. A user skill named `lint` will override a plugin skill named `lint`. This design allows teams to customize or disable plugin skills on a per-project basis without modifying the plugin itself.

Conflict resolution is deterministic and transparent. If a skill is shadowed by a higher-priority skill, Claude Code will indicate which version is active. Developers can inspect the skill definition to understand which scope is providing it.

## Comparison table

| Aspect | Project | User | Plugin |
|--------|---------|------|--------|
| Storage | `.claude/skills/` in repo | `~/.claude/skills/` on machine | Package manager or registry |
| Version control | Yes, part of git history | No, local only | Yes, via package versioning |
| Scope | All developers on the repo | Single developer | All users who install the plugin |
| Lifecycle | Tied to repository branches | Independent of repositories | Independent, managed by plugin system |
| Precedence | Highest | Medium | Lowest |
| Use case | Team workflows, standards | Personal tools, experiments | Reusable, distributable tools |
| Discoverability | High (in repo) | Low (local only) | Medium (registry or docs) |
| Maintenance | Reviewed in pull requests | Self-managed | Managed by plugin author |

## Decision framework

Choosing the right scope depends on three questions:

1. Who needs this skill? If the answer is "the whole team", use project scope. If it is "just me", use user scope. If it is "many teams or the public", use plugin scope.
2. Does this skill need to evolve with the codebase? If yes, use project scope. If it is stable or independent, use user or plugin scope.
3. Is this skill experimental or stable? If experimental, start with user scope and promote to project or plugin scope once it is proven.

A common pattern is to start with a user skill, test it across a few projects, and then either promote it to project scope (if it is team-specific) or package it as a plugin (if it is general-purpose).

## Takeaways

Project-level skills in `.claude/skills/` are version-controlled and shared across a team, making them ideal for standardized workflows and onboarding. User-level skills in `~/.claude/skills/` are local and personal, suited for cross-project utilities and experiments. Plugin skills are distributed and reusable, designed for general-purpose tools that benefit many users. Precedence is fixed: project skills override user skills, which override plugin skills. Choose the scope based on who needs the skill, whether it evolves with the codebase, and whether it is experimental or stable. Start with user scope for exploration, promote to project scope for team adoption, and package as a plugin for broad distribution.

## Further reading

- [Anthropic Claude Code documentation](https://docs.anthropic.com) for official skill syntax and configuration.
- [anthropics/skills GitHub repository](https://github.com/anthropics/skills) for example skill definitions and best practices.
- [Claude Code release notes](https://docs.anthropic.com/release-notes) for updates to skill scoping and precedence rules.
- [YAML specification](https://yaml.org/spec/) for skill file format reference.
- [Semantic versioning](https://semver.org) for plugin versioning conventions.

## Frequently asked

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

The project skill takes precedence and is used. Project-level skills override user-level skills by design, allowing teams to customize or disable user skills on a per-project basis. Claude Code will indicate which version is active.

### Can I share a user skill with my team without making it a plugin?

Not automatically. User skills are local to your machine. To share with teammates, you can export the skill file and ask them to copy it to their ~/.claude/skills/ directory, or promote it to project scope by moving it to .claude/skills/ in the repository.

### Do plugin skills need to be installed for every project?

No. Plugin skills are installed once at the user or system level and are available across all projects. However, a project skill or user skill with the same name will override a plugin skill, allowing per-project customization.

### How do I migrate a user skill to project scope?

Copy the skill file from ~/.claude/skills/ to .claude/skills/ in your repository, commit it to git, and push. All developers who clone the repo will then have access to the skill. Remove it from ~/.claude/skills/ if you no longer need the personal version.

### Can I version control user skills?

User skills are stored locally and are not version-controlled by default. If you want to track changes, you can manually commit them to a personal dotfiles repository or export them as part of your development environment setup.