How to install Claude skills in Claude Code

01 / Decision

Choose the scope before you copy the folder

Where the folder goes decides who gets the skill. Claude Code documents four locations, plus a synced directory it fills from your claude.ai account. When the same skill name exists at more than one level, enterprise overrides personal and personal overrides project, and a skill at any of those levels overrides a skill synced from claude.ai.

02 / Workflow

Install a skill and confirm Claude Code loaded it

The manual path is worth learning first, because the plugin path and the sync path produce the same result: a SKILL.md folder in a directory Claude Code reads. Commands below are quoted from the documentation cited beside each step.

1. 01

   Read the skill before you install it

   Anthropic's guidance is to use skills only from sources you trust, because a skill gives an agent new instructions and executable code, and a malicious one can direct the agent to call tools in ways its stated purpose does not suggest. Review SKILL.md, every bundled script, and anything the skill fetches from an external URL. Treat the decision the way you would treat installing software.

   Output: A skill you have read in full, from a source you are willing to run.

2. 02

   Create the skill directory at the scope you chose

   For a personal skill the documentation creates the folder directly, with mkdir -p ~/.claude/skills/summarize-changes. For a project skill, create .claude/skills/<skill-name>/ inside the repository instead. The directory name becomes the command you type, so that example is invoked as /summarize-changes.

   Output: One folder named after the skill, at one scope.

3. 03

   Put SKILL.md inside the folder

   SKILL.md is the entry point and the only required file. It opens with YAML frontmatter and continues with the Markdown instructions Claude follows. Claude Code treats every frontmatter field as optional and recommends description, because that is the text it matches a request against. The Agent Skills specification is stricter: name and description are required, and name has to match the parent directory name, stay within 64 characters, and use lowercase letters, numbers, and single hyphens. Optional scripts, references, and assets sit beside SKILL.md and load only when the task reaches them.

   Output: A folder whose SKILL.md says what the skill does and when to use it.

4. 04

   Commit it when the whole team works in that repository

   Project skills load from .claude/skills/ in the directory where you start Claude Code and in every parent directory up to the repository root, so starting in a subdirectory still picks up skills defined at the root. Skills in nested .claude/skills/ directories below your starting directory are not loaded at startup: they load the first time Claude reads or edits a file inside that subdirectory. To load skills from a directory outside that path at startup, pass it with --add-dir.

   Output: A skill that arrives with a clone instead of a paste.

5. 05

   Or install a plugin that bundles the skills

   Add a marketplace with /plugin marketplace add owner/repo, then install from it with /plugin install plugin-name@marketplace-name. Anthropic's public skills repository is registered with /plugin marketplace add anthropics/skills. Plugin skills live in the plugin's skills/ directory and are namespaced by the plugin, so a skill named review inside my-plugin is invoked as /my-plugin:review. When the install summary says to run /reload-plugins, run it to activate the plugin in the current session.

   Output: Several skills installed and updated through one source.

6. 06

   Verify that Claude Code sees the skill

   Run /skills to open the menu of what is loaded, and ask what skills are available as a second check inside the session. The Skills row in /context reports the size of the skill listing the model actually receives, and /doctor estimates its context cost. Claude Code watches skill directories, so adding, editing, or removing a skill under ~/.claude/skills/, the project .claude/skills/, or a .claude/skills/ inside an --add-dir directory is picked up within the session, without a restart. Creating a top-level skills directory that did not exist when the session started does need a restart.

   Output: The skill listed by name, before anyone relies on it.

7. 07

   Invoke it, and decide who is allowed to

   A skill is available as a slash command named after its directory, and Claude can also load it on its own when a request matches the description. Set disable-model-invocation: true when only you should trigger it, which is the sensible default for anything that deploys, commits, or sends a message. Set user-invocable: false for background knowledge that only Claude should reach for.

   Output: A skill that runs when you expect it and stays quiet when you do not.

Teammates who run a different agent need their own install path for the same folder, which is the subject of manage skills across Claude Code, Codex, and Cursor.

03 / Record

The install note worth keeping

Write this once per skill, beside the recommendation. It answers the questions the next person would otherwise ask in chat, and it records when the path was last checked, because product behavior changes.

Skill and source

The skill name plus the repository and path the folder came from.

Scope

Personal, project, plugin, or managed, and the reason that scope was chosen.

Install path

The exact directory the folder goes in, written out rather than described.

Verification

The command that proves it loaded, and the output the reader should see.

Reviewed at

Who checked the path, on what date, against which documentation page.

Re-review trigger

The source changed, the skill failed a run, or the documented locations changed.

Skill: <skill-name>
Source: <repository URL and path to the skill folder>
Scope: personal (~/.claude/skills/<skill-name>/) or project (.claude/skills/<skill-name>/)

Install
  1. Read SKILL.md and every bundled script at the source.
  2. mkdir -p ~/.claude/skills/<skill-name>
  3. Copy SKILL.md and any scripts, references, and assets into that folder.

Verify
  1. Run /skills and confirm <skill-name> is listed.
  2. Invoke /<skill-name> and confirm the expected output.

Reviewed by: <name>, <date>
Re-review when: the source changes, a run fails, or the documented skill locations change.

04 / Pitfalls

Where installs go wrong

05 / Checklist

Ready to share with the team?

• The skill came from a source you were willing to read in full.
• The folder sits at one scope, and you can say why that scope.
• SKILL.md stays inside the specification fields if the folder also has to load outside Claude Code.
• Running /skills in a fresh session lists the skill by name.
• Invoking the skill produced the output you expected, not a near miss.
• The next teammate can find the source, the scope, and the verification step without asking you.

06 / Questions

Frequently asked questions

Where are Claude skills stored?

Claude Code documents four locations: ~/.claude/skills/<skill-name>/SKILL.md for personal skills, .claude/skills/<skill-name>/SKILL.md for a project, a skills directory inside a plugin, and enterprise managed settings. Skills you enable on claude.ai are downloaded into ~/.claude/skills/synced/ during a run with CLAUDE_CODE_SYNC_SKILLS set. A symlink at any of those paths is followed too.

How do I add a skill to Claude Code without a plugin?

Create the directory, then write the file. The documentation creates a personal skill with mkdir -p ~/.claude/skills/summarize-changes and saves SKILL.md inside that folder. For a project skill, use .claude/skills/<skill-name>/ and commit it with the code. The directory name becomes the slash command you type.

Do I have to restart Claude Code after adding a skill?

Usually not. Claude Code watches skill directories, so a skill added, edited, or removed under ~/.claude/skills/, the project .claude/skills/, or a .claude/skills/ inside an --add-dir directory is picked up within the session. Restart when you create a top-level skills directory that did not exist at startup.

Why does my skill not show up?

Check the scope, then the frontmatter. A skill with the same name at a higher level wins, a nested project skill loads only after Claude touches a file in its directory, and malformed YAML loads the body with empty metadata so nothing matches your request. Run with --debug to see parse errors.

Can I install a skill for a whole team in one step?

Not through the skill format itself. Anthropic documents three distribution scopes: commit the folder to the repository's .claude/skills/, ship a skills directory inside a plugin, or deploy through managed settings. Each one is set up separately, and each teammate still ends up with skill files on disk.

Are Claude Code skills the same as claude.ai skills?

Same file format, separate installs. Anthropic documents that custom skills do not sync across surfaces: a claude.ai upload is not available through the API, an API skill is not on claude.ai, and Claude Code skills are filesystem based. Claude Code can download the ones you enabled on claude.ai into a synced folder.