Skill scopes: personal vs project vs plugin vs managed

Why you'd careThe problem it solves

You wrote a skill on Friday, it worked, you told the team it was ready. Monday, two people say Claude never picks it up, and the nightly routine you scheduled reports the skill as not found. Nothing is broken. The file is sitting in ~/.claude/skills/ on your laptop, which is a location no other session can see. Cloud sessions, Cowork sessions and routines never read that folder: Cowork sessions get the skills enabled on your claude.ai account, and cloud sessions — routines included — get those plus whatever the repository or a plugin it declares brings with it, and nothing else. This is the actual answer to “how does my team get this”, it is a one-line decision, and it is usually got wrong by defaulting to the personal directory because that is the one the docs show first.

ConceptWhat it is

A skill is discovered by location. Claude Code walks a fixed set of roots when a session starts, reads the YAML frontmatter of every SKILL.md it finds, and puts each skill's name and description in front of the model. Scope is therefore not something you declare inside the file — it is entirely a consequence of which root the directory sits under.

There are seven roots, and four carry most of the weight. Personal: ~/.claude/skills/<name>/SKILL.md, available in every project on one machine and only that machine. Project: .claude/skills/<name>/SKILL.md inside the repository, committed to git, so every checkout and every session started from a checkout has it. Plugin: skills/<name>/SKILL.md inside a plugin directory, delivered to whoever installs that plugin and refreshed when the plugin updates. Managed: .claude/skills/<name>/SKILL.md inside the organisation's managed settings directory, installed by IT rather than by the user, so every user on that machine gets the skill; the same managed settings can also pin which marketplaces are trusted and which plugins are on, so a new machine arrives with them already enabled. The other three roots: nested <subdir>/.claude/skills/ directories, which load once Claude works on files there; the .claude/skills/ of a directory passed with --add-dir; and the skills enabled on your claude.ai account, which Cowork and cloud sessions load and a local session gets only after a sync into the reserved ~/.claude/skills/synced/.

Two consequences follow. Names collide across roots, and the harness resolves them two ways: enterprise beats personal and personal beats project, while other roots are qualified — plugin skills are addressed in the form plugin-name then skill-name, and a skill scoped to a subdirectory of a monorepo is listed with its path prefix — for example apps/web then deploy — with the most specific match winning when both a scoped and an unscoped variant of a name exist. And scope governs reach, not trust: committing a skill to a repo widens who can invoke it without narrowing what it is allowed to do.

How it worksThe mechanics

Discovery scans each root for immediate subdirectories containing a SKILL.md. In Claude Code no frontmatter key is required — name defaults to the directory name and description to the first non-empty line of the body — but the description is what the model reads when deciding whether to load the skill, and everything below the frontmatter stays on disk until it does.

~/.claude/skills/                 personal - this machine, every project
└── commit-style/
    └── SKILL.md

my-repo/
├── .claude/
│   └── skills/                   project - committed, travels with the repo
│       └── release-notes/
│           ├── SKILL.md
│           └── references/
│               └── format.md
└── src/

acme-plugin/
└── skills/                       plugin - ships to whoever installs it
    └── incident-review/
        └── SKILL.md

The frontmatter itself is small. The spec and every upload path require these two keys, Claude Code requires neither, and the rest are optional; in Claude Code the commonly used optional one, allowed-tools, pre-approves tools for the turn that invokes the skill rather than restricting them:

---
name: release-notes
description: Draft release notes from merged PRs since the last tag. Use when the user asks for a changelog, release notes, or what shipped.
---

For the managed scope, the managed settings directory lives outside the user's home directory so a user cannot quietly override it — on macOS under /Library/Application Support/ClaudeCode/, on Linux under /etc/claude-code/, and on Windows under C:\Program Files\ClaudeCode\ (the legacy ProgramData path is no longer read). It can carry skill bodies directly, in a .claude/skills/ folder inside that directory. It can also carry the marketplace and plugin entries that cause skills to be installed, so an org-wide rollout is either a folder IT deploys or a plugin question wearing a settings hat.

To check what a session actually resolved, ask Claude to list the skills available to it and compare the qualified names against the seven roots. That takes seconds and is the only reliable way to tell a discovery problem from a description problem.

At a glanceSee it

Four of the skill locations feed a session; a personal skill never reaches a fresh remote run.

Where it runsSurfaces and availability

The pattern is that scope is a harness idea rather than a Claude idea. It holds wherever the Claude Code harness runs — the terminal, the Agent SDK, and any model backend you point either at — and nowhere else. On every server-side surface a skill is an uploaded addressable object, not a directory that happens to be present. If the same behaviour has to work in a terminal and in a server-side agent, plan to maintain the content once and publish it twice, and write the body so it does not assume a filesystem it will not have.

ExampleIn the real world

A platform team writes a skill called db-migration. It encodes the house rules for schema changes: never drop a column in the same release that stops writing to it, always add the backfill job, always paste the estimated lock time into the PR description. The author builds it in ~/.claude/skills/db-migration/ and it works — ask for a migration and Claude produces one with the backfill and the lock estimate.

Two colleagues copy the folder. A third asks for a migration in the same repository and gets a bare ALTER TABLE. Worse, the scheduled routine that opens dependency-bump PRs overnight never applies the rules at all, because each run is a fresh remote session that never sees the author's laptop.

The author moves the directory to .claude/skills/db-migration/ and opens a PR. Now the rules arrive with the checkout: every teammate, every session started from CI, every scheduled run. When a second and third repository want the same rules, it moves once more — into a plugin published from an internal marketplace — so a fix lands in one place and the other repos pick it up on their next update instead of drifting into three slightly different copies.

Not thisWhat it is often confused with

• Not a permission boundaryscope decides who can discover a skill, not what it may do once loaded. Restricting behaviour is the job of the disallowed-tools frontmatter and of settings and hooks (allowed-tools grants tools rather than restricting them), and a committed project skill is no more sandboxed than a personal one.
• Not the API's skill registrythe Messages API and Managed Agents do not read directories at all. Moving a folder does nothing for a server-side agent; that path involves uploading the skill and naming it in the request.
• Not CLAUDE.mdproject memory is loaded into context every session whether it is relevant or not. A skill sits dormant until its description matches, which is why a long skill is cheap and a long CLAUDE.md is not.
• Not a version managercopying a project skill into a second repo produces a fork, not a subscription. Nothing tells the copy that the original changed. Plugins exist because copying does not scale past about two repos.
• Not a subagent definition.claude/agents/ is a sibling directory with different semantics. A subagent is a separate context that runs work; a skill is instructions loaded into the context you already have.

LimitsWhen not to reach for it

• One person, one repo, one week.Project scope and a committed file. Building a plugin and a marketplace for a skill that two people will use is infrastructure you will maintain forever for a problem you had once.
• It must run in cloud sessions or routines.Personal scope is disqualified outright, not merely inconvenient. Put it in the repository, in a plugin the repository declares, or on your claude.ai account, and verify by triggering one scheduled run before you rely on it.
• The instructions contain a secret.A committed project skill is a file in git that everyone with read access can see and that will be mirrored into forks. Reference a credential by environment-variable name; never paste the value.
• It is three lines and always applies.A rule that should govern every response is memory, not a skill. Scope-shopping will not fix a thing that should never have been conditional.
• The behaviour must be guaranteed.Skills are invoked because the model decides they are relevant. If the step must happen on every commit regardless, a hook or a script in the pipeline is the right instrument.

RelatedGo deeper