To add a skill to Claude Code, put a folder that contains a SKILL.md file into ~/.claude/skills/ (every project on your machine) or .claude/skills/ (one repository), or install a plugin that ships skills with /plugin install. Claude picks the skill up without a restart and uses it when your request matches its description, or when you type /skill-name.
The rest of this page covers each route in order, then how to call a skill, what to do when it does not show up, and what to check before you run someone else’s skill.
What you are installing
A skill is a directory. It holds a SKILL.md file with a short YAML header (name and description) and Markdown instructions, and it may also hold scripts/, references/ and assets/ folders. The format is an open specification at agentskills.io, which is why the same folder works in Claude Code, Codex and many other agents.
The agent keeps only the name and description of each skill in context. The full SKILL.md loads when the skill is chosen, and extra files load only when the instructions point to them. That is why you can install dozens of skills without filling the context window, and also why a vague description means a skill that never fires.
How to add skills to Claude Code
Claude Code has three ways to get a skill: copy a folder in by hand, install a plugin, or use the cross-agent skills command. The first two are Anthropic’s own paths, documented in the Claude Code skills docs.
Personal and project folders
These are the locations from the official docs:
| Scope | Path | Where it applies |
|---|---|---|
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | All your projects on this machine |
| Project | .claude/skills/<skill-name>/SKILL.md | Sessions in this repository; commit it to share with the team |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md | Wherever the plugin is enabled, as /plugin-name:skill-name |
| Enterprise | .claude/skills/ inside the managed settings directory | Every user on machines where your organization deploys it |
A manual install is a copy. Clone the repository, find the skill folder, and copy the whole folder, not only SKILL.md, because scripts and reference files travel with it:
git clone https://github.com/anthropics/skills /tmp/anthropic-skills
cp -r /tmp/anthropic-skills/skills/skill-creator ~/.claude/skills/When two skills share a name, enterprise wins over personal and personal wins over project. A plugin skill is namespaced, so it does not collide with a local one.
Claude Code watches these folders. Edits, additions and removals take effect in the running session. The one exception: if you create a brand-new top-level skills directory mid-session, run /reload-skills. To remove a personal or project skill, delete its folder.
Plugins and marketplaces
A plugin bundles skills with agents, hooks or MCP servers, and Claude Code installs it as one unit. Plugins come from marketplaces, which are catalogs listed in a marketplace.json file. Anthropic’s official marketplace is added for you the first time you start an interactive session. For anything else, add the marketplace first, then install:
/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills/plugin install opens the plugin’s details so you can read what it adds and pick a scope: user (all projects on this machine), project (everyone on the repository, through the committed .claude/settings.json) or local (you, this repository only). You can also run /plugin with no name to browse the Discover tab. From a script, claude plugin install <name>@<marketplace> does the same without a session. The full flow is in the plugin install docs.
After installing, type / and look for /<plugin>:<skill>. If the reload message appears, /reload-plugins applies it. Plugins from marketplaces other than Anthropic’s official ones do not auto-update by default, so update them from the Marketplaces tab or with claude plugin update <plugin>@<marketplace>.
If you want to see which repositories ship a plugin manifest, our plugins page lists them, and our Claude Code platform page has the paths and the install command for each reviewed pack.
The skills CLI
The open-source skills CLI installs from a GitHub repository into whichever agents it detects on your machine. It needs Node.js 22.20 or later, per its README:
npx skills add vercel-labs/agent-skills
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a claude-codeWithout -g the skill goes into the current project; with -g it is installed for all projects. Other commands: npx skills find, list, check, update and remove. The CLI sends anonymous usage data unless you set DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1, which also turns off its security-audit requests.
Claude.ai and the desktop apps
Claude.ai handles skills through settings instead of folders. According to Anthropic’s support article on using skills, skills are available on Free, Pro, Max, Team and Enterprise plans and need code execution turned on:
- On Free, Pro and Max, open Settings, then Capabilities, and enable code execution and file creation. On Team and Enterprise, an owner enables it under Organization settings.
- Open Customize, then Skills, and toggle the skills you want.
- To add your own, zip the skill folder, choose ”+”, then “Create skill”, then “Upload a skill”.
Common upload failures from the same article: an oversized ZIP, a folder name that does not match the skill name, a missing skill file, and invalid characters in the name or description. Anthropic’s built-in document skills (Excel, Word, PowerPoint, PDF) run automatically when relevant. Custom skills are chosen from their description, and the article suggests naming the skill in your request if Claude ignores it.
The Code tab of the desktop app reads the same settings files as the terminal, so a user-scope plugin installed in one is available in the other. In the desktop app you open the plugin browser from the ”+” button next to the prompt box.
Codex and other agents
Codex follows the same format with different folders. The Codex skills documentation lists the locations it scans:
.agents/skillsin the current directory and each parent folder up to the repository root$HOME/.agents/skillsfor your user/etc/codex/skillsfor admins, plus skills bundled with Codex
In Codex you install a curated skill with $skill-installer <name>, and you invoke one by typing $ and the skill name or by running /skills. Codex detects new skills automatically; restart it if one does not appear.
For everything else, the skills CLI’s agent reference gives the paths. A few of them:
| Agent | -a flag | Project path | Global path |
|---|---|---|---|
| Claude Code | claude-code | .claude/skills/ | ~/.claude/skills/ |
| Codex | codex | .agents/skills/ | ~/.agents/skills/ |
| Cursor | cursor | .agents/skills/ | ~/.cursor/skills/ |
| OpenCode | opencode | .agents/skills/ | ~/.config/opencode/skills/ |
| GitHub Copilot | github-copilot | .agents/skills/ | ~/.copilot/skills/ |
| Gemini CLI | gemini-cli | .agents/skills/ | ~/.gemini/skills/ |
We keep a page per agent with the same details: Codex, Cursor, OpenCode and others under /platforms/.
How to use Claude skills once they are installed
There are two ways to run a skill, and most skills allow both.
Automatic. Describe your task normally. If it matches the skill’s description, Claude loads the skill and follows it. A skill’s description is therefore the trigger; asking for “a code review” will not call a skill whose description only mentions “pull request triage”.
Direct. In Claude Code, type /skill-name, followed by arguments if the skill takes them (/fix-issue 123). In Codex, type $skill-name. Direct calls are the reliable way to test a new skill.
Two frontmatter settings change who can call a skill. With disable-model-invocation: true, only you can run it, which is the right setting for anything with side effects such as deploys or commits. With user-invocable: false, only Claude can, which suits background knowledge. To see what is loaded, run /skills in Claude Code, or ask Claude what skills are available.
Two behaviors surprise people. First, once a skill runs, its content is added to the conversation and Claude Code does not re-read the file on later turns. Second, after auto-compaction Claude Code keeps only the first 5,000 tokens of each invoked skill, so put the critical rules at the top of a long SKILL.md, and re-invoke the skill if Claude drifts.
Troubleshooting a skill that does not work
These checks come from the troubleshooting section of the Claude Code skills docs.
The skill never triggers.
- Check that the description contains words people would actually say.
- Confirm the skill appears in the
/skillslist. - Try
/skill-namedirectly. If that is not recognized either, the name may have been refused (names with control characters or angle brackets are). - Make sure the opening
---is on line 1. If the YAML is malformed, Claude Code loads the body with empty metadata, so the slash command works but description matching does not. Runclaude --debugto see the parse error. - If the skill sets
paths, it only activates for files inside the current working directory.
The skill fires too often. Narrow the description, or set disable-model-invocation: true.
The description is cut off. With many skills installed, Claude Code drops descriptions from the listing to fit a budget equal to 1% of the context window, starting with the skills you use least. Each entry is also capped at 1,536 characters for description plus when_to_use. Put the main use case first, and run /doctor for an estimate of the listing’s cost.
The skill vanished. Check ~/.claude/skills/.trash/. Skills synced from claude.ai live in a separate ~/.claude/skills/synced/ folder and do not touch folders you created.
A plugin skill is missing. Look under the Errors tab in /plugin, run /reload-plugins, and check claude plugin list for the scope and status.
In Codex, restart the app if a new skill does not appear, and check that no two skills share a name: Codex does not merge them.
Security checklist before you install
A skill is instructions plus, often, scripts that your agent runs with your permissions. Anthropic’s own article names prompt injection and data exfiltration as the main risks and says to install skills only from trusted sources. A plugin, likewise, runs with your user privileges whichever marketplace it comes from.
Before installing anything from a stranger:
- Read
SKILL.mdand every file inscripts/. If you cannot read it, do not run it. - Look for
curl ... | sh, “download this prerequisite”, encoded blobs, and instructions to contact an outside server. - Check
allowed-tools. It pre-approves tools for the turn the skill runs, so a broadBash(*)removes a prompt you would want. - Compare the owner and star count with the install count. A famous name under a new owner is a red flag.
- Pin to a commit or tag instead of tracking a moving branch, and run unattended sessions in a sandbox.
We apply this to every pack in the directory. Of the 88 individual skills we have reviewed in depth, 30 came out with no issues, 51 carry a “review before installing” note, and 7 ask for broad access; the reasoning is on our security page and the scoring rules are on how we review. Browse the reviewed skills in /skills/, or start from our best skills shortlist. If you want to write your own instead, see how to create a Claude skill.