Where is the global skills folder for Claude Code?

At ~/.claude/skills/. Each skill is a folder with a SKILL.md inside, such as ~/.claude/skills/deploy/SKILL.md. Skills there load in all your projects on that machine, but not in Cowork or cloud sessions.

What is the difference between .claude/skills and .claude/commands?

Custom commands were merged into skills. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy. Command files keep working, but skills also support supporting files. If both exist under one name, the skill wins.

Which skill runs if two have the same name?

Enterprise beats personal, and personal beats project. A plugin skill doesn't clash, because plugin skills are namespaced as /plugin-name:skill-name. A root skill and a nested skill with the same name both stay available.

Why doesn't Claude Code see my skill?

Check the path is /SKILL.md under a skills folder. A skill in a .claude/skills/ below where you started loads only after Claude works on files there. If you created a new top-level skills folder mid-session, run /reload-skills.

Do I need to restart Claude Code after editing a skill?

No. Claude Code watches skill folders and picks up added, edited or removed skills in the current session. The exception is a top-level skills folder that didn't exist when the session started, which needs /reload-skills.

Where are Claude Code skills stored, and how are they found?

Claude Code stores personal skills in ~/.claude/skills/<skill-name>/SKILL.md and project skills in .claude/skills/<skill-name>/SKILL.md inside the repository. It also loads skills from a managed folder, from plugins, and from your claude.ai account. Claude sees each skill's description up front and loads the full SKILL.md only when the skill is used.

Every location Claude Code loads skills from

Location	Path	Loads in
Enterprise	`.claude/skills/<skill-name>/SKILL.md` in the managed settings folder	All users on machines where your organization deploys it
Personal	`~/.claude/skills/<skill-name>/SKILL.md`	All your projects on this machine, not Cowork or cloud sessions
Project	`.claude/skills/<skill-name>/SKILL.md`	Sessions in this repository. Commit it so your team gets it
Nested	`<subdir>/.claude/skills/<skill-name>/SKILL.md`	Sessions started in or below that folder, or once Claude works on files there
Added directory	`.claude/skills/` in a folder passed to `--add-dir`	That session
Plugin	`<plugin>/skills/<skill-name>/SKILL.md`	Wherever the plugin is enabled, as `/plugin-name:skill-name`
claude.ai account	Enabled on your account, downloaded to `~/.claude/skills/synced/`	Cowork, cloud, and terminal sessions signed in with that account

A skill is a folder, and the file inside must be named SKILL.md. To see what your session found, run /skills. /context shows them too, bundled skills included.

How Claude Code finds skills in a repo

At launch, Claude Code loads project skills from .claude/skills/ in the folder where you started and in every parent folder up to the repository root. Starting in packages/frontend/ still picks up skills defined at the root.

Skills in a .claude/skills/ folder below where you started don't load at launch. They load the first time Claude reads or edits a file in that subfolder, then stay for the session. Until then they aren't in the / menu and you can't invoke them by name. On v2.1.257 or later, /add-dir with the subfolder's path loads them sooner.

permissions.additionalDirectories in settings.json grants file access only and loads no skills. --add-dir and /add-dir do load them.

How Claude decides to use a skill

Each skill's description and when_to_use frontmatter go into the skill listing Claude sees. The combined text is cut at 1,536 characters, so put the main use case first.
When your request matches, Claude invokes the skill. You can also type /skill-name.
The full SKILL.md enters the conversation only then.

This is the main difference from CLAUDE.md, which costs context in every session. A skill's body costs almost nothing until it's used, which suits long procedures. See how long CLAUDE.md should be for what to move out.

A minimal skill:

~/.claude/skills/release-notes/SKILL.md

---
description: Write release notes from the commits since the last tag
---

1. Find the last tag with git describe --tags.
2. Summarize the commits since then, grouped by feature and fix.

The command name comes from the folder, so this one is /release-notes. A name field in the frontmatter changes what the / menu shows.

When two skills share a name

Same name in	Which one runs
Enterprise, personal and project	Enterprise over personal, personal over project
A skill and a `.claude/commands/` file	The skill
Your skill and a bundled skill	Yours replaces the bundled command, but not its aliases
A root skill and a nested skill	Both load. `/deploy` runs the root one, `/apps/web:deploy` the nested one
A plugin skill and any other	Both load, because plugin skills are namespaced

Folder rules that trip people up

A <skill-name> entry in the enterprise, personal or project location can be a symlink to a folder elsewhere on disk. Claude Code loads the skill once even if several locations point at the same target.
Don't name a folder synced, in any capitalization. Claude Code uses ~/.claude/skills/synced/ for claude.ai skills and skips yours. A folder named anthropic-skills doesn't load either.
If the frontmatter YAML doesn't parse, the skill still loads with no fields set, so /skill-name works but Claude can't match your description. claude --debug shows the error, and on v2.1.233 or later claude plugin validate ~/.claude/skills finds the bad files.

Rulebook, the Mac app we are building, covers CLAUDE.md, settings.json and .mcp.json files. It doesn't manage skills. For the same question about instructions, see where Claude Code looks for CLAUDE.md.

Questions

Where is the global skills folder for Claude Code?: At ~/.claude/skills/. Each skill is a folder with a SKILL.md inside, such as ~/.claude/skills/deploy/SKILL.md. Skills there load in all your projects on that machine, but not in Cowork or cloud sessions.
What is the difference between .claude/skills and .claude/commands?: Custom commands were merged into skills. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy. Command files keep working, but skills also support supporting files. If both exist under one name, the skill wins.
Which skill runs if two have the same name?: Enterprise beats personal, and personal beats project. A plugin skill doesn't clash, because plugin skills are namespaced as /plugin-name:skill-name. A root skill and a nested skill with the same name both stay available.
Why doesn't Claude Code see my skill?: Check the path is <skill-name>/SKILL.md under a skills folder. A skill in a .claude/skills/ below where you started loads only after Claude works on files there. If you created a new top-level skills folder mid-session, run /reload-skills.
Do I need to restart Claude Code after editing a skill?: No. Claude Code watches skill folders and picks up added, edited or removed skills in the current session. The exception is a top-level skills folder that didn't exist when the session started, which needs /reload-skills.

Rulebook for Mac

Rulebook is a native Mac app we are building for these files. It shows every CLAUDE.md and settings.json level side by side, lets you drag a rule from one file to another, and edits permissions without hand-written JSON. See the features.

Rulebook is in development and not available yet.

Email us about the launch