A Cursor rule is always-on context that shapes how the model behaves across everything you do in Cursor. A Claude Code skill is an invokable specification for a specific task. Cursor rules are guidelines. Claude Code skills are procedures. The architectural difference matters the moment you need something more than "always write TypeScript" guidance.

Agent Engineer Master (AEM) builds production Claude Code skills for development teams. The most common question from teams migrating from Cursor is whether their existing rules translate directly. The answer: some do, most need restructuring, and a significant portion belong in a different layer entirely.

TL;DR: A Cursor rule is a persistent instruction that applies across your entire editor session. A Claude Code skill is a SKILL.md file with process steps, an output contract, and a named trigger condition. Cursor rules are context. Skills are procedures.

What is a Cursor rule?

A Cursor rule is a text file that loads into the model's context to shape its behavior within Cursor. The original format is .cursorrules at your project root: a single file of instructions that applies globally to all your interactions in that project.

Cursor's newer format, .cursor/rules/*.mdc files, allows multiple rule files. These can be configured as "always applied," "applied to specific file patterns" (for example, only when editing *.test.ts files), or "manual" (only loaded when you reference them explicitly). Cursor rules are prose. They state preferences, constraints, and conventions in natural language.

Most Cursor rule files are a list of "always do this" instructions: use functional components, prefer named exports, follow this error handling pattern. That is their strength and their limit. Cursor rules tell the model what standards to apply. They do not define what tasks to perform or how to perform them in sequence.

What is a Claude Code skill?

A Claude Code skill is a SKILL.md file with three structured components: YAML frontmatter, numbered process steps, and an output contract. The frontmatter defines the skill's name and description. The description field, which controls automatic invocation, has a 1,024-character limit and must stay on a single line (source: Claude Code documentation, 2026).

The process steps are where skills differ fundamentally from any rule file. Steps are numbered instructions Claude follows in sequence, potentially including tool calls, reference file loads, conditional branches, and calls to load external data. The output contract defines what the skill produces and what it does not produce.

A Claude Code skill is not just context. It is a specification for a complete procedure.

"The single biggest predictor of whether an agent works reliably is whether the instructions are written as a closed spec, not an open suggestion." - Boris Cherny, TypeScript compiler team, Anthropic (2024)

For the full anatomy of a SKILL.md file, see What Is a Claude Code Skill?.

How does the activation model differ?

Cursor rules are active all the time, or scoped to file types, or referenced manually. The model reads them as part of the baseline context for every request. You do not invoke them. They are always there, shaping behavior passively.

Claude Code skills activate in two ways:

  1. Explicit invocation: You type /skill-name and Claude loads the full SKILL.md into context and executes the process steps.
  2. Automatic detection: Claude reads the skill's description during context loading. If the description matches your current intent, the skill activates without a slash command.

This is a fundamentally different architecture. Cursor rules push context into every interaction. Claude Code skills pull procedures into specific interactions when the conditions are met.

The practical difference: a Cursor rule that says "always check for missing test coverage before submitting code" relies on the model remembering and applying that instruction in the right moment. A Claude Code skill named review-pr with "check for missing test coverage" as step 2 in a numbered process guarantees that step runs in the right position every time you invoke the skill.

Research explains why this matters. Models lose more than 30% accuracy on retrieval tasks when the relevant instruction sits in the middle of a long context rather than at the beginning or end (source: Liu et al., Stanford NLP / UC Berkeley, "Lost in the Middle," ArXiv 2307.03172, 2023). A Cursor rule buried mid-context is exactly this failure mode in production.

What can a Claude Code skill do that a Cursor rule cannot?

A Claude Code skill can load reference files on demand, enforce an explicit output contract, run as a guaranteed numbered sequence, and work across 14+ AI coding tools. A Cursor rule can do none of these: it is always-on context, not an executable procedure. The four differences below define the capability gap.

  1. Load reference files on demand. A skill's process steps can instruct Claude to read a specific file at a specific point in the workflow. A Cursor rule has no equivalent mechanism. At startup, Claude loads only the skill's name and description, consuming roughly 30-50 tokens; the full SKILL.md body (typically 4-5k tokens) loads only when the skill is invoked (source: Claude Code documentation, 2026).

  2. Enforce an output contract. A skill defines exactly what it produces and what it does not produce. Cursor rules can state output preferences, but without an explicit contract, the model interprets those preferences differently across sessions. When given an explicit output format with examples, output consistency rises from roughly 60% to over 95% (source: Addy Osmani, Engineering Director, Google Chrome, 2024).

  3. Run as a structured sequence. Numbered steps in a SKILL.md create a sequence Claude follows. A Cursor rule's instructions can be applied in any order the model chooses. In our builds at AEM, the skills with the fewest revision cycles are the ones where the sequence is explicit, not suggested.

  4. Work across platforms. A SKILL.md file is compatible with 14+ AI coding tools including Claude Code, Cursor (with translation), Gemini CLI, and Windsurf (source: universal SKILL.md format documentation, 2026). A .cursorrules file only works in Cursor.

