Claude Skills vs Cursor Rules: Which Should You Use?

If you write code with AI in 2026, you’ve probably ended up with instructions in two places: a .cursor/rules folder that Cursor reads, and a skills directory that Claude reads. They solve the same problem, teaching your AI how your project works so you stop repeating yourself, and they solve it differently enough that picking wrong costs you tokens, sync headaches, or both.

We run SkillProof, where we install and test Claude skills on a clean machine before listing them. That gives us a specific vantage point on this comparison: we’ve converted dozens of rule files into skills during testing, and we’ve watched both formats fail in ways their documentation doesn’t mention.

TL;DR: Cursor rules are simpler and live closer to your editor. Claude skills are more capable and travel with you across tools. Rules win when the instruction should apply to every file matching a pattern, always. Skills win when the instruction is conditional, bundles supporting files, or needs to work outside one IDE. Most developers who use both tools should keep project conventions in a shared file and put everything conditional into skills.

	Cursor rules	Claude skills
Scope	Per-project (.cursor/rules/) or per-user (settings)	Global (~/.claude/skills/) or per-project (.claude/skills/)
Trigger	Glob patterns, always-on, or description match	Description match, decided by the model
Payload	Plain instructions	Instructions plus scripts, templates, reference files
Portability	Cursor only	Claude Code, Claude Desktop, claude.ai, the Agent SDK
Context cost	Full rule text when attached; always-on rules ride every request	~100 tokens of metadata until triggered, then the body
Ecosystem	Large; thousands of shared .cursorrules on GitHub	Smaller but growing; includes Anthropic’s official set
Testing culture	Effectively none	Mostly none; we test ours

Now the detail, because the table hides the interesting parts.

What Cursor rules actually are

Cursor has two generations of the same idea. The original .cursorrules file sits at your project root: one plain-text file of instructions injected into every AI request in that repo. It’s deprecated but still honored, and a huge share of public examples still use it.

The current system is a .cursor/rules/ directory of .mdc files, each with frontmatter controlling when it applies. Four modes: Always (every request), Auto Attached (fires when a file matching a glob is in context, so globs: *.tsx attaches only during React work), Agent Requested (the model reads the description and decides), and Manual (only when you @-mention it). Cursor also reads AGENTS.md, which matters later in this article. There are user-level rules too, set in Cursor’s settings, which apply across all projects.

If that sounds a lot like a skill’s trigger system, it partly is. Agent Requested rules are description-matched exactly the way skills are. The difference is what happens after the trigger, and we’ll get there.

Where rules genuinely win

We test Claude skills for a living, so you’d expect us to argue for skills everywhere. We won’t, because rules have real strengths.

Always-on rules are simpler to reason about. A rule with alwaysApply: true is in the context of every request, period. There’s no trigger to misfire, no description to get wrong, no “why didn’t it activate” debugging session. When we test skills, trigger failure is one of the two most common defects we find. Rules in always or glob mode structurally cannot have that defect. For a small set of hard project laws (“never touch the generated files in src/gen/”), a dumb always-on rule beats a clever conditional one.

