Cursor rules vs skills: which to use for what
Cursor rules are .mdc files in .cursor/rules; skills are SKILL.md folders. How each applies, which fits which job, and what /migrate-to-skills converts.
- For
- Cursor users deciding between a rule and a skill
- Written for
- Cursor
- Time
- 8 min read · updated Nov 21, 2026
The short answer
A Cursor rule is a short instruction in an .mdc file under .cursor/rules, put in front of the model when its type says so: always, when a file matches, when the agent finds it relevant, or when you @-mention it. A skill is a folder with a SKILL.md that the agent loads on demand, and it can carry scripts. Cursor’s own guidance: use a rule when a short instruction is enough, and a skill when the agent needs a detailed, repeatable process. /migrate-to-skills converts only “Apply Intelligently” rules and slash commands, and leaves always-on and file-scoped rules alone.
People who search for “Cursor rules” are usually setting up Cursor for a project and have run into a second thing, skills, that sounds like it does the same job. It partly does. This page sets Cursor’s two pages side by side, the rules page and the skills page, plus the short “skills instead of rules” note in its help centre, all read on 21 November 2026. The rules page never mentions skills, so the comparison is ours, built from what each page says.
What a rule is
Cursor’s documentation describes rules as system-level instructions to Agent. When one applies, its contents are included at the start of the model’s context. There are four kinds.
Project rules must use the .mdc extension. The docs say a plain .md file in .cursor/rules is ignored by the rules system, because it has no frontmatter to say description, globs and alwaysApply, and that if you prefer plain markdown you should use AGENTS.md. Those three fields decide when the rule applies.
Two more details from the same page. A file mention such as @migration-template.sql inside a rule tells the agent where to look; the file’s contents are not inlined into the prompt, so anything that must always be in context belongs in the rule body. And the docs advise keeping rules under 500 lines and splitting large ones into composable pieces.
What a skill is
A skill is a folder with a SKILL.md, in .agents/skills/ or .cursor/skills/ in a project, or ~/.agents/skills/ or ~/.cursor/skills/ for you. When Cursor starts it discovers them, and the agent decides from each skill’s description when one is relevant. You can also apply one yourself by typing / in Agent chat. A skill can carry scripts/, references/ and assets/ folders that the agent reads or runs only when needed, which keeps context use down. Cursor’s skills page also calls skills portable across agents that support the Agent Skills standard; the rules page makes no such claim for .mdc files. Cursor agent skills covers the folders, the plugin route and Cloud Agents.
Side by side
Which one to write
Cursor’s help centre puts it in one sentence: use a rule when a short instruction is enough, and a skill when Agent needs a detailed, repeatable process to follow. Cursor gives “Use TypeScript for all new files” as a rule and “Deploy to staging: run tests, build, deploy, verify” as a skill. Applying that to common cases:
Rules that are rarely needed are a poor fit either way. The rules page lists what to avoid: copying whole style guides (use a linter), documenting every command, and covering edge cases that rarely apply. Its advice is to start simple and add a rule only when the agent repeats the same mistake.
Converting between them
Cursor includes a built-in /migrate-to-skills skill, which its docs date to Cursor 2.4. It converts two things: dynamic rules, meaning rules set to “Apply Intelligently” (alwaysApply: false or undefined, and no globs), and slash commands, at user and workspace level, which become skills with disable-model-invocation: true so they still run only when called. It does not convert rules with alwaysApply: true or with globs, because their triggering conditions differ from a skill’s, and it does not convert User Rules, which are not stored as files.
Step 1: Run the migration
Type
/migrate-to-skillsin Agent chat. The agent lists the eligible rules and commands and converts them.Step 2: Review the result
The new skills are written to
.cursor/skills/. Open each one and check that thedescriptionsays when to use it, since that is now what decides whether it runs.Step 3: Convert one rule by hand if you need to
To turn a single rule into a skill, ask Agent with
/create-skill, for example “turn@my-ruleinto a skill”, review the generated file, and delete the original rule if you no longer need it.
Skills that make a finished file
Rules shape how Cursor writes your code. Lookbk’s skills do a different job: they render something you can open, such as a landing page, a deck, a link-preview image or a title video, and each skill’s page shows what it made. The installer’s --shared flag writes ~/.agents/skills, which Cursor loads. These four are free, and the Cursor page lists the folders in one table.
Run the installer with the last part of a skill page’s address, restart Cursor, then type / in Agent chat.
Common questions
- What is the difference between Cursor rules and skills?
- A rule is a short instruction in an
.mdcfile under.cursor/rulesthat Cursor includes in the model’s context always, for matching files, when relevant, or when you @-mention it. A skill is a folder with aSKILL.mdthat the agent loads on demand, and it can carry scripts and reference files. Cursor’s help centre says to use a rule when a short instruction is enough and a skill for a detailed, repeatable process. - Why is my Cursor rule ignored?
- Project rules must be
.mdcfiles. The rules page says a plain.mdfile in.cursor/rulesis ignored because it has no frontmatter. For an “Apply Intelligently” rule, check that it has adescription; for “Apply to Specific Files”, check that theglobspattern matches the files in context. - Do Cursor rules still work now that skills exist?
- Yes. Both are documented side by side, and
/migrate-to-skillsleaves rules withalwaysApply: trueorglobsuntouched. - Should I convert my rules to skills?
- Only the ones that are really procedures. Always-on rules and file-scoped rules stay rules.
/migrate-to-skillsconverts only “Apply Intelligently” rules and slash commands, and you review the result afterwards. - Is
AGENTS.mda rule or a skill? - Neither. The rules page calls it a simple alternative to
.cursor/rules: plain markdown with no metadata, in the project root, and nested files apply to their folders. - Do Cursor rules work in other coding agents?
- The rules page makes no such claim. Cursor’s skills page calls skills portable across agents that support the Agent Skills standard, so a skill is the form to choose when you want to reuse the instructions elsewhere.
- Which wins when a Team Rule, Project Rule and User Rule disagree?
- The rules page gives the order Team Rules, then Project Rules, then User Rules. All applicable rules are merged, and earlier sources take precedence when guidance conflicts.
Sources
What this guide says about other companies’ tools comes from their own documentation, checked on Nov 21, 2026.
Did this guide help?
Read next
All guidesCursor agent skills: add a skill from GitHub, step by step
How to get a skill from a GitHub repository into Cursor: the folders it loads, the plugin route in its docs, Cloud Agents and the frontmatter.
Claude Code skills vs prompts, commands and plugins
What a skill is next to a prompt, a slash command, a subagent, a plugin, CLAUDE.md and a hook, with each definition taken from Anthropic’s Claude Code docs.
Where skills live: folders for every agent
The folders Claude Code, Codex, Cursor and other agents read skills from, which copy wins when two share a name, and what cloud agents can see.
Install a skill in any agent
Install a Lookbk skill in Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI or OpenCode: where each looks, how to check it loaded and how to run it.
Agent skills marketplaces: how each agent adds a catalog
There is no one skills marketplace for every agent. How Claude Code, Cursor, OpenCode, Gemini CLI, Codex and Copilot each add a catalog, from their own docs.
See a skill’s result before you install it.
Every skill page shows what it makes, what it needs and which agents can run it.



