Cursor rules vs skills: when to use each

Cursor rules vs skills comes down to how each loads. A Cursor rule is short guidance added to the agent's context. Depending on its settings, it applies every time, for matching files, or when the agent finds it relevant. A Cursor skill is a folder with a SKILL.md file. It holds a step-by-step procedure. Its full instructions load only when the task needs them, or when you call it with /. Use a rule for a constraint ("named exports only"). Use a skill for a workflow ("cut a release"). Two details are easy to miss when you migrate: a plain .md file in .cursor/rules/ is ignored, and /migrate-to-skills leaves always-on and glob rules untouched.

Cursor's behavior on this page comes from the official docs for rules and skills, plus Cursor's help pages on rules and skills, all read on November 10, 2026. This page doesn't measure how often the agent follows either one. The Skillpack commands below ran on Skillpack CLI 0.3.5 the same day. Disclosure: Skillpack is built by The Vibe Company, the author's company. It installs and shares skills. It doesn't manage Cursor rules, so this page isn't a ranking.

Cursor rules vs skills differ in loading, length and sharing

Cursor's skills help page sums it up in its own table: rules are "short coding guidelines and constraints," skills are "multi-step workflows and procedures."

Four kinds of rules, each loaded by its own frontmatter

Rules give the agent persistent context because, as Cursor's docs put it, large language models don't retain memory between completions. So when a rule applies, its contents go in at the start of the model context. Cursor has four kinds:

• Project rules live in .cursor/rules/, are version-controlled, and are scoped to your codebase.
• User rules are global preferences you set in Customize, then Rules. They sync with your Cursor account.
• Team Rules are managed from the Cursor dashboard on Team and Enterprise plans.
• AGENTS.md is plain Markdown in the project root or any subfolder, a simpler alternative to .cursor/rules.

How a project rule decides when to load

Each project rule is an .mdc file with three frontmatter fields. The rules docs spell out how they combine:

In the editor these show up as Always Apply, Apply to Specific Files, Apply Intelligently and Apply Manually. A rule scoped to React components looks like this:

---
globs: src/components/**/*.tsx
alwaysApply: false
---

- Use named exports, not default exports
- Co-locate styles in a module CSS file next to the component

Three details catch people out:

• The extension matters. Project rules must use .mdc. Cursor ignores a plain .md file in .cursor/rules/, because it has no frontmatter to say when it applies.
• @file mentions are not inlined. A rule that says "read @migration-template.sql" tells the agent where to look. The agent opens the file with its tools when it needs it. Anything that must always be in context has to sit in the rule body.
• CLAUDE.md is always on. Cursor reads CLAUDE.md like AGENTS.md, and applies it to every conversation whatever its frontmatter says, to stay compatible with projects that also use Claude Code. For conditional guidance, use a project rule instead. CLAUDE.md vs AGENTS.md vs SKILL.md explains how those root files relate to SKILL.md.

When rules conflict, Cursor applies them in the order Team Rules, then Project Rules, then User Rules, and earlier sources win. The old .cursorrules file in the project root is legacy. Cursor's help page says it "will be deprecated" and shows how to move it into an Always Apply rule.

A skill packages one task in a SKILL.md folder

A skill is a folder with a SKILL.md file that teaches the agent one task. It can also carry scripts/, references/ and assets/. Cursor follows the open Agent Skills standard, the same SKILL.md format Claude Code and Codex read. The Cursor skills guide covers folders, invocation and Cloud Agents in detail. Here is only what matters for the comparison.

Cursor discovers skills when it starts and shows the agent the available ones. The agent decides when a skill is relevant, and the docs describe skills as loading resources "on demand, keeping context usage efficient." You can also run one yourself by typing / and its name. That call attaches the skill to one message.

Two frontmatter fields bring skills closer to rules:

• paths limits a skill to files matching glob patterns, much like a rule's globs. Cursor still accepts the legacy globs field on skills, but new skills should use paths.
• disable-model-invocation: true stops the agent from picking the skill on its own. It then only runs when you type /skill-name, like an old slash command. Claude Code skills vs slash commands compares the two.

If the SKILL.md format itself is new to you, What is SKILL.md? goes through every field.

Loading sets the context cost of each

Loading is the real difference. A rule that applies is included in the prompt as written. An Always Apply rule is in every chat, whether the task needs it or not. That's why Cursor's best practices say to keep rules under 500 lines and split large ones. They also advise against copying whole style guides or listing commands the agent already knows.

A skill costs much less until it's used. The agent sees what skills exist, then reads the full instructions and any reference files only when it decides one fits. So a long release checklist works better as a skill than as an Always Apply rule.

The trade-off runs the other way for reliability. An Always Apply rule is always there. A skill depends on the agent matching your request to its description. You can call it with / instead, or keep it on for the whole session as a Custom Mode (Option+Enter on Mac, Alt+Enter on Windows). Some instructions must never be skipped, like "never edit files in dist/." Keep those in a rule.

Six questions pick a rule or a skill

Ask these questions about the instruction you're about to write:

1. Is it one or two sentences? Write a rule. "Use zod for all API validation" doesn't need a folder.
2. Must it apply to every edit, even when nobody thinks of it? Rule, set to Always Apply or scoped with globs.
3. Is it a sequence of steps with a clear start and end? Skill. "Run tests, build, deploy to staging, check the health endpoint" is the example Cursor uses.
4. Does it need a script, a template or a long reference doc? Skill. Rules can only point at files. Skills can ship them.
5. Should it only run when someone asks for it? Skill with disable-model-invocation: true. A deploy or a database migration belongs here.
6. Will teammates use Claude Code or Codex too? Prefer a skill. The same folder works there, while .mdc rules are a Cursor format.