Glob scoping is precise. globs: **/*.sql means your SQL conventions attach during SQL work and never otherwise. The mapping from file type to instruction is mechanical and predictable. Skills approximate this with description wording (“use when writing SQL”), which works well in practice but is a judgment call by the model rather than a pattern match.

They live where you type. Rules integrate with Cursor’s Tab completion, inline edits, and agent mode without any setup. Nothing to install, no directory conventions to learn beyond dropping files in a folder.

The ecosystem is enormous. Search GitHub for .cursorrules and you’ll find thousands of files covering nearly every framework. Quality varies wildly, but coverage doesn’t.

What skills do that rules can’t

If you’re new to the format, our full guide to Claude skills covers the anatomy. Here’s the comparison-relevant part.

Conditional triggering with real economics behind it. A skill loads in stages. At startup, Claude reads only each skill’s name and description, roughly 100 tokens. The body loads when the description matches your request. Reference files load later still, and only if needed. Fifty installed skills idle at a few thousand tokens total. Fifty always-on rules would be a context catastrophe, which is why Cursor caps and warns about rule length. Progressive disclosure means a skill can be huge without being expensive, and that changes what you can afford to write down.

Bundled files. A skill is a folder, not a file. Anthropic’s docx skill ships Python scripts that build Word documents. The skill-creator skill ships templates and an eval harness. A code review skill can carry a severity rubric as a separate reference file that loads only during reviews. Rules are text describing what the model should do. Skills can include the tooling to do it, and the model runs the script instead of improvising the output.

Portability. A skill you write for Claude Code also works in Claude Desktop, on claude.ai, and in anything built on the Agent SDK. Your git conventions follow you from terminal to chat to a custom agent. A Cursor rule works in Cursor. If you ever switch editors, or use Claude for non-editor work like writing or data analysis, the skill format is the one that survives the move. This is the strongest argument for skills as a cursor rules alternative: you write the instructions once and they aren’t married to one product.

Skills can act, not only advise. Because Claude Code executes commands, a skill can say “run this script and paste the output” rather than “here is how one might format the output.” The gap between describing behavior and shipping behavior is the same gap between a style guide and a linter.

What rules do that skills can’t

Two things, and they’re not small.

IDE-native context. Rules participate in everything Cursor does: completions as you type, Cmd+K inline edits, the agent panel. Skills operate wherever Claude operates, which today means the CLI, desktop app, and web, not inside another company’s editor. If your entire AI usage happens in Cursor’s Tab key, skills don’t reach you there.

Per-glob application. There is no skill equivalent of “attach these instructions whenever a .proto file is in context.” The model decides from descriptions, and while it’s good at this, it isn’t a guarantee. For instructions that must correlate with file type rather than task type, glob-scoped rules are the better mechanism, full stop.

The migration path, both directions

Converting a .cursorrules file to a skill

Take a typical rules file:

You are an expert React and TypeScript developer.

- Functional components with hooks only, no classes
- Named exports, never default exports
- Tailwind for styling, no inline style objects
- All API calls go through src/lib/api.ts
- Tests in Vitest, colocated as *.test.tsx

The conversion is mostly adding a trigger and structure:

---
name: react-conventions
description: React/TypeScript conventions for this repo. Use when
  writing or reviewing components, hooks, styles, API calls, or
  frontend tests.
---

## Components
- Functional components with hooks. No class components.
- Named exports only. No default exports.

## Styling
- Tailwind utility classes. Never inline style objects.

## Data access
- Every API call goes through `src/lib/api.ts`. Do not call
  fetch directly from a component.

## Tests
- Vitest, colocated next to the component as `*.test.tsx`.

Drop it in .claude/skills/react-conventions/SKILL.md and it triggers on frontend work in that repo. Three things changed and each matters. The persona line (“You are an expert…”) is gone because it does nothing; the model doesn’t get better at React by being told it’s an expert. The description now lists concrete activities, because that field is the trigger and vague descriptions are the number one reason skills sit inert. And the bullets gained headings, since a skill body should be skimmable by the model at load time. Our guide to writing skills covers the description-writing part in depth; it’s the step people botch.

While you’re at it, ask whether any bullet should become a file. If your rules file describes an API response format, put an actual example response in reference.json next to the SKILL.md and point to it. That option simply doesn’t exist in the rules format.

Going the other way

Converting a skill to a Cursor rule means flattening it. Take the body of your SKILL.md, drop the frontmatter, and save it as .cursor/rules/react-conventions.mdc with new frontmatter:

---
description: React/TypeScript conventions for this repo
globs: src/**/*.tsx,src/**/*.ts
alwaysApply: false
---

- Functional components with hooks. No class components.
- Named exports only. No default exports.
...

You lose the bundled files, so anything that was a script becomes a description of what the script did. You lose progressive disclosure, so trim hard: a 3,000-token skill body should become a 500-token rule, keeping only what Cursor’s models actually need per-request. Keep the glob tight so the rule doesn’t tax unrelated work.

Running both without duplicating yourself

Plenty of developers use Cursor for editing and Claude Code for agent work in the same repo. The trap is maintaining two copies of the same conventions that drift apart within a month.

The fix that has worked for us: pick one canonical home per instruction, based on its shape.

