Cursor Rules vs Agent Skills: I Tested Both. Here's When Each One Actually Works.

Someone told me Cursor deprecated rules in favor of Agent Skills. I went and tested it. Rules are...

title: Cursor Rules vs Agent Skills: I Tested Both. Here's When Each One Actually Works. published: true tags: cursor, ai, productivity, webdev series: cursor-experiments

Someone told me Cursor deprecated rules in favor of Agent Skills. I went and tested it.

Rules are not deprecated. They do different things. Here's what I found.

The setup

I created identical instructions in both formats and ran them through Cursor's agent to see how each one behaves.

As a rule (.cursor/rules/jsdoc.mdc with alwaysApply: true):

---
description: JSDoc rules
alwaysApply: true
---
Always add JSDoc comments to exported functions.

As a skill (.cursor/skills/jsdoc/SKILL.md):

# JSDoc Skill
Always add JSDoc comments to exported functions.

Test 1: Does each one work on a relevant task?

Prompt: "Create a utility function that formats dates"

• Rule: Added full JSDoc with @param and @returns. Followed the instruction.
• Skill: Same result. Full JSDoc, followed the instruction.

When the task matches what the instruction is about, both rules and skills work fine.

Test 2: Does each one load on an UNRELATED task?

This is the test that matters. I gave each setup a marker instruction ("add a // RULE-LOADED comment" or // SKILL-LOADED) and asked Cursor to write a Python hello world script. Nothing to do with JSDoc or JavaScript.

• Rule (alwaysApply: true): The marker comment showed up in the Python file. The rule loaded even though the task had nothing to do with it.
• Skill: No marker. The skill did not load at all.

This is the core behavioral difference. Rules with alwaysApply: true are injected into every prompt regardless of relevance. Skills only load when the agent decides the task is relevant.

Test 3: Cross-tool discovery

Cursor's docs say it auto-discovers skills from .claude/skills/ and .codex/skills/ for cross-tool compatibility. I put a skill in .claude/skills/test/SKILL.md with a marker instruction and ran a relevant task.

The skill did not load. Cursor didn't find it.

This might be a CLI vs GUI difference, or it might only work with .cursor/skills/. Either way, the "put it in .claude/skills/ and every tool finds it" claim didn't hold up in my testing.

When to use which

Based on these results:

Use rules when:

• You want something enforced on every task (coding style, naming conventions, framework patterns)
• You need it to apply even when the task seems unrelated (like "preserve comments" applying during a refactor)
• You want predictable, always-on behavior

Use skills when:

• You have procedural, multi-step workflows ("here's how to deploy to staging")
• You want the instruction to load only when relevant (saves context window space)
• You're building something portable across tools (once cross-tool discovery works reliably)

The migration question

Cursor has a /migrate-to-skills command mentioned in their docs. I wasn't able to test it through the CLI (it appears to be GUI-only). The v2.4 changelog positions skills as complementary to rules: "compared to always-on, declarative rules, skills are better for dynamic context discovery and procedural how-to instructions."

That framing matches what I tested. Rules and skills aren't competing. They handle different use cases.

What this means for your .cursor/rules/ files

If you have .mdc rules with alwaysApply: true for things like coding style, error handling patterns, or framework conventions, keep using them. They work, they're reliable, and they load every time.

If you're building multi-step workflows or deployment procedures, skills are the better fit. They keep the context window clean by only loading when needed.

Don't migrate everything to skills because someone said rules are deprecated. They're not.

Links

• 77 free .mdc rules if you need a starting point
• cursor-doctor validates your rules and can auto-generate them from your stack (npx cursor-doctor --generate)
• Agent Skills spec for the open standard
• Cursor docs on rules and skills

Need help sorting out your rules setup? I do $50 async audits. Code FIRSTAUDIT for 20% off.

📋 I made a free Cursor Safety Checklist — a pre-flight checklist for AI-assisted coding sessions, based on actual experiments.

Get it free →