Cursor Skills and How to Add, Write and Share Them

The repo behind this site keeps 22 skills in .claude/skills, a Claude Code folder that Cursor also reads. A Cursor skill is a folder with a SKILL.md file, and Cursor’s own locations are .cursor/skills and .agents/skills, in a repo or your home folder. The agent loads one when its description fits your request, or you type / to run it.

Getting a skill used is harder than writing one. In one engineer’s 323 Claude Code sessions from September 2 to October 3, 2026, a skill loaded in 49, or 15%. That count is from Claude Code because we don’t use Cursor enough to measure it. So we’d write fewer skills than you’re tempted to, and check which ones get used.

What is a Cursor skill?

A skill is a set of instructions for one job, kept in its own folder so it can carry scripts/, references/ and assets/ next to the SKILL.md. When Cursor starts it finds every skill and shows them to the agent, which decides from each description whether one applies. Reference files load only when they’re needed, so a skill takes up little context until it runs.

Cursor also ships built-in skills that appear next to yours. The format is the open Agent Skills standard, and support arrived in Cursor 2.4 in January 2026.

How to add a skill to Cursor

Make a folder named after the skill, put a SKILL.md inside, and place the folder in one of these locations. To confirm Cursor found it, open Customize in the sidebar and go to Skills.

Location	Who gets it	Details
.cursor/skills/ or .agents/skills/	Everyone who pulls the repo, once it’s committed	A copy in a subfolder such as apps/web/.cursor/skills/ applies only to files under apps/web/
~/.cursor/skills/	You, in every project	The only location that can sync to Cloud Agents
~/.agents/skills/	You, in every project	Stays on your machine
.claude/skills/ and .codex/skills/, in the repo or under ~/	Whoever already has those folders	Loaded for compatibility with Claude Code and Codex

Category folders are fine, as in .cursor/skills/shipping/land-it/SKILL.md.

To install someone else’s skill, the plain route is to copy its folder into one of those locations, since Cursor picks up any SKILL.md it finds there. Cursor’s packaged route is a plugin. Under Customize, import a repository with From GitHub Repository (it needs a .cursor-plugin/marketplace.json), then install the plugin it offers.

Cursor reviews every plugin in its Marketplace by hand and points to cursor.directory for community ones, and lists such as awesome-cursor-skills collect more. A skill can include scripts the agent will run, so read it before you install it. Cursor gives the same advice for plugins.

How to use a skill in Cursor

If the description fits, the agent loads the skill without being asked. To run one yourself, type / in Agent chat, search for the name and send the message, or type @ and select it to attach it as context. A skill run with / applies to that one message and fades as the conversation moves on.

To keep one on for a whole session, make it a Custom Mode. Pick it from the / menu and press Option+Enter on a Mac or Alt+Enter on Windows, and it stays in context on every turn until you exit the mode. Cursor lists Custom Modes for the Agents Window and the CLI.

How to write your own

The fastest way is to type /create-skill and describe the job, and Cursor’s built-in skill walks you through the naming and structure. By hand, a skill is YAML frontmatter followed by plain instructions. This frontmatter is a real one from our repo, and everything below the closing --- is instructions for the agent. Its allowed-tools line is a Claude Code field that Cursor’s docs don’t list.

---
name: commit
description: Generate a conventional commit message from staged changes and commit.
disable-model-invocation: true
allowed-tools: Bash(git *)
---

Two fields decide whether it works at all. name must match the folder and use only lowercase letters, numbers and hyphens. description is what the agent reads to decide, so say what the skill does and when to use it, in the words people use when they ask. Cursor’s own example ends with “Use when deploying code or when the user mentions deployment, releases, or environments.” A skill with no description can still be run by name, but the agent is unlikely to pick it by itself.

Field	Required	What it does
name	Yes	The skill’s identifier, matching its folder
description	Yes	What it does and when to use it, read by the agent
paths	No	Globs that limit the skill to matching files
disable-model-invocation	No	When true, it runs only when you type /skill-name
icon and color	No	The badge when the skill is used as a Custom Mode
metadata	No	Any extra key-value data

We set disable-model-invocation: true on 10 of our 22, among them the ones that commit, review a branch, draft a ticket or build a plugin. A job with side effects shouldn’t start because a request looked similar. Keep SKILL.md itself short and move long reference material into references/.