Shared project facts go in AGENTS.md. Both tools read it. Architecture notes, build commands, directory layout, the “never touch these files” list. One file, zero duplication, and it also serves human newcomers.

Glob-shaped instructions stay in .cursor/rules. File-type conventions that should mechanically attach in the editor.

Task-shaped and cross-tool instructions become skills. Debugging methodology, review checklists, release procedures, anything with a script or template, anything you also want available in Claude Desktop or chat.

If an instruction genuinely needs to exist in both formats, make the rule a pointer, not a copy: a two-line .mdc saying “conventions for X live in .claude/skills/x/SKILL.md; follow them” keeps one source of truth. Some teams script the conversion in CI instead, regenerating .mdc files from SKILL.md bodies on commit. That’s more machinery than most projects need, but it beats silent drift on a large team.

One thing we’d steer you away from: pasting the same 2,000-word document into both systems verbatim. In Cursor it bloats every request. In Claude it’s usually a sign the content should be split into a small always-relevant core and a set of conditional skills. This is the same reasoning as skills vs MCP: match the mechanism to the shape of the problem instead of forcing one tool to do everything.

Nobody tests rules either

Here’s the part of this comparison nobody else will give you, because it’s our whole reason for existing.

When we started testing community Claude skills, roughly half failed on first try: broken triggers, instructions the model can’t follow, output no better than baseline. We documented the failure taxonomy in why half of Claude skills don’t work. The uncomfortable follow-up question is whether the thousands of shared .cursorrules files on GitHub are any better.

They aren’t, and structurally they can’t be. The same incentives apply: rules are published from a single author’s workflow, never verified on a clean setup, never measured against a no-rule baseline, and starred based on README quality rather than results. When we’ve pulled popular rule files apart, we find the same defects we score skills down for. Persona padding that consumes context and changes nothing. Instructions written for a model version two generations old. Contradictory bullets (“be concise” forty lines after “always explain your reasoning in detail”). Rules so long they crowd out the code they’re meant to improve.

Rules dodge one failure mode, since an always-on rule can’t fail to trigger. Every other failure mode transfers directly. A convention document that makes output worse is equally harmful in either format; the format just changes how it’s delivered.

So whichever side of this comparison you land on, the operational advice is identical: don’t install shared instruction files on faith. Diff the output with and against the instructions on a real task from your own project. Ten minutes of comparison beats any star count. For skills, we’ve done that work already across our tested coding collection, where entries like systematic-debugging carry before/after evidence rather than promises. For Cursor rules, as far as we know, nobody is doing it at all. Draw your own conclusion about what half of them are worth.

FAQ

Can Claude Code read my .cursorrules file directly? Not automatically. Claude Code reads CLAUDE.md, AGENTS.md, and its skills directories, and ignores .cursorrules and .cursor/rules. You can tell it to read the file in a session, but for anything permanent, convert the contents into a skill or move the shared parts to AGENTS.md.

Do Cursor rules cost tokens the way skills do? More, in most setups. An always-on rule rides every single request at full length. A skill idles at about 100 tokens of metadata and pays for its body only when triggered. Glob-scoped rules narrow the gap, since they attach only during matching work, but there’s no rules equivalent of loading reference material on demand.

Should I convert all my Cursor rules to skills? No. Keep glob-scoped, file-type conventions as rules if you work in Cursor; that mechanism is genuinely better for them. Convert the task-shaped material: workflows, checklists, anything with templates or scripts, anything you want outside the editor.

Is there a shared standard both tools read? AGENTS.md is the closest thing. Cursor and Claude Code both read it, along with a growing list of other agents. It’s plain always-on instructions with no conditional loading, so treat it as the home for a small core of project facts rather than a dumping ground.

Are Claude skills or Cursor rules better for a team? Skills check into git under .claude/skills/ and version like code, and rules check in under .cursor/rules/ the same way, so both distribute fine. The team question is really about surface: if everyone lives in Cursor, rules reach them with zero setup. If the team also uses Claude Code, Desktop, or agents built on the SDK, skills are the only format that covers every surface, and the sync pattern above keeps the two from drifting.