A repo can hold both at once: a few short rules for standing constraints, and a few skills for the jobs people repeat every week.

One release-notes procedure, written both ways

Say your team keeps pasting a release-notes procedure into chat. Written as an Apply Intelligently rule, it lives in .cursor/rules/release-notes.mdc:

---
description: How to write user-facing release notes from merged PRs
alwaysApply: false
---

1. List PRs merged since the last tag.
2. Group them under New, Improved and Fixed.
3. One plain sentence per change.

As a skill, it moves to .cursor/skills/release-notes/SKILL.md and gets a name, a sharper description and a scope:

---
name: release-notes
description: Write user-facing release notes from merged pull requests. Use when asked for release notes, a changelog entry or "what shipped". Do not use for commit messages.
paths: "CHANGELOG.md, docs/releases/**"
disable-model-invocation: true
---

1. List PRs merged since the last tag with `git log --merges <last-tag>..HEAD`.
2. Group them under New, Improved and Fixed. Skip refactors and dependency bumps.
3. Write one plain sentence per change, from the user's point of view.

The skill version can grow. Add a scripts/list-merged-prs.sh and a references/style.md with examples, and none of it touches context until the skill runs. The name must match the folder name and use lowercase letters, numbers and hyphens only.

The Skillpack CLI checked both files. skillpack skills validate ./release-notes returned valid: true, with the Cursor-specific paths and disable-model-invocation fields in place. Pointed at .cursor/rules/, the same command failed with "SKILL.md is missing or oversized" (exit code 5). A rule folder isn't a skill package. It has to be converted first.

/migrate-to-skills skips always-on and glob rules

Cursor ships a built-in /migrate-to-skills skill, available since Cursor 2.4. Type it in Agent chat and the agent finds eligible rules and commands, converts them, and writes the results to .cursor/skills/ for you to review. Per the skills docs, it converts:

• Dynamic rules: rules set to Apply Intelligently, meaning alwaysApply: false (or unset) and no globs. They become standard skills.
• Slash commands: user and workspace commands become skills with disable-model-invocation: true, so they still only run when called.

It leaves alone rules with alwaysApply: true, rules with globs, and user rules, which aren't stored on the file system. That's the right call, since those rules have explicit triggers that a skill's on-demand model doesn't copy exactly.

To convert a single rule by hand, type /create-skill and ask the agent to "turn @my-rule into a skill." Review the result. Then delete the old rule if you no longer need it. Before you commit a migrated skill, check three things:

• The description says when to use the skill as well as what it does. The agent reads it to decide.
• Steps that only made sense as always-on context ("prefer composition") go back into a short rule.
• skillpack skills validate ./<skill-folder> passes, if you plan to share the skill outside Cursor.

Git first, then Team Rules or a team marketplace

Both start in git. Commit .cursor/rules/ and the team gets your project rules. Commit .cursor/skills/ or .agents/skills/ and the team gets your project skills too. Cursor's docs call skills version-controlled files. After that, the options differ.

For rules, Team and Enterprise plans have Team Rules, set in the dashboard. Admins can enforce a rule so members can't switch it off, and Team Rules support glob patterns. Rules from another repository arrive through a plugin. You import the repo in Customize, and it needs a .cursor-plugin/marketplace.json.

For skills, team marketplaces and publishing need Teams or Enterprise. On those plans, you can publish a personal skill from ~/.cursor/skills/ to the team's Default marketplace (Customize, then Skills, then Publish). Teammates choose to install it. Publishing installs it for no one else, unless an admin sets the plugin to Default On or Required. A Team Rule can simply be enforced. Plugins that bundle skills also install from the Cursor Marketplace. Personal skills only reach Cloud Agents if you turn on Sync Skills for Cloud Agents, and ~/.agents/skills/ never syncs.

Across agents and repos, a CLI that pins versions helps. Skillpack has no cursor target: --tools cursor returned "unknown coding tool" when tested. Cursor reads .agents/skills, so --tools opencode is the way to go:

skillpack install github:anthropics/skills/skills/frontend-design \
  --scope project --tools opencode --yes

That wrote .agents/skills/frontend-design/ and a .companion/skills.lock.json with the exact commit. Before copying, the CLI printed the source commit, "Executable files: none" and a warning that Skillpack only copies files and never runs package scripts. With the skill folder deleted, skillpack sync --frozen restored it (restored: 1) and left the lockfile unchanged. Commit both, so every laptop and CI run gets the same skill. The guides on sharing skills with your team and checking skills in CI go further.

Seven mistakes that break rules and skills

• A .md file in .cursor/rules/. Cursor ignores it. Rename it to .mdc and add frontmatter, or move the content to AGENTS.md.
• An Apply Intelligently rule with no description. The agent has nothing to match against. Cursor's FAQ tells you to check this when a rule doesn't apply.
• A giant Always Apply rule. It lands in every chat. Move the procedure into a skill and keep the rule to the constraints.
• Expecting @file contents in the prompt. They aren't inlined. Paste must-have content into the rule body.
• Two rules with the same filename. Cursor identifies rules by full path, so both apply if their conditions match.
• A skill that never triggers. Rewrite its description with the words you actually type, or call it with / to confirm it loads.
• A migrated skill that lost its scope. If the rule had globs, /migrate-to-skills skips it. If you convert it by hand, add paths to keep the same file scope.

Next: sort your .cursor/rules folder

Open .cursor/rules/ and sort what's there. Short constraints stay as rules. Anything with steps becomes a skill, through /migrate-to-skills or by hand. The Cursor skills guide covers the file format and invocation in more depth if a skill is also worth sharing with people who use Claude Code or Codex.