Cursor Skills vs Rules

The 10-second decision test: constraint or procedure?

If you are deciding whether to write a Cursor rule or a Cursor skill, use this fundamental distinction:

Is it a standing constraint or an on-demand procedure?
├── Standing constraint, code style, or invariant  →  Write a RULE (.cursor/rules/*.mdc)
│   (Always active or injected automatically when editing matching files)
│
└── Multi-step workflow, task, or procedure        →  Write a SKILL (SKILL.md)
    (Loaded on demand when relevant, file-scoped via paths, or triggered via /)

• Write a Rule when you need standing guidance that Cursor must adhere to continuously (e.g., "Always use TypeScript strict mode", "Follow functional React conventions in components/**", "Never use lodash").
• Write a Skill when you need a repeatable procedure that should only execute when relevant (e.g., "Review database migrations", "Deploy to staging", "Generate API client fixtures", "Audit accessibility").

---

Quick triage: rule or skill for your situation?

---

Architectural comparison: rules vs skills

Cursor's own documentation neatly summarizes the boundary: use rules for "short coding guidelines and constraints"; use skills for a "detailed, repeatable process."

---

What /migrate-to-skills tells us about Cursor's architecture

Cursor ships a built-in skill called /migrate-to-skills. To automate conversions, Cursor engineers defined mechanical criteria for what belongs in each system.

From Cursor's official documentation:

Dynamic rules: Rules that use the "Apply Intelligently" configuration—rules with alwaysApply: false (or undefined) and no globs patterns defined. These are converted to standard skills.
Slash commands: Both user-level and workspace-level commands are converted to skills with disable-model-invocation: true.

The official conversion matrix

The underlying design principle is clear: deterministic triggers (always, file glob, or explicit @ reference) belong in rules. Whenever inclusion requires semantic judgement based on what the user is doing, the instruction belongs in a skill.

---

paths vs globs: the critical difference

Both Cursor rules and skills support file-matching patterns, but they behave very differently:

# In a rule (.cursor/rules/api-routes.mdc):
globs: "src/api/**/*.ts"
# Behavior: Injects the entire rule text directly into the system prompt 
# whenever a matching file is opened or edited.

# In a skill (.cursor/skills/audit-api/SKILL.md):
paths: "src/api/**/*.ts"
# Behavior: Marks the skill as ELIGIBLE for execution when matching files 
# are touched, but loads the skill instructions only if the model decides to run it.

• Rule globs = Direct Prompt Injection: Use globs on a rule for short, immediate instructions (e.g., "In API routes, always use the Result<T, E> pattern").
• Skill paths = Scoped Eligibility: Use paths on a skill for elaborate workflows that have executable scripts or reference documentation (e.g., a 200-line API contract testing checklist).

---

What Cursor does not document: two critical myths

Two common claims about rules and skills circulate in community discussions that are not backed by official documentation:

Myth 1: "Rules always take precedence over skills in conflicts"

Cursor documents a strict precedence order for rules: Team Rules → Project Rules → User Rules. However, Cursor publishes no documented precedence order between a rule and a skill.

If an always-on rule states "Never run integration tests locally" and a skill procedure instructs "Run integration tests before pushing", the behavior is non-deterministic. Do not rely on unverified precedence: resolve conflicting guidance in your configuration directly.

Myth 2: "Moving rules to skills saves a known amount of context tokens"

Cursor states that skills "load resources on demand, keeping context usage efficient," but does not publish a numeric context budget.

In contrast, Codex caps its skill catalog index at 2% of context or 8,000 characters, and OpenClaw documents ~97 characters per skill. While migrating large procedural rules to skills is directionally best practice, Cursor publishes no exact token count.

---

How to migrate rules to skills in practice

If your workspace has accumulated dynamic rules or legacy slash commands:

1. Run the migration skill: In Cursor Agent chat, type:

   /migrate-to-skills
   

2. Review the proposed conversion: Cursor scans .cursor/rules/ and identifies dynamic rules and slash commands.
3. Audit the output:
   • Verify that the resulting folder names in .cursor/skills/<name> match the name: field in each generated SKILL.md.
   • Watch for false conversions: if a rule was configured as "Apply Intelligently" but was actually meant to be an invariant across your whole codebase, reconfigure it as alwaysApply: true or move it to AGENTS.md.

---

Caveats

• We have not run Cursor or /migrate-to-skills. The conversion criteria and frontmatter attributes are verified directly from Cursor's official documentation.
• The claim that rules override skills in conflicts is undocumented by Cursor and is not treated as fact here.
• Slash command unification with disable-model-invocation: true aligns with similar architectural changes in Claude Code and OpenClaw.

---

Sources

• Cursor — Agent Skills Official Documentation — Conversion criteria for /migrate-to-skills, paths, and disable-model-invocation.
• Cursor — Rules Official Documentation — Rule types, .mdc format, and Team/Project/User precedence.
• Cursor — Customization Help Center — Distinction between rules, skills, and commands.
• Claude Code — Skills Documentation — Industry-wide merging of commands into skills.
• Agent Skills Open Standard — Specification for SKILL.md.