Cursor skills vs rules vs commands

Cursor’s own guidance is to use a rule when a short instruction is enough and a skill when the agent needs a repeatable process. Commands are the older form of the second, run only when someone types them.

	Rules	Skills	Commands
Holds	Short guidelines and constraints	Multi-step procedures	A prompt you run by name
Kept in	.cursor/rules/*.mdc	A folder with SKILL.md	Your user or workspace commands
Applies	Every chat, on matching files, when relevant, or when you @-mention it	When relevant, or when you run it	Only when you type it

To move older setups across, type /migrate-to-skills. It converts rules set to Apply Intelligently and turns slash commands into skills with disable-model-invocation: true. Rules with alwaysApply: true or globs stay as they are, and user rules aren’t migrated because they aren’t stored on the file system.

How to use your Claude Code and Codex skills in Cursor

You don’t need to do anything. Cursor loads .claude/skills/, .codex/skills/ and the same folders under your home directory, and the Mac build we checked (3.29.9) has those paths in its code. That is why our 22 can stay in .claude/skills.

Test the Claude Code extras, though. Of our 22, 15 use argument-hint, 14 use $ARGUMENTS and 3 use allowed-tools, and Cursor’s skills documentation mentions none of them. Run a Claude Code skill once in Cursor before you count on it. Our guides to Claude Code skills and Codex skills cover those two agents’ folders.

How to share skills with your team

Committing them is the simplest way, and it needs no particular plan. It is also how to reach automations and self-hosted workers, which won’t see a skill that lives only in your home folder.

On Teams and Enterprise plans you can publish a personal skill from ~/.cursor/skills/. Open it under Customize and Skills, then choose Publish, and Cursor packs it into a plugin and adds it to your team’s Default marketplace. Teammates still have to install it themselves, and the skill moves out of your folder into the plugin’s. A team can also import a repository as a team marketplace, with one import on the Teams plan and no limit on Enterprise.

Cloud Agents work differently. Only ~/.cursor/skills/ can sync to them, through Sync Skills for Cloud Agents under Settings and Agents, and those synced copies stay private to you.

How to see which skills get used

Cursor offers two views. Customize has a leaderboard of the plugins, skills and MCPs most popular across your team. The Analytics API, for Enterprise teams only, returns daily counts per skill at /analytics/team/skills and /analytics/by-user/skills. Its docs don’t say whether a count means the agent chose the skill or a person did, and that difference tells you whether a description is working.

The 15% at the top of this page counts calls to Claude Code’s Skill tool in that engineer’s local transcripts, in work repos only. Thirteen skills loaded 58 times and two browser-automation skills made up 25 of those, while the Stripe plugin, enabled the whole time, used none of its 10 skills. It is one person on one agent, so don’t read it as a rate for Cursor. We can’t give you one, because Cursor co-authored 7 of the 3,192 commits in our two repos from July 5 to October 3, 2026, which is too little to measure.

Zest’s Cursor extension records only the skills a person asks for by name, and rolls those up per engineer. That means a skill picked from the / menu, a command attached to the message, or a message that starts with /name. For the agent’s own steps it keeps only the tool’s name, so a skill Cursor loaded by itself doesn’t show up. The list also mixes in slash commands and Cursor’s built-ins, and nothing in the extension counts a Custom Mode as a skill. It comes closest to complete for a skill with disable-model-invocation: true.

FAQ

What are some useful skills for Cursor?

Start with the ones that ship with it: /create-skill to write your own, /review for a code review, /split-to-prs to break up a large change and /migrate-to-skills if you have old rules and commands. After that, the most useful skill is usually a procedure your own team repeats, such as a deploy or a release, because nobody outside your team can write it.

Is there a directory of Cursor skills?

Yes, a few. The Cursor Marketplace lists reviewed plugins, which can carry skills, and cursor.directory collects community plugins.

Why doesn’t my skill show up in Cursor?

Check that the file is named SKILL.md, that it sits in its own folder in one of the locations above, and that name matches the folder. Cursor discovers skills when it starts, so restart it after adding one. If the skill is listed but never runs by itself, rewrite its description, and run it once with / to confirm the instructions work.

Do Cursor skills work in the CLI?

Yes. Cursor 2.4 added skills to both the editor and the CLI.