The short answer
- 1Put the Skill in
~/.cursor/skills/to use it in every project (it’s also the only folder that can sync to Cloud Agents), or in.cursor/skills/for one project. - 2The
nameinSKILL.mdmust match the folder name, using only lowercase letters, numbers, and hyphens. - 3Find it under Customize → Skills. Run it with
/skill-name, or attach it to a message with@skill-name.
Where Cursor looks for Skills
Cursor checks its own folders, the shared ~/.agents/skills/, and the Claude Code and Codex folders too. If you already use another agent, your Skills may be in Cursor already.
| Folder | What it’s for |
|---|---|
~/.cursor/skills/ | Every project. The only folder that syncs to Cloud Agents. |
~/.agents/skills/ | Every project on this computer. Skillry installs here, and Codex reads it too. |
.cursor/skills/ or .agents/skills/ | One project, anywhere in the repo. A nested folder applies to the files under it. |
.claude/skills/, .codex/skills/ and the same in ~ | Read so Skills from Claude Code and Codex work here too. |
How to add Skills to Cursor
The Skillry CLI installs to ~/.agents/skills/, which Cursor reads, so you don’t need a flag. If you copy a folder in by hand, put it in ~/.cursor/skills/ instead; that’s the folder that can follow you to Cloud Agents.
- 1
Open the Skill on Skillry, select Copy install prompt, then select Copy in the dialog.
- 2
Paste it into Cursor and send it. The agent reads Skillry’s install instructions and runs the right command itself.
Install prompt Read https://skillry.dev/skills/<slug>/install.md and follow the instructions to install the skill. - 3
When your browser asks you to approve a device code, approve it.
You should see: Cursor reporting the version it installed and the folder it used, under
~/.agents/skills/.
- 1
Sign in once. A browser window opens with a device code for you to approve.
Terminal npx --yes skillry-cli@latest login - 2
Install. You don’t need a flag, because the CLI’s default folder is the one Cursor reads.
Terminal npx --yes skillry-cli@latest install <slug>You should see:
Installed <slug> <version> to ~/.agents/skills/<slug>
Select Download ZIP on the Skill’s page, or use a Skill folder you got somewhere else. Read SKILL.md and anything in scripts/ before you install, since the agent follows those instructions and can run those scripts. Then move the whole folder:
mkdir -p ~/.cursor/skills
mv ~/Downloads/my-skill ~/.cursor/skills/ZIPs often unpack with an extra level, like my-skill/my-skill/SKILL.md. SKILL.md has to sit directly inside the Skill’s folder, or the agent won’t find it.
Cursor looks for Skills when it starts. After installing, open a new chat or reload the window, then check Customize → Skills under the Agent Decides group.
The naming rule that makes Skills disappear
Cursor only loads a Skill when the name in its SKILL.md exactly matches the folder it sits in. When they differ, there’s no error. The Skill just isn’t there.
Why did it disappear?
You download launch-page, rename the folder to landing to tidy up, and it vanishes from Cursor. The folder and the name no longer match. Rename the folder back, or change name to landing.
A name Cursor accepts
- Only lowercase letters, numbers, and hyphens
- Identical to the folder that holds
SKILL.md - Paired with a
description
How to run a Skill in Cursor
In the chat, type / and the Skill’s name, then your request:
/launch-page Parcelo, a parcel-tracking dashboard for small online shopsTo keep a Skill active for the whole session, pick it from the / menu and press Option+Enter (Mac) or Alt+Enter (Windows), or choose Use as Mode. It turns into a Custom Mode and stays on until you exit.
Use Skills in Cloud Agents
Cloud Agents don’t run on your computer, so they only get the Skills Cursor syncs for them. Here’s how to set it up:
- 1Keep the Skill in
~/.cursor/skills/. Project Skills and~/.agents/skills/stay on your machine. - 2Open Settings → Agents → Context and Tools and turn on Sync Skills for Cloud Agents.
- 3To share a personal Skill with your team instead, open it in Customize → Skills and choose Publish.
Cursor rules vs Skills
Cursor rules are short guidance that Cursor adds to the conversation, either always or for matching files. A Skill is a procedure the agent loads only when the task calls for it. Use rules for conventions and Skills for multi-step jobs.
A procedure, on demand
- A folder with
SKILL.md - Runs when relevant, or when you type
/name - Multi-step work, scripts, templates
Guidance in context
.mdcfiles in.cursor/rules/(plain.mdfiles are ignored)- Always Apply, Apply Intelligently, Apply to Specific Files, or Apply Manually
- Short conventions. Cursor also reads
AGENTS.mdandCLAUDE.md
Moving old rules over? Cursor’s built-in /migrate-to-skills converts “Apply Intelligently” rules and slash commands into Skills.
Cursor Skill not showing up? Try these
Check the name first. A mismatch between name and the folder is the usual reason a Skill goes missing in Cursor.
Not in Customize → Skills
Check that name matches the folder, then open a new chat or reload the window.
Missing in Cloud Agents
Move it to ~/.cursor/skills/ and turn on sync.
Never picked on its own
Its description may not match how you ask, or paths limits it to other files.
Common questions
What is the difference between Cursor rules and Skills?
Rules are guidance Cursor adds to conversations, either always or for matching files. Skills are folders holding a procedure that the agent uses when it’s relevant or when you call it.
Can Cursor use Claude Skills?
Yes. Cursor reads ~/.claude/skills/ and .claude/skills/, as long as each Skill’s name matches its folder.
Where are Cursor Skills stored?
~/.cursor/skills/ or ~/.agents/skills/ for every project, and .cursor/skills/ or .agents/skills/ for a single project.
Do Skills work in Cursor Cloud Agents?
Only Skills in ~/.cursor/skills/, and only after you turn on Sync Skills for Cloud Agents.
Sources
Did this guide help?
