How to install skills in Claude Code

A skill is just a folder with a SKILL.md file in it, and installing one means putting that folder where Claude Code looks. There are four ways to do that, and the right one depends on whether you are grabbing a single skill, wiring up a whole team, or trying something you found in a README two minutes ago.

Where Claude Code looks for skills

Claude Code reads skills from two places, and the difference between them is the only piece of this you really have to remember:

~/.claude/skills/ — your personal skills. Available in every project on the machine, invisible to everyone else.
.claude/skills/ inside a repository — project skills. They travel with the repo, so committing one gives it to everybody who clones it.

Either way the layout is the same: one folder per skill, with SKILL.md at its root and any supporting files alongside it.

~/.claude/skills/
└── pdf/
    ├── SKILL.md
    ├── reference.md
    └── scripts/
        └── fill_form.py

The folder name matters if the skill’s frontmatter has no name field — that is what the agent falls back to. Keep it lowercase and hyphenated.

Method 1: copy the folder yourself

The method with no moving parts, and the one worth knowing even if you never use it, because everything else is a wrapper around it. If the skill lives in a GitHub repository:

git clone https://github.com/anthropics/skills.git /tmp/skills
cp -r /tmp/skills/document-skills/pdf ~/.claude/skills/

For a repository of many skills you only want one from, cloning the whole thing and copying one directory out is still the least fiddly option. Sparse checkout works too, but you will spend longer reading its flags than the copy takes.

Cloning gets you the tip of the default branch, which moves. If you want to know exactly what you installed six months from now, note the commit SHA somewhere — nothing in the format records it for you.

Method 2: npx skills add

The community CLI from Vercel Labs handles the clone-and-copy for you and knows about the directory layouts of 75+ agents. It accepts a repository URL, including one pointing at a subdirectory:

npx skills add https://github.com/anthropics/skills/tree/main/document-skills/pdf

Add -a claude-code to skip the interactive agent picker, -g to install globally rather than into the current project, and -y to accept the defaults. It is a good fit for scripting a machine setup, and a reasonable default if you are comfortable in a terminal.

Method 3: plugin marketplaces

Some skills ship inside Claude Code plugins, which are bundles that can also carry MCP servers, subagents and hooks. Those are installed from a marketplace rather than copied:

/plugin marketplace add owner/repo
/plugin install skill-name

If a project’s README tells you to run /plugin, follow that — a plugin is a different unit from a bare skill folder, and copying files out of one by hand tends to leave its other pieces behind.

Method 4: one click from the page you found it on

This is the one we built, so treat this section as what it is. The gap it fills: the moment you find a skill is almost never the moment you are in a terminal. You are reading a curated list, or a repository, or a marketplace page. The distance between “that looks useful” and “it is installed” is a context switch and half a dozen commands.

A pill appears on any page that has installable skills — a GitHub repo, an awesome-list, a marketplace.
Clicking it opens a preview: the skill’s instructions rendered, its file tree, and security flags for bundled scripts, tool grants and external URLs.
You pick targets — Claude Code, the universal directory, a specific project — and the folder is written atomically, pinned to the exact commit you previewed.

The preview is the part that matters more than the click. Skills carry instructions your agent may act on, and sometimes scripts; reading them before they land on disk should be the default regardless of which method you use.

Which one should you use?

Trying something you just found — one-click, or the manual copy. Both let you read it first.
Setting up a new machine — npx in a shell script, so it is repeatable.
Sharing with a team — commit the skill into the repo’s .claude/skills/. No install step for anyone else.
The README says plugin — use /plugin.

Confirming it worked

Claude Code hot-loads skills, so there is no restart and no reload command. Ask it directly — something like “what skills do you have available?” — and the new one should be listed. Skills are loaded on demand rather than all at once: the agent reads the one-line description in the frontmatter and pulls in the full instructions only when the description matches what you are asking for.

When a skill is not loading

SKILL.md is one level too deep. The most common cause by far. It must sit at the root of the skill folder, not inside a nested directory from the copy.
The frontmatter is malformed. The YAML block needs both name and description, fenced by --- lines at the top of the file.
The description is too vague. Skills are selected by that one line. “Helps with documents” will lose to a specific description every time; say what it does and when to use it.
You are in the wrong scope. A skill in a project’s .claude/skills/ is invisible from other directories. That is the point, but it surprises people.

Where to go next

If you are still deciding what to install, the format itself is worth ten minutes — what Agent Skills are and how SKILL.md works covers the frontmatter fields and how agents choose between skills. If you are weighing this against a server-based approach, see Agent Skills vs MCP servers. And if you use more than one agent, most of them read the same universal directory, so you can install once.