Cursor Skills: The Practical Guide

What Cursor skills are

Cursor is an AI code editor and coding agent. A skill is a directory containing a SKILL.md file: YAML frontmatter that tells Cursor when the skill is relevant, followed by markdown instructions to follow once it is.

Cursor implements the Agent Skills open standard, the same SKILL.md format used by Claude Code, Codex, Hermes Agent, and OpenClaw. Support arrived in Cursor 2.4, released 22 January 2026 — "Cursor now supports Agent Skills in the editor and CLI," per the release notes. The format itself is covered in SKILL.md.

The minimum skill is two fields:

---
name: deploy-staging
description: Deploys the app to the staging environment. Use when asked to ship, deploy, or push to staging.
---

Step-by-step instructions for the agent to follow.

A full skill directory:

.cursor/skills/deploy-staging/
├── SKILL.md         # required
├── scripts/         # optional: executable code
├── references/      # optional: docs loaded on demand
└── assets/          # optional: templates, images, data

Where Cursor looks for skills

This is the part worth reading even if you know the rest. Cursor scans eight directories, and half of them are not Cursor's.

The documentation is explicit about the second group: "For compatibility, Cursor also loads skills from Claude and Codex directories."

The practical consequence is larger than it sounds. If you already have skills in ~/.claude/skills/, they are available in Cursor with no copying, no symlinks, and no conversion. Every install guide for Cursor skills we found teaches .cursor/skills/ and stops there, which means a lot of people are hand-copying files they never needed to move. See how to install Cursor skills for what this does and doesn't cover, and agent skills compatibility for how the other runtimes compare — Cursor is the most permissive of them by some distance.

One wrinkle worth knowing if you also run Codex: the directory Cursor reads for compatibility is ~/.codex/skills, which Codex's own source marks as deprecated in favour of ~/.agents/skills. Both are covered here, but by different routes — ~/.codex/skills as a compatibility path, ~/.agents/skills as one of Cursor's four native ones.

Nested directories in a monorepo

Skills don't have to sit at the repository root. From the docs: "A .cursor/skills/ (or .agents/skills/) folder anywhere inside your repository is picked up, so monorepos can colocate skills with the package they apply to."

So apps/web/.cursor/skills/deploy/SKILL.md works, and lives next to the code it describes.

The frontmatter, including two fields that are Cursor's alone

name, description, and metadata come straight from the portable Agent Skills specification. paths and disable-model-invocation are Cursor's own additions, and they don't travel to other agents.

paths is not the same thing as a rule's globs

paths is the more interesting of the two, and the one most often confused with something else. From the docs: "Use the paths field to limit a skill to files that match one or more glob patterns. The skill is then only surfaced to the agent when it is reading or editing matching files."

---
name: migration-review
description: Reviews database migrations for destructive operations and missing rollbacks.
paths: "db/migrations/**/*.sql, prisma/migrations/**"
---

Every other skills system covered on this site matches a skill to the phrasing of a request. paths matches it to the files being touched. Those are genuinely different triggers, and for anything file-shaped — migrations, generated code, a config format with sharp edges — the second is far more reliable than hoping the description catches the right wording.

Cursor rules have a globs field that looks superficially similar. It isn't the same mechanism on the same object — see Cursor skills vs rules.

How Cursor decides to use a skill

Two paths:

• Automatic. "The agent is presented with available skills and decides when they are relevant based on context." This is why description carries most of the weight — it is the only thing the agent sees before deciding.
• Explicit. Type / in Agent chat and search by name.

Setting disable-model-invocation: true removes the automatic path and keeps the explicit one. That's the setting for anything with side effects you want triggered deliberately rather than inferred.

On context cost

Cursor says only that "Skills load resources on demand, keeping context usage efficient," and publishes no number.

That is worth stating plainly, because two of the neighbouring ecosystems do publish one: Codex caps its skill index at 2% of the context window or 8,000 characters, whichever is smaller, and OpenClaw documents roughly 97 characters per skill plus field lengths, with a configurable ceiling. Cursor gives you no equivalent budget to write against. We haven't measured one ourselves and won't invent one — but the general advice that follows from the other two systems still applies: a sprawling description is a functional cost, not just untidy writing.

