Converting a .cursorrules file into a Claude Code skill is a four-step process: add YAML frontmatter, write a description directive, restructure the content into labeled sections, and move the file to .claude/skills/. AEM puts this conversion at 15-30 minutes for a well-written source file. It usually reveals that the original rule was doing two or three things that should be separate skills.

TL;DR: The structural conversion is mechanical: frontmatter, section restructuring, file move. The hard part is the description field, which must be a directive specifying trigger, output, and exclusion, not a label. Most Cursor rules files conflate all three. The conversion forces that separation.

What makes Cursor rules structurally different from Claude Code skills?

Cursor rules are flat markdown prose with no required structure, while Claude Code skills are structured files built from four distinct layers: a trigger layer (frontmatter and description), an execution layer (process steps), a constraint layer (rules section), and an output specification (output contract), each serving a different routing and execution function. Cursor reached over 1 million daily active users by 2025 (Cursor, 2025), which means a large and growing pool of existing rule files that need this conversion.

A typical Cursor rule looks like this:

When reviewing code, look for security issues including SQL injection, XSS, and hardcoded credentials. Always explain why each issue is a problem and suggest a fix. Focus on the most critical issues first. Don't reformat the code unless asked.

This packs all four layers into one paragraph. The trigger condition (when reviewing code), the instructions (look for these issues, explain, suggest), the constraints (don't reformat), and an implicit output structure are all blended together.

Claude Code needs these separated. A flat paragraph works fine when a developer is reading it and applying judgment. A model following a skill needs explicit structure to route the skill correctly, execute steps in the right order, and produce consistent output.

Most Cursor rules files read as notes to a future developer. SKILL.md reads as an executable specification. That distinction matters: 84% of developers now use or plan to use AI coding tools (Stack Overflow Developer Survey, 2025), and the flat-prose rule format stops scaling when the model is the executor rather than the reader.

How do I convert a .cursorrules file step by step?

The conversion follows four steps: add YAML frontmatter with a name and description, extract and restructure the content into labeled sections (process steps, rules, output contract), write the description directive as a trigger specification, and move the file to .claude/skills/. Total time: 15-30 minutes for a focused rule.

  1. Add YAML frontmatter. Open your .cursorrules file. At the top, add:

    ---
name: your-skill-name
description: "Use this skill when [trigger condition]. Produces [specific output]. Do NOT use for [exclusion]."
---

    Leave the existing content below the second --- delimiter. The original rule text is now the skill body.

  2. Extract and restructure the content into labeled sections. Read through the original rule text and separate it into:

    ## Process steps

1. [First thing the skill does]
2. [Second thing]
3. [Third thing]

## Rules

- Always [constraint]
- Never [constraint]

## This skill produces

- [Specific output item 1]
- [Specific output item 2]

## This skill does NOT produce

- [What to exclude]

    This separation is the highest-value step in the conversion. It forces clarity about what the skill is actually doing. If you can't separate the original rule into these sections cleanly, it's doing more than one thing and should be split into multiple skills.

  3. Write the description directive. The description is the most important element you're adding. It's not a title or summary. It's a trigger specification.

    Structure the description in three parts:

    1. Trigger: "Use this skill when the user asks to [specific task]"
    2. Output: "Produces [specific output format or content]"
    3. Exclusion: "Do NOT use for [task that sounds similar but should use a different skill]"

    The description must stay under 1,024 characters and must be a single line in the frontmatter, with no line breaks inside the value string. Keep it under 150 characters.

    A description like "Security code reviewer" is a label. A description like "Use this skill when the user asks to review code for security vulnerabilities. Produces a structured list of risks with severity, location, and fix. Do NOT use for general code review or style feedback." is a directive.

    Imperative descriptions achieve 100% activation rate in Claude Code. Passive descriptions ("This skill handles security reviews") sit at 77% activation rate (AEM internal testing, 650 trials). Write the directive version.

  4. Move the file to .claude/skills/. Place the file at:

    • .claude/skills/your-skill-name.md for project-level skills
    • ~/.claude/skills/your-skill-name.md for user-level skills available across all projects

    The file is now a Claude Code skill.

How do I write a good description field for a converted skill?

The description field is the only part of the conversion that requires original thinking: it must specify what triggers the skill, what the skill produces, and what it explicitly does not handle, all in a single directive under 150 characters, none of which the original Cursor rule ever had to define. The other three steps, adding frontmatter, restructuring sections, and moving the file, are mechanical: they transfer and reorganize existing content.

A good description answers three questions:

When should this skill fire? Be specific about the trigger. "When reviewing code" is too broad. "When the user explicitly asks for a security review of a function, file, or codebase" is the right specificity. The more specific the trigger, the less likely the skill is to fire when it shouldn't.

What does it produce? Name the output format. "Produces a structured list of security risks, each with severity level (critical/high/medium/low), file and line location, and a specific remediation step." This is what Claude Code matches against when routing the request.

What does it NOT do? One explicit exclusion prevents false positives. "Do NOT use for general code style feedback or formatting requests" keeps the security review skill from triggering on every code-related question.

"The failure mode isn't that the model is bad at the task — it's that the task wasn't specified tightly enough. Almost every production failure traces back to an ambiguous instruction." — Simon Willison, creator of Datasette and llm CLI (2024)

The description is the skill's commitment. A vague description makes a fair-weather skill: one that works when the task is obvious and misfires when it's not. Claude Code processed 195 million lines of code per week as of July 2025, across 115,000 developers (Anthropic, July 2025). At that scale, a poorly specified description doesn't just fail occasionally; it fails systematically, on every request that hits the wrong trigger.

For a deeper look at description optimization, see The SKILL.md Description Field: The One Line That Makes or Breaks Your Skill.

What are the most common mistakes when converting Cursor rules?

Five mistakes account for the majority of failed conversions: writing a label instead of a trigger directive in the description, leaving process steps and constraints in a single mixed list, converting rules that assume persistent context without making that context explicit, treating a single rule as a single skill when it contains multiple concerns, and omitting the output contract entirely.

  1. Writing a label instead of a directive. "Code quality rules" is a label. "Use this skill when the user asks for a code review focusing on quality, not style" is a directive. Every description needs a trigger condition, an output, and an exclusion.

  2. Not separating process steps from rules. Process steps are sequential actions. Rules are invariant constraints. Mixing them in one list creates a skill where Claude follows some items as steps (in order, once) and others as constraints (always, regardless of order). Separate them explicitly.

  3. Converting rules that assume persistent context. Many Cursor rules rely on context that's always present in a Cursor session but isn't always present in a Claude Code context window. "Use the project's existing naming conventions" works in Cursor because the conventions are in the codebase visible to the model. In Claude Code, add an explicit step: "Read references/naming-conventions.md at step 1."

  4. Keeping the conversion scope at 1:1. One Cursor rule often contains multiple skills. A "code review" rule usually has logic for style, logic for security, and logic for architecture, three different skills with different trigger conditions and outputs. Converting 1 rule into 1 skill preserves the problem. Converting 1 rule into 3 focused skills fixes it.

  5. Skipping the output contract. Cursor rules focus on what to do, not what to produce. Adding an explicit output contract ("This skill produces X, not Y") is not optional for Claude Code. Without it, the skill produces different output lengths and formats across invocations. The output contract is the consistency mechanism.

In our experience converting 40+ client rule sets, the conversion reveals an average of 2.3 distinct skills per original Cursor rule. The original rule was doing multiple things blended together because Cursor doesn't require separation. Well-configured Cursor rules can reduce code review iterations by 41% (Opsera, 2025), but that gain disappears when the same unstructured rules are ported to an agent runtime that can't interpret flat prose as reliably as a developer can.

When should I convert a Cursor rules file vs. rewrite from scratch?

Convert when the original rule has good instruction quality: clear steps, specific constraints, and a single coherent purpose, because the conversion adds the structural layers Claude Code needs, covering trigger, execution, constraints, and output contract, without discarding the knowledge embedded in the original rule. If the rule is vague or covers multiple unrelated concerns, rewrite instead.

Rewrite when:

  • The rule mixes 3+ unrelated concerns (convert → rewrite as 3+ separate skills)
  • The rule relies heavily on persistent context that would need to become explicit load instructions
  • The rule's instructions are vague or aspirational ("write good code") rather than specific

A quick test: if you can read the original rule and describe in one sentence what it does and produces, convert it. If you need two sentences for the "what" or you can't name the output format, rewrite it.

The rewrite path produces better skills. The conversion path is faster. Pick based on how much the original rule is worth preserving. In JetBrains' January 2026 AI Pulse survey, 18% of developers used Cursor at work; most of them have existing rule files. That's a large installed base of conversion candidates, most of which are worth converting rather than rewriting from scratch.

For a full view of how SKILL.md compares to Cursor rules and Copilot instructions across every platform, see Skills vs Cursor Rules vs Copilot Instructions: A Cross-Platform Comparison.

FAQ

How long does it take to convert a .cursorrules file into a SKILL.md?

15-30 minutes for a well-written source file with a single clear purpose. 45-90 minutes for a rule that mixes multiple concerns and needs to be split. The description field is usually where the time goes: writing a clear trigger + output + exclusion for a rule that never had to define these things explicitly.

Can I keep using my Cursor rules in Cursor after converting them to Claude Code skills?

Yes. The conversion copies or restructures the file; it doesn't delete the original. Keep the .cursorrules or .mdc file in .cursor/rules/ for Cursor and the converted SKILL.md in .claude/skills/ for Claude Code. Maintain both, or accept that one drifts when you update the other.

What happens to the frontmatter if I install a converted SKILL.md back in Cursor?

Cursor ignores it. The YAML block reads as plain text or is skipped. The instruction body below the second --- delimiter works in Cursor exactly as it did before the conversion. The frontmatter adds Claude Code functionality without breaking Cursor compatibility.

Do I need to add reference files when converting Cursor rules?

Only if the rule relies on domain knowledge that isn't in the instruction body. If the rule says "follow the project's coding standards," you need to either make the standards explicit in the skill or create a reference file (references/coding-standards.md) and add a load instruction in step 1. Cursor can see the codebase implicitly. Claude Code needs explicit instructions to access specific files.

Is there a tool that automates the conversion from .cursorrules to SKILL.md?

Not currently. The structural conversion (adding frontmatter, reorganizing sections) could be automated. The description directive cannot: it requires understanding what the rule is doing, what it should trigger on, and what it explicitly should not trigger on. That judgment call doesn't automate cleanly.

Last updated: 2026-04-17