How to install a skill in Claude, and what to check when it does not load

How do you install a skill in Claude Code (terminal, desktop app or VS Code)?

Copy the skill's folder into a skills directory: ~/.claude/skills/ for all your projects, or .claude/skills/ inside a project for that project only. Claude Code looks for each skill at skills/<skill-name>/SKILL.md, so the SKILL.md must sit exactly one folder below skills/.

1. Create the folder if it does not exist: ~/.claude/skills/ for all your projects, or <project>/.claude/skills/ for one project.
2. Copy the skill's folder into it, keeping its name. A skill delivered as a .skill file is a ZIP archive whose root is that folder: unzip it there.
3. Claude Code watches these folders and picks up new or edited skills in the running session. If the skills folder did not exist when the session started, run /reload-skills or restart. Claude Code is not watching a folder created mid-session, so run /reload-skills again after each later change there.
4. Run /skills to see what is loaded.

mkdir -p ~/.claude/skills
unzip dist/site-xray.skill -d ~/.claude/skills

The Code tab of the desktop app reads the same ~/.claude/skills/ in local sessions. An SSH session reads ~/.claude/skills/ on the remote machine, not on yours.

In the VS Code extension, type /skills in the panel to open the skills list (Claude Code v2.1.280 or later). Anthropic's VS Code page gives the extension no separate skills folder, and says the panel offers a subset of commands: if one is missing, run claude in VS Code's integrated terminal, which needs the standalone CLI install.

Should you install a skill globally or per project?

Install a skill globally (a personal skill, in ~/.claude/skills/) when you want it in every project on your machine. Install it per project (in .claude/skills/ at the project root) when it belongs to one codebase or your team should get it too: commit that folder to git and everyone who clones the repository has it.

If the same skill name exists in both places, Claude Code runs the personal one. Anthropic's documentation puts enterprise skills over personal ones and personal over project ones; at least one guide that ranks for this question says project skills win, which the documentation contradicts.

Project skills also load when you start Claude Code in a subfolder: it reads .claude/skills/ in the folder where you start and in every parent folder up to the repository root. Cloud sessions load the project skills committed to the repository, never your personal folder.

Where are Claude skills stored on Mac, Windows and Linux?

Claude Code keeps personal skills in a .claude folder in your home directory on every system: ~/.claude/skills/ on macOS and Linux, and %USERPROFILE%\.claude\skills\ on Windows, where Anthropic documents that ~/.claude resolves to %USERPROFILE%\.claude. Skills uploaded in Claude.ai, Desktop chat or Cowork are kept in your account, not in a folder on your computer.

If the CLAUDE_CONFIG_DIR environment variable is set, every ~/.claude path moves under that directory instead. Inside Claude Code, /skills lists what is loaded, whatever the folder.

On a Mac the folder name starts with a dot, so Finder hides it. Open it from Terminal with: open ~/.claude/skills

Some guides give ~/Library/Application Support/Claude Code/skills/ on macOS or %APPDATA%\Claude Code\skills\ on Windows. Anthropic's documentation does not list those paths for skills; it gives the ones in the table.

How do you install Claude skills from GitHub?

It depends on what the repository holds. If it is a plugin marketplace (it has a .claude-plugin/marketplace.json file), add it once in Claude Code and install plugins from it. If it only holds skill folders, copy the folder you want into your skills directory. Either way, read the skill before you install it: it is code from someone else.

1. Plugin marketplace, inside Claude Code: run /plugin marketplace add owner/repo, then /plugin install <plugin>@<marketplace>, where <marketplace> is the name the marketplace registered under. In a session, the install command opens the plugin's details so you can review it and choose a scope first.
2. The same from your shell, without opening a session: claude plugin marketplace add owner/repo, then claude plugin install <plugin>@<marketplace>.
3. Plain skill folders: clone the repository anywhere, then copy the folder that holds SKILL.md into ~/.claude/skills/ or .claude/skills/. Cloning a whole repository straight into ~/.claude/skills/ works only when SKILL.md sits at the top of that repository; otherwise the skill ends up a level too deep, where Claude Code does not look.
4. To update a cloned skill with git pull, link it instead of copying it: a skill folder in the personal or project location can be a symlink to a directory elsewhere on disk.
5. For Claude.ai, Desktop chat or Cowork: download the skill's folder, zip it with the folder itself at the root of the ZIP, and upload it as the next section describes.