The 19 skills Cursor already ships

Skills you don't install, available in every session:

/automate, /babysit, /canvas, /create-hook, /create-rule, /create-skill, /create-subagent, /cursor-blame, /loop, /migrate-to-skills, /review, /review-bugbot, /review-security, /sdk, /shell, /split-to-prs, /statusline, /update-cli-config, /update-cursor-settings.

Two of those are the ones to reach for first. /create-skill writes a new skill for you. /migrate-to-skills converts existing rules and slash commands — and its conversion criteria are the most precise answer anyone has published to "which of my rules should have been skills," which is why the comparison page is built around them rather than around opinion.

Skills, rules, commands, plugins, and MCP

Five things Cursor supports that get conflated constantly:

The distinction that costs people the most time is the first two, covered in full here. The one people get wrong in a more interesting way is the last two: a plugin isn't an alternative to a skill, it's an envelope that skills and MCP servers travel in together. That packaging layer is now a published standard of its own — see Agent Skills vs MCP.

Plugins: how skills get distributed

A Cursor Plugin is a directory with a .cursor-plugin/plugin.json manifest:

my-plugin/
├── .cursor-plugin/
│   └── plugin.json      # only `name` is required
├── rules/
│   └── coding-standards.mdc
├── skills/
│   └── code-reviewer/
│       └── SKILL.md
└── mcp.json

Skills inside a plugin follow the same skills/<name>/SKILL.md convention as everywhere else. Install from Customize in the sidebar, choosing project or user scope.

Cursor also accepts the vendor-neutral form: per the docs, "Agent Plugins use a root plugin.json manifest and load in Cursor without modification." That's the Agent Plugins standard, whose 1.0.0 specification lists Core Maintainers from Amazon, Cursor, Microsoft, OpenAI, and Vercel on its initial technical steering committee.

Worth noting for anyone browsing the official marketplace repository: plugins are not all skill packages. Reading the manifests directly, the third-party integrations there are predominantly MCP-only — the Gmail plugin is a plugin.json and an mcp.json with no skills/ directory at all — while Cursor's own first-party plugins are the ones carrying skills. "Plugin" tells you how something is packaged, not what's inside it.

Common questions

Do I need to restart Cursor after adding a skill? The documentation doesn't state a reload requirement, and we haven't tested it. If a new skill doesn't appear, check the directory and the frontmatter first — name must match the parent folder name exactly, and the filename must be SKILL.md in that exact case. Agent skills not working covers the rest.

Which directory should I use? .cursor/skills/ for anything project-specific you want committed, ~/.cursor/skills/ for personal ones. Use .agents/skills/ instead if you want the same file picked up by Codex or OpenClaw as well.

What happens if the same skill name exists in two directories? Not documented, and we haven't tested it. Codex is explicit that duplicates both appear without merging, and Claude Code documents a precedence chain; Cursor says neither. Avoid the collision rather than relying on a guess.

Limitations and caveats

• We have not run Cursor or installed any skill. Everything here is either documented behavior or read directly from the cursor/plugins repository and the Agent Plugins specification, and this page says which throughout.
• Cursor publishes no context budget for skills, no rules-vs-skills precedence, and no duplicate-name resolution rule. Where the docs are silent, this page says so rather than filling the gap.
• Cursor's own documentation describes skills slightly differently in two places — the Agent Skills page describes automatic relevance-based selection plus explicit / invocation, while the customization help page frames skills as invoked on demand. The full picture needs both, plus disable-model-invocation and paths, which is how it's presented above.
• Repository details (star counts, licences, push dates) are snapshots taken 16 August 2026 and will drift.

Sources

• Cursor — Agent Skills (official docs) — directories, frontmatter, built-in skills, migration criteria
• Cursor — Rules (official docs) — rule types, .mdc frontmatter, precedence
• Cursor — Plugins (official docs) — plugin structure and the Agent Plugins pointer
• Cursor 2.4 changelog — release date and editor/CLI support
• cursor/plugins (GitHub) — manifests and schemas read directly
• Agent Plugins Specification — the portable plugin format
• agentskills.io — the open standard Cursor implements