Cursor rules vs Cursor skills

A Cursor rule is reusable instructions scoped by project, file pattern, relevance, or manual selection: it’s how you tell Cursor’s agent about codebase conventions that should apply predictably. A Cursor skill packages a task-specific workflow in SKILL.md, with scripts and references, that the agent loads when doing that task. Reach for a rule when you want a convention to apply automatically to matching files. Reach for a skill when you want a full procedure the agent pulls in only when relevant. As of September 2026, Cursor documents both side by side rather than treating one as a replacement for the other.

Choose a rule when

• You want a convention to apply automatically to particular files or the whole project, for example “use our error-handling pattern in every **/*.tsx file.”
• The behavior should be predictable from scope alone: Always Apply, Apply to Specific Files, Apply Intelligently, or Apply Manually, per Cursor’s rules docs.
• The instruction is short, closer to a standing convention than a multi-step procedure.

Choose a skill when

• The task is a multi-step procedure that benefits from supporting files (a references/ checklist, a scripts/ helper), not just a paragraph of guidance.
• You want the same SKILL.md format to be portable to other hosts, since Cursor skills follow the Agent Skills specification.
• The agent should load it only when doing that specific task, not on every matching file.

Worked example

Say a project wants two things: every .tsx file reviewed against an internal error-handling convention, and a separate, occasional “explain this error” workflow. The first is a natural fit for a rule: a file at .cursor/rules/error-handling.mdc with frontmatter description, globs: ["**/*.tsx"], set to Apply to Specific Files, so it’s pulled in when a matching file is in the agent’s context, with no explicit invocation needed. Cursor rules.

The second is a better fit for a skill: our explain-error SKILL.md, with instructions and a references/checklist.md, placed at .cursor/skills/explain-error/ (or the shared .agents/skills/explain-error/ path Cursor also documents). It only enters play when the agent judges that an error-explaining task matches its description. Cursor skills.

We tested explain-error’s discovery and invocation on Codex, not Cursor. Cursor wasn’t installed in our test environment, so every Cursor-specific claim in this example is what Cursor’s docs describe rather than something we watched happen.

At a glance

What we checked

Everything on this page is from Cursor’s own documentation (rules and skills), checked September 27, 2026, not from our own testing. Cursor wasn’t installed in our test environment on that date, so none of the Cursor-specific behavior here (rule attachment, skill discovery, the /migrate-to-skills command) has been confirmed hands-on by us.

The one hands-on result we have is Codex, not Cursor: our explain-error SKILL.md was discovered and correctly invoked on Codex CLI 0.157.1 at .agents/skills/explain-error/, the same shared path Cursor also documents for skills. That’s suggestive that the shared convention is real across hosts, but it isn’t evidence that Cursor itself loads from it; only a direct Cursor test would confirm that.

What we didn’t check: no Cursor testing at all, no rule attachment, no skill discovery, no /migrate-to-skills run. Treat every claim above as documentation until someone runs it on an installed Cursor build.

Sources

• Cursor rules
• Cursor skills
• Agent Skills specification