How to Install a Skill in Claude Code, Cursor, and Codex (Step by Step)
Where the skill folder goes in each tool, how to check it loaded, and one folder layout that works in all three without keeping three copies in sync.
Installing a skill is mostly a question of where you put a folder. Claude Code, Cursor and Codex all read the same SKILL.md format from the Agent Skills standard, but each one looks in slightly different places. Get the folder in the right spot and the tool picks it up. Put it one level off and nothing happens, with no error to tell you why.
This guide walks through all three, then shows a single layout that covers them at once. If you’re not sure what a skill is yet, start with What Are Claude Skills? and come back.
Before you start: check the skill folder
A skill is a folder. Inside it there has to be a file called SKILL.md, and that file has to open with YAML frontmatter:
---
name: release-notes
description: Writes release notes from merged pull requests. Use when the user asks for release notes or a changelog entry.
---
Instructions for the agent go here.
Three quick checks save most of the trouble later:
- The folder name and
namematch. Cursor requires it, and the standard expects it. Use lowercase letters, numbers and hyphens only, sorelease-notes, notRelease Notes. - Both
nameanddescriptionare filled in. Claude Code treatsnameas optional and falls back to the folder name, but Cursor and Codex both require it. Write it anyway. SKILL.mdsits directly inside the skill folder. Not in asrc/subfolder, and not zipped.
Extra files like scripts/ or references/ can sit next to SKILL.md. They don’t change where the folder goes.
Claude Code
Claude Code reads skills from a skills folder under .claude. You choose between two places:
| Scope | Path | Who gets it |
|---|---|---|
| Personal | ~/.claude/skills/<skill-name>/SKILL.md |
You, in every project on this machine |
| Project | .claude/skills/<skill-name>/SKILL.md |
Everyone who works in the repo, once it’s committed |
There are also enterprise, plugin and claude.ai-synced locations, but for installing a skill you downloaded or wrote, those two are the ones you want.
Steps
- Pick the scope. Personal if it’s just for you; project if the team should share it.
- Create the folder, for example
mkdir -p .claude/skills/release-notes. - Copy
SKILL.md(and any supporting files) into it. - Check it loaded. Ask Claude “What skills are available?” or type
/and look forrelease-notesin the menu. You can also run it directly with/release-notes.
Claude Code watches its skill folders, so a new or edited skill shows up in the session you already have open. One exception: if the top-level skills folder didn’t exist when the session started, run /reload-skills once to pick it up.
If the skill shows in the / menu but Claude never uses it by itself, the description is usually the cause. Make it name the situations where it should apply. We cover that, plus uploading to claude.ai, in the longer Claude Code and Claude.ai install guide.
Cursor
Cursor finds skills automatically when it starts and offers them to Agent. It reads from four places of its own:
| Scope | Path |
|---|---|
| Project | .agents/skills/ or .cursor/skills/ |
| User (this machine) | ~/.agents/skills/ or ~/.cursor/skills/ |
It also reads the Claude and Codex folders for compatibility: .claude/skills/, .codex/skills/, ~/.claude/skills/ and ~/.codex/skills/. So a skill you’ve already installed for Claude Code is usually visible in Cursor too.
Steps
- Create the folder, for example
.cursor/skills/release-notes/. - Copy
SKILL.mdinto it. Double-check thatnamematches the folder name, since Cursor is strict about this one. - Open Customize in the sidebar and go to Skills. Your skill should be listed.
- In Agent chat, type
/and search for the skill name to run it on one message.
Cursor also scans subfolders. You can group skills as .cursor/skills/shipping/release-notes/SKILL.md; the category folder is only for tidiness, and the skill is still called release-notes. A .cursor/skills/ folder inside a package in a monorepo is scoped to files in that package.
Two things that catch people out. First, Cursor doesn’t import skills from a GitHub link on its own; a repository has to be packaged as a plugin with a marketplace file before Customize can install from it. For a single skill, copying the folder is simpler. Second, personal skills in ~/.cursor/skills/ run only on your machine. Cloud Agents see them only if you turn on Sync Skills for Cloud Agents under Settings → Agents.
Codex
Codex looks in .agents/skills, not .codex/skills. That’s the most common mistake when people move a skill over.
| Scope | Path |
|---|---|
| Repository | .agents/skills/ in the folder where you launch Codex, and in each parent folder up to the repo root |
| User | $HOME/.agents/skills/ |
| Admin | /etc/codex/skills/ |
Steps
- Create the folder, for example
.agents/skills/release-notes/at the repo root. - Copy
SKILL.mdinto it, with bothnameanddescription. - In the Codex CLI or IDE extension, run
/skillsor type$to mention the skill, for example$release-notes. - Codex detects new skills automatically. If it doesn’t appear, restart Codex.
Codex has its own installer for curated skills. Running $skill-installer linear inside Codex installs the linear skill, and you can point it at other repositories too. If you later want to switch a skill off without deleting it, add an entry to ~/.codex/config.toml:
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
Restart Codex after editing that file.
One layout for all three
If your team uses more than one of these tools, you don’t want three copies of the same skill drifting apart. Going by what each tool’s docs say they read:
.agents/skills/is read by Cursor and Codex, but not by Claude Code..claude/skills/is read by Claude Code and Cursor, but not by Codex.
So keep the real folder in .agents/skills/ and give Claude Code a symlink to it:
mkdir -p .agents/skills .claude/skills
mv release-notes .agents/skills/
ln -s ../../.agents/skills/release-notes .claude/skills/release-notes
Claude Code and Codex both document that they follow symlinked skill folders. Commit both paths and every tool sees the same files.
One thing to check afterward: Cursor reads both folders, and its docs don’t say what happens when the same skill turns up twice. Open Customize → Skills once and make sure it looks right before you share the setup with the team.
Quick reference
| Claude Code | Cursor | Codex | |
|---|---|---|---|
| Project folder | .claude/skills/ |
.cursor/skills/ or .agents/skills/ |
.agents/skills/ |
| Personal folder | ~/.claude/skills/ |
~/.cursor/skills/ or ~/.agents/skills/ |
~/.agents/skills/ |
name required |
No (folder name used) | Yes, must match folder | Yes |
| Run it by hand | /skill-name |
/ then search |
/skills or $skill-name |
| Picks up changes | Live; /reload-skills for a new top-level folder |
Discovered at startup | Automatic; restart if missing |
Before you install someone else’s skill
A skill can include scripts, and in Claude Code it can pre-approve tools through allowed-tools. Read SKILL.md and anything in scripts/ before you drop a folder from the internet into your repo, the same way you’d read a shell script before piping it to bash. If a skill’s page doesn’t say whether it only reads files or also changes them, treat that as a question to answer before you install it. When you’re ready for one to try, the Skillaisle library is a good place to start.
Sources
- Claude Code docs: Extend Claude with skills
- Cursor docs: Agent Skills
- OpenAI (ChatGPT Learn): Build skills
- Agent Skills: Specification
Products change quickly. If something here no longer matches what you see, the official page above is the reference.
Related on Skillaisle
Want the setup steps? Browse the Learn guides or walk the skills aisle.