A Cursor rule is a well-placed sticky note. A Claude Code skill is the actual documentation. Both have their place; they solve different problems.

See What's the Difference Between a Claude Code Skill and a Prompt? for how skills compare to unstructured instructions more broadly.

What belongs in a Cursor rule vs a Claude Code skill?

Put always-on standards in a Cursor rule or CLAUDE.md: coding conventions, editor preferences, and project constraints that apply to every file. Put any multi-step workflow, task with a defined output contract, or operation that loads external context in a Claude Code skill. The deciding factor is whether the instruction is a persistent guideline or an invocable procedure.

Put this in a Cursor rule (or in CLAUDE.md for Claude Code):

  • Always-on coding standards: "use named exports," "prefer functional components"
  • Project conventions that apply to every file: "this codebase uses Zod for validation"
  • Editor behavior preferences: "always suggest tests for new functions"

Put this in a Claude Code skill:

  • Any workflow with more than one step: "review this PR, then check test coverage, then output a structured report"
  • Tasks with specific output requirements: "produce a JSON object with these exact fields"
  • Operations that depend on loading external context: "read the API spec, then validate this implementation against it"
  • Workflows you will invoke repeatedly and need to produce consistent results

The clearest signal that something belongs in a skill and not a rule: if you have corrected the model's output for the same task more than three times, the instructions need to be in a procedure, not a suggestion (source: AEM commission pattern analysis, 2026).

This does not mean Cursor rules are inferior. For always-on project context, a rule file is exactly the right tool. Standards that apply universally do not need to be invoked. Procedures that run on specific tasks do.

See When Should I Use a Skill Instead of Writing Instructions in CLAUDE.md? for the equivalent decision in Claude Code's native architecture.

Can you convert Cursor rules into Claude Code skills?

Yes, with restructuring. A typical .cursorrules file of 30 to 60 lines takes 30 to 60 minutes to migrate correctly. Always-on standards move directly to CLAUDE.md. Task-specific instructions require conversion from prose into numbered steps. The migration is not a direct copy-paste: the format and the execution model differ. The common patterns:

  • Always-on standards from .cursorrules map directly to CLAUDE.md in Claude Code. They remain always-on context, just in Claude Code's format.
  • Task-specific instructions in Cursor rules (things that describe how to handle a specific type of request) become SKILL.md files with a trigger condition in the description field.
  • Prose instruction blocks need to be restructured into numbered steps. "When reviewing code, check for X, then Y, then Z" becomes three sequential steps in a process section, not three sentences in a paragraph.

The restructuring takes longer than a direct copy-paste, but it produces more reliable output. Prose instructions leave interpretation up to the model. Numbered steps leave interpretation out entirely. Claude Code reached 18% workplace adoption among professional developers by January 2026, up from 3% in mid-2025, which means more teams are making exactly this migration now (source: JetBrains Developer Survey, April 2026).

See Can I Use Skills and Agents Together? for how skills fit into larger Claude Code workflows.

Frequently Asked Questions

Can I use my .cursorrules file in Claude Code? Not directly. Claude Code reads CLAUDE.md, not .cursorrules. You can migrate your always-on Cursor instructions to CLAUDE.md manually. Task-specific instructions in your Cursor rules should become SKILL.md files rather than landing in CLAUDE.md.

Which is better for a solo developer: Cursor rules or Claude Code skills? Neither is universally better. Cursor rules are sufficient for simple always-on standards and editor preferences. Claude Code skills become valuable the moment you have a workflow you run more than three times a week and need consistent output. The two tools are not in competition -- they solve different problems.

Do Claude Code skills work inside Cursor? Cursor has some support for SKILL.md-format files, but the invocation mechanism differs from Claude Code's native runtime. For full skill support including automatic description-based triggering and tool integration, Claude Code is the native environment.

Can I have both a Cursor rule and a Claude Code skill for the same task? Yes, if you are using both tools. There is no conflict. A developer using Cursor for editing and Claude Code for automation tasks could reasonably have Cursor rules for editor behavior and Claude Code skills for workflow procedures.

How long does it take to convert a Cursor rule file to Claude Code skills? A typical .cursorrules file of 30 to 60 lines takes 30 to 60 minutes to migrate (source: AEM commission pattern analysis, 2026). The always-on standards move to CLAUDE.md quickly. The task-specific instructions take longer because they require restructuring from prose into numbered steps.

Last updated: 2026-05-05