Cursor rules vs Cursor skills: when to use each (and how to migrate)

Cursor has two ways to give the agent standing instructions, and most .cursor directories in the wild are using the wrong one for at least half their content. Rules came first: .mdc files under .cursor/rules/ that Cursor injects into context according to a few frontmatter switches. Skills came later: SKILL.md folders under .cursor/skills/ that Cursor loads only when a task matches. Both still exist, both are supported, and the difference between them is not stylistic. It is about what costs tokens on every message and what the agent can find on its own.

This article covers the mechanics of each, the decision rule, the conflict behavior, and what /migrate-to-skills will and will not do for you.

Rules: the always-on layer

A Cursor rule is a Markdown file with an .mdc extension and a small frontmatter block:

---
description: "Conventions for React components in this repo"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---
- Use function components with named exports.
- Co-locate tests as `Component.test.tsx`.
- Never import from `../../` more than two levels; use the `@/` alias.

The frontmatter controls when the rule enters context:

Setting	Behavior
alwaysApply: true	Injected into every conversation in the project, every message
globs set	Injected when the agent is working with a file matching the pattern
Neither, with a description	”Apply Intelligently”: the agent reads the description and decides whether to pull the rule in
Manual	Only when you reference the rule with @rule-name

Rules can live at the project level (.cursor/rules/) or the user level (Cursor settings), and legacy .cursorrules files at the repo root still work. The thing to notice is that alwaysApply rules are paid for on every single turn. A 300-line style guide with alwaysApply: true is roughly 3,000 tokens of overhead on a request to rename a variable.

Skills: the on-demand layer

A Cursor skill is a folder with a SKILL.md, following the open Agent Skills specification that Cursor shares with Claude Code, Codex, and GitHub Copilot:

---
name: react-component
description: "Scaffold a new React component in this repo's conventions: function component, named export, co-located test, Storybook story. Use when asked to create, add, or scaffold a component."
paths: ["src/components/**"]
---
## Steps
1. Create `src/components/<Name>/<Name>.tsx` with a named function export.
2. Create `<Name>.test.tsx` using the shared render helper in `test/utils.tsx`.
3. Create `<Name>.stories.tsx` with a default story.
4. Export from `src/components/index.ts`.

Skills load in stages. At startup Cursor reads only name and description (about 100 tokens per skill). When your request matches, or when you pick the skill from the / menu, the body loads. Files under scripts/, references/, and assets/ load only when the body refers to them. A repo with forty skills costs about as much idle context as one medium rule.

Cursor’s skill-specific frontmatter fields:

Field	Effect
name	Required. Lowercase, matches the folder name.
description	Required. Drives automatic triggering.
paths	Glob patterns; the skill applies only to matching files. The closest thing to a rule’s globs.
disable-model-invocation	true makes the skill manual-only, via /skill-name.
icon, color	Badge appearance when the skill is pinned as a Custom Mode.
metadata	Free-form string map.

Skills are discovered from .cursor/skills/ and .agents/skills/ in the project, from ~/.cursor/skills/ and ~/.agents/skills/ for personal skills, and, for compatibility, from the Claude and Codex directories in the repo. Nested skills in monorepo subfolders are discovered recursively and scoped to their folder.

The decision rule

A rule is a fact or constraint the agent must always respect. A skill is a procedure the agent should follow when doing a specific task.

Apply that to a typical .cursor/rules/ directory and it splits cleanly:

Content	Rule or skill	Why
”We use pnpm, not npm”	Rule (alwaysApply)	Relevant to every command the agent might run
”Tests live next to source files”	Rule (globs: ["src/**"])	A constraint on file placement
”Never commit to main”	Rule (alwaysApply)	A safety constraint
”How to add a database migration”	Skill	A multi-step procedure, needed rarely
”How to write a release note”	Skill	Procedure plus a template in assets/
”Our API error-envelope shape”	Rule (globs on API routes) or a references/ file in an API skill	A constraint, but only relevant in one area
”Steps to debug a flaky Playwright test”	Skill	Procedure, long, occasionally needed
”Deploy to staging”	Skill with disable-model-invocation: true	Side effects; you want to trigger it

