Cursor skills: how Agent Skills work in Cursor

What are Cursor skills?

Cursor skills are folders with a SKILL.md file that teach Cursor's agent how to do a specific task, such as deploying to staging or running a security audit. Cursor loads them from .cursor/skills/ or .agents/skills/ in your project (or the same folders in your home directory), lets the agent pick one when it's relevant, and lets you run one yourself by typing / and its name.

Skills in Cursor follow the open Agent Skills standard, the same format Claude Code and Codex use. Cursor's skills documentation describes them as "a portable, version-controlled package that teaches agents how to perform domain-specific tasks." Because the format is shared, a skill written for another agent usually works in Cursor as is, and Cursor goes out of its way to find skills stored in Claude Code and Codex folders.

Cursor's help center draws the line with rules this way: skills are "more detailed than rules and designed for multi-step workflows." If you already use Cursor rules, think of skills as the place for procedures, and rules as the place for short standing guidelines.

Where does Cursor look for skills?

Cursor discovers skills automatically when it starts. Per the docs, it reads these folders:

Each skill is its own folder, and the folder name is the skill's name:

.cursor/
└── skills/
    └── deploy-app/
        ├── SKILL.md
        ├── scripts/
        │   └── deploy.sh
        └── references/
            └── REFERENCE.md

Three details from the docs are worth knowing:

• Category folders are fine. Cursor walks the skills folder recursively, so .cursor/skills/shipping/land-it/SKILL.md works. The skill is still called land-it; the shipping folder is only for organizing.
• Monorepos get scoping for free. A .cursor/skills/ folder anywhere in the repo is picked up, and skills in a nested folder are scoped to it. A skill in apps/web/.cursor/skills/ only shows up when the agent works with files under apps/web/.
• Personal skills stay local. Skills in ~/.cursor/skills/ don't reach Cloud Agents unless you turn on Sync Skills for Cloud Agents under Settings, Agents. Only ~/.cursor/skills/ syncs; ~/.agents/skills/ and project skills are not copied.

To see what Cursor found, open Customize in the sidebar and go to Skills.

How does Cursor's agent pick a skill?

When Cursor starts, it gives the agent the list of available skills, and the agent "decides when they are relevant based on context." What it reads to decide is the description in each skill's frontmatter. So the description does most of the work: say what the skill does and when to use it, in words that match how you'd ask for the task. Our guide on how to write a SKILL.md covers descriptions that get picked up.

The frontmatter fields Cursor documents:

Two of these change how the agent chooses. paths keeps file-specific guidance out of unrelated work:

---
name: react-component-patterns
description: Conventions for writing React components in this codebase.
paths:
  - "**/*.tsx"
---

And disable-model-invocation: true turns a skill into what Cursor calls "a traditional slash command": the agent never applies it on its own, only when you call it.

How do you invoke a skill in Cursor?

You have three options, all from Agent chat:

1. Type / and search for the skill name, for example /write-tests. The docs say a skill invoked this way "attaches to one message."
2. Type @ and select the skill to attach it as context, per Cursor's skills help page.
3. Use it as a Custom Mode to keep it on for the whole session. Press Option+Enter on Mac or Alt+Enter on Windows. An active mode shows a badge in the chat input, styled by the skill's icon and color fields.

Cursor also ships its own built-in skills that appear next to yours. A few useful ones from the list in the docs:

How do you create a skill in Cursor?

The fastest route is /create-skill: type it in Agent chat and describe the skill, and Cursor's built-in skill "walks you through naming, structuring, and saving a new skill." To write one by hand, make a folder in .cursor/skills/ and add a SKILL.md:

---
name: deploy-app
description: Deploy the application to staging or production environments. Use when deploying code or when the user mentions deployment, releases, or environments.
---

# Deploy App

Deploy the application using the provided scripts.

## Usage

Run the deployment script: `scripts/deploy.sh <environment>`

Where `<environment>` is either `staging` or `production`.

That example comes from Cursor's docs, which also note that scripts can be in any language and should be referenced by relative paths from the skill root. Keep SKILL.md focused and move long reference material into references/, since the agent loads those files only when needed.

If you already have a prompt you reuse in Cursor, Kipt's free SKILL.md generator turns it into a valid SKILL.md in your browser, with a name and a starting "Use when" description. For other ways to build a skill, including Anthropic's tool that tests skills, see skill creator.

Skills vs Cursor rules vs AGENTS.md

Cursor gives you three places to put instructions, and they do different jobs.

The help center sums up the choice: "Use a rule when a short instruction is enough. Use a skill when Agent needs a detailed, repeatable process to follow." Rules are covered in our Cursor rules guide, and AGENTS.md has its own guide.

If you have rules that should really be skills, Cursor's built-in /migrate-to-skills converts them. Per the docs, it converts "Apply Intelligently" rules (no alwaysApply and no globs) into skills, and turns slash commands into skills with disable-model-invocation: true. Rules that always apply or use globs are left alone, and user rules aren't migrated because they don't live on the file system.

How do you share one skill between Cursor, Claude Code and Codex?

The folders overlap, but no single folder is read by all three, so it helps to know who reads what:

• Claude Code reads .claude/skills/ in the project and ~/.claude/skills/ for personal skills, per its skills docs.
• Codex reads .agents/skills/ from your working folder up to the repo root, and ~/.agents/skills/, per OpenAI's Codex docs.
• Cursor reads both of those, plus .cursor/skills/ and .codex/skills/.

So a skill in .claude/skills/ works in Claude Code and Cursor, and a skill in .agents/skills/ works in Codex and Cursor. If you use Claude Code and Cursor, .claude/skills/ is the simplest shared home. If you use all three, the skill needs to be in both .claude/skills/ and .agents/skills/. Cursor's docs don't say how it handles the same skill found in two folders, so check Customize, Skills for duplicates after you set this up.

A few habits keep one file working everywhere. Stick to name and description for anything that must work across tools, since fields like paths or icon are Cursor features. Describe actions ("run the test suite") rather than naming one agent's tools. And commit the folders, so teammates get the skills with the repo. To share a personal skill with a Cursor team instead, the plugins docs describe publishing it to your team marketplace from Customize, Skills.

Keep your skills in one place

Once you have skills in several tools and repos, the hard part is keeping one current copy. Kipt stores your prompts and skills as Markdown in a private GitHub repo you own and installs every skill into Claude Code or Codex with one npx skills add command. Because Cursor also reads Claude Code's and Codex's skill folders, skills installed there show up in Cursor too. For how Cursor and Claude Code compare more broadly, see Claude Code vs Cursor.