# Anthropic's own skills repository is a plugin marketplace:
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

• Discover and install plugins: Anthropic's page for /plugin marketplace add, /plugin install and their shell forms.
• anthropics/skills on GitHub: Anthropic's example skills, installable as a marketplace.

Installers such as npx skills add are third-party tools, not part of Anthropic's documentation. Whatever they do, Claude Code loads skills from the locations Anthropic documents (the table above) or from an enabled plugin.

How do you add a skill in Claude.ai, Claude Desktop (chat) and Cowork?

Here a skill is uploaded to your account, not copied to a folder on your machine.

1. Switch on code execution. On Free, Pro and Max plans: Settings > Capabilities, then turn on "Code execution and file creation". On Team and Enterprise an owner enables code execution and Skills in Organization settings > Plugins & skills, on the "Policy" tab.
2. Open Customize > Skills, press the "+" button, then "+ Create skill" and "Upload a skill".
3. Choose the ZIP of one skill. Upload skills one at a time: a bundle that holds several skill folders is not a skill and will not load as one.
4. The help center asks for a ZIP with the skill folder at its root, and shows loose files at the root of the ZIP as the incorrect structure. A .skill file is a ZIP archive built that way. If the file picker refuses the .skill extension, make a copy and rename it to .zip.

Cowork and cloud sessions do not read ~/.claude/skills/ on your machine. They load the skills enabled on your account.

On Team and Enterprise plans an owner can turn off user-created skills. If the option to create or upload a skill is missing, that is the first thing to ask about.

How do you use a skill once it is installed, and why does it not trigger?

You do not have to call a skill by name. Claude reads each skill's description and loads the right one from your wording: "audit my site" is enough for an audit skill to answer.

In Claude Code you can also call a skill directly with a slash and its folder name, for example /site-xray.

A skill that never triggers is usually loaded but not chosen: its description does not match the words you used. Call it by name once, or say what you want in the terms its description uses.

• Site X-Ray: The skill used as the example on this page.

Why is my Claude skill not showing up or not loading?

1. Check the folder name. A skill's folder must keep the name it was shipped with: it matches the name written in its SKILL.md. The help center lists a folder name that does not match the skill name as an upload error.
2. Check that code execution is on, in the apps. Without it the Skills section can be missing or greyed out, and a skill that ships scripts can only follow its manual route, if it has one.
3. Check the ZIP, in the apps. The help center's other usual causes of a failed upload: a ZIP over the size limit, a missing SKILL.md, invalid characters in the name or description.
4. Check the description length. The Agent Skills specification and Anthropic's platform documentation allow 1,024 characters. One help-center article gives a shorter limit (200 characters): if an upload is rejected or cut for that reason, the description is the first thing to look at.
5. In Claude Code, run /skills. If the skill is not listed, run /reload-skills or restart the session. A folder name with a hidden character (a no-break space, a zero-width space, < or >) is refused: start claude --debug and search the debug log for [names].

Before you install any skill

A skill can ship scripts, and scripts run code in your Claude environment or on your machine. Read the SKILL.md and look at the scripts before installing a skill from someone you do not know. Anthropic's help center gives the same advice: install skills only from trusted sources, and review the bundled files, the code dependencies and any instruction to reach an external network source first.

The 14 skills of this pack use standard-library Python 3.9 or later, with nothing to install, and they come with a checksum file and a small verifier: python3 verify_pack.py tells you whether your copy is the released one.

• Are Claude skills from independent developers safe to install?: the checks to run before you install one