If a rule file is longer than a screen and reads like a checklist, it is a skill wearing a rule’s file extension.

What happens when they conflict

Rules are in context before the skill loads, and the rule frontmatter tells the agent it is a standing instruction. When independent testers wrote a rule and a skill that directly contradicted each other, the agent followed the rule and cited the .mdc file. Treat that as the expected behavior: rules win.

The practical consequences:

• Never put a contradicting instruction in a skill and expect it to override a rule. Fix the rule.
• If a skill needs to relax a constraint for one task (say, a migration skill that must touch a normally protected directory), state the exception in the rule itself (“…except when running the db-migration skill”).
• Keep rules short so there is less to conflict with.

Invocation: how you trigger each one

Action	Rule	Skill
Automatic	By alwaysApply, globs, or intelligent-apply description	By description, optionally narrowed by paths
Force for one message	@rule-name	Type /, pick the skill
Keep active all session	alwaysApply: true (permanently)	Custom Mode: Option+Enter on Mac, Alt+Enter on Windows
Prevent automatic use	Manual rule type	disable-model-invocation: true

The Custom Mode shortcut is the answer to “I want this skill on for the next hour but not forever.” That used to require a temporary alwaysApply rule.

Migrating with /migrate-to-skills

Cursor 2.4 added a built-in /migrate-to-skills skill. Run it in a project and it converts:

• Dynamic rules (intelligent-apply, the ones with a description and no alwaysApply) into standard skills. The description carries over as the trigger.
• Slash commands into skills with disable-model-invocation: true, so they remain manual.

It deliberately does not convert:

• Rules with explicit triggering conditions (alwaysApply: true, or globs). Those are constraints and stay as rules.
• User-level rules in your Cursor settings.

After running it, review the generated descriptions. A rule description was written to help the agent decide whether to read a constraint; a skill description should say what task the skill performs and when to use it, ideally with a “Use when…” clause containing the words a user would actually type.

Cloud Agents, SSH, and background workers

A difference that bites teams: user-level skills are not copied to Cloud Agents, remote SSH sessions, or self-hosted workers. Only skills committed to the project (or baked into a worker image) exist there. User-level rules have the same limitation. If a Cloud Agent must follow it, it goes in the repo, whichever format you choose.

Portability: the biggest non-obvious difference

A .mdc rule works only in Cursor. A SKILL.md works in Cursor, Claude Code, OpenAI Codex, GitHub Copilot, Gemini CLI, Windsurf, and 60+ other agents that read the Agent Skills spec. If anyone on your team uses a second tool, or you publish anything for other people, that alone decides the format for procedural content.

Skills also have a registry ecosystem that rules never had. SkillMD lists 25,000+ skills with safety review, and installing one into Cursor is one command:

npm i -g skillmds
skillmd add anthropic/skill-creator -a cursor

Or, to install into every agent detected on your machine at once, drop the -a cursor. The Cursor agent guide has the paths and the manual copy steps.

A migration checklist

1. Run /migrate-to-skills. Let it convert the dynamic rules and commands.
2. Open each remaining rule. If it is longer than 30 lines or contains numbered steps, move the steps to a skill and leave a one-line constraint behind if needed.
3. Add paths to any skill that should only fire in one part of the repo.
4. Add disable-model-invocation: true to any skill with side effects.
5. Check for contradictions between remaining rules and new skills. Fix them in the rule.
6. Run skillmd lint .cursor/skills/* to catch names that do not match their folder, descriptions over 1,024 characters, and missing licenses.
7. Commit the skills. Personal skills do not reach Cloud Agents.

Further reading

• Claude skills vs Cursor skills
• AI agent skills: the complete guide
• One SKILL.md for every agent: the compatibility matrix
• Writing skills that get used
• Cursor install guide