CONCEPT Where a skill lives decides who gets it
Skills are discovered by location. The same SKILL.md reaches a different
audience depending on which folder it's in:
| Scope | Path | Applies to |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | All your projects, on your machine |
| Project | .claude/skills/<name>/SKILL.md | This project — commit it and the team gets it |
| Plugin | <plugin>/skills/<name>/SKILL.md | Wherever the plugin is enabled (namespaced plugin:skill) |
| Enterprise / managed | Managed-settings location | All users in the organization |
On a name clash across levels, enterprise overrides personal, and personal overrides project;
any of these also overrides a bundled skill of the same name. Plugin skills are namespaced
(plugin-name:skill-name), so they never collide with the other levels.
.claude/skills/ to version control (project),
bundle a skills/ directory in a plugin (shareable install),
and deploy via managed settings (org-wide).CONCEPT Plugins & marketplaces
A plugin is the packaging unit for sharing skills (plus optional agents, hooks, and MCP
servers). Put a skills/ directory in the plugin and each subfolder becomes a namespaced skill.
Plugins are distributed through marketplaces — a marketplace is a source you add once, then
install plugins from:
# Add a marketplace (a source of plugins), then install one. /plugin marketplace add anthropics/claude-plugins-official /plugin install skill-creator@claude-plugins-official # Refresh a stale marketplace if an install can't be found. /plugin marketplace update claude-plugins-official # Make a newly installed plugin's skills active this session. /reload-plugins
Unlike personal or project skills, plugin skills are managed through /plugin,
not through the per-skill visibility settings covered below.
CONCEPT The /skills view & visibility control
The /skills menu lists the skills available in your session. It's also how you
tune per-skill visibility without editing anyone's SKILL.md: highlight a skill, press
Space to cycle its state, then Enter to save. The menu writes a
skillOverrides entry into .claude/settings.local.json:
skillOverrides value | Listed to Claude | In / menu |
|---|---|---|
"on" (default when absent) | Name + description | Yes |
"name-only" | Name only (frees description budget) | Yes |
"user-invocable-only" | Hidden | Yes |
"off" | Hidden | Hidden |
skillOverrides for skills you don't own — ones checked into a shared repo or
provided by an MCP server — where editing the SKILL.md frontmatter isn't yours to do. Plugin skills
are not affected by skillOverrides; manage those via /plugin.DIAGRAM Distribution channels
~/.claude/skills/"] Q -->|"this repo's team"| PR["🟢 Project
commit .claude/skills/"] Q -->|"anyone who installs"| PL["🟠 Plugin
skills/ dir → marketplace"] Q -->|"whole org, enforced"| EN["🔴 Managed settings
enterprise scope"] PL --> MP["/plugin marketplace add …
/plugin install …@marketplace"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class P ok; class PR ok; class PL gate; class EN bad;
CODE A plugin that ships skills
Drop a skills/ directory into the plugin; each subfolder is one namespaced skill. Publish the
plugin through a marketplace and users install it with /plugin install.
my-plugin/ ├── .claude-plugin/ │ └── plugin.json # plugin manifest ├── skills/ │ ├── review/ │ │ └── SKILL.md # becomes /my-plugin:review │ └── deploy/ │ └── SKILL.md # becomes /my-plugin:deploy ├── agents/ # optional: bundled subagents └── hooks/ # optional: bundled hooks # settings.local.json — collapse a noisy skill, disable another. { "skillOverrides": { "legacy-context": "name-only", "deploy": "off" } }
SKILL.md, scripts, assets) before
trusting a repo or marketplace.TRADE-OFFS Project commit vs. plugin vs. managed
✅ Commit to .claude/skills/
- Zero install — clone the repo, get the skills
- Versioned and reviewed with the code
- Scoped to exactly the project that needs them
✅ Plugin / marketplace / managed
- Plugin: reusable across many repos, bundles agents/hooks/MCP
- Managed settings: pushed org-wide, centrally enforced
- But: more setup than a plain committed folder
EXAM TRAPS
.claude/skills/ to version control. Plugins are for reuse across repos and
bundling other extensions.skillOverrides manages plugin skills too." → It does not —
plugin skills are managed through /plugin. skillOverrides covers personal/project/MCP
skills./skills menu only lists skills." → It also edits
visibility: Space cycles a skill's state and Enter writes a
skillOverrides entry to .claude/settings.local.json.PRACTICE
Q1 · What's the lightest way to give your whole team a project-specific skill?
Put it in the project's .claude/skills/<name>/SKILL.md and commit it to
version control. Everyone who clones the repo gets the skill with no install step. Plugins and managed
settings are for broader reuse or org-wide enforcement.
Q2 · A skill named deploy exists at personal, project, and plugin scope. Which runs on /deploy?
Across the non-plugin levels, personal overrides project (and enterprise would override
both). The plugin's version is namespaced as plugin-name:deploy, so it never conflicts —
you'd invoke it with its qualified name.
Q3 · How do you install a shared skill packaged as a plugin?
Add the marketplace once with /plugin marketplace add <source>, then
/plugin install <plugin>@<marketplace>, and run /reload-plugins to activate
it in the current session. Manage plugin skills afterward via /plugin (not skillOverrides).