← All posts
Cursor By Editorial · Skillaisle ([email protected]) · Published Nov 3, 2026 · 5 min read · Facts checked against official docs on Nov 2, 2026

Cursor Rules vs Agent Skills: Migrating Your .cursorrules the Right Way

Rules stay always-on. Skills load on demand. Migrate legacy .cursorrules into Always Apply rules first, then move multi-step workflows into skills — and use /migrate-to-skills only for what it actually converts.

If you still have a .cursorrules file in the repo root, you are not behind — you are sitting on a format Cursor itself now calls legacy. The mistake is dumping that whole file into a skill, or leaving it where it is and hoping the agent “just knows.” Rules and skills solve different problems. Mixing them up is how you end up with a skill that never fires, or a rule that burns context on every chat.

This is a migration guide for people who already use Cursor. It starts from what each thing is for, then walks through moving off .cursorrules, deciding what becomes a skill, and using the built-in /migrate-to-skills helper without turning always-on guidance into something the agent only sees sometimes.

Rules vs skills, in one table

Cursor’s own docs put it cleanly: rules are short, persistent instructions; skills are longer, on-demand workflows.

Rules Skills
Purpose Coding guidelines and constraints the agent should keep in mind Multi-step procedures the agent follows when the task matches
Typical length A few lines to a few hundred Often longer, with steps, scripts, references
When it loads Always, intelligently, by file pattern, or when you @mention it On demand via /skill-name, or when the agent decides it matches
Where it lives .cursor/rules/ (project), account user rules, team rules .cursor/skills/ or .agents/skills/ (and personal folders under ~)
Context cost Paid on every matching conversation Full body loads only when invoked

If the instruction is “always use TypeScript” or “never edit migrations/ by hand,” that is a rule. If it is “deploy to staging: build, test, ship, hit the health URL,” that is a skill. Cursor’s customizing agents guide uses the same split: rules as static context, skills as dynamic context.

For how skills compare to MCP servers and custom instructions across tools, see Skills vs MCP vs Custom Instructions.

Step 1: get off .cursorrules

Cursor’s Rules help says the root .cursorrules file is legacy and will be deprecated. The migration it documents is boring on purpose:

  1. Open the command palette and run New Cursor Rule.
  2. Paste the old .cursorrules body into the new rule.
  3. Set the type to Always Apply — that matches how the old file behaved.
  4. Delete .cursorrules from the project root.

Do not turn the whole dump into a skill in this step. Always-on project conventions belong in a rule so they stay in context without you typing / every time. You can split the file later; first get the same behavior under .cursor/rules/.

If the old file was enormous, split it after the move: one rule for language/style, one for repo commands, one for “do not touch” paths. Cursor’s guidance is to keep rules under roughly 500 lines and to point at example files instead of pasting whole style guides.

Step 2: sort what should stay a rule

Keep as rules:

  • Build, test and lint commands the agent needs on every change
  • Naming and import conventions
  • Guardrails (folders not to edit, patterns to avoid)
  • Pointers to a canonical file (@components/Button.tsx) rather than copying that file into the rule

Drop or shorten:

  • Entire style guides your linter already enforces
  • Generic “write clean code” filler
  • Long procedures that only matter on deploy day or once a quarter

Always Apply and Apply to Specific Files (globs) are the right shapes for conventions that must fire without waiting for the agent to notice. Apply Intelligently needs a clear description so the agent can decide; Apply Manually is for rules you @mention when you want them.

Step 3: move multi-step workflows into skills

A skill is a folder with a SKILL.md (name and description in frontmatter, body below). Cursor discovers project skills from .cursor/skills/ and .agents/skills/, and personal skills from the matching folders under your home directory. Details, including Cloud Agent sync, are in the Agent Skills docs. The open Agent Skills specification is the shared shape across tools.

Good candidates to peel out of an old rules dump:

  • Deploy / release checklists
  • Incident or rollback playbooks
  • “Add a new API route” or “cut a changelog” procedures
  • Anything with scripts under scripts/ that the agent should run in order

Cursor’s Skills help also documents /create-skill and converting a named rule into a skill when the content has become a procedure rather than a convention. For writing the file itself, use How to Write Your First SKILL.md. If a skill installs but never fires, walk through Why Your AI Agent Ignores Your Skill.

Step 4: use /migrate-to-skills for what it actually converts

Cursor 2.4+ ships a built-in /migrate-to-skills skill. Type that in Agent chat and it converts eligible rules and slash commands into skills under .cursor/skills/.

What it converts, per the docs:

  • Dynamic rules — Apply Intelligently style: alwaysApply: false (or unset) and no globs
  • Slash commands — user- and workspace-level commands, turned into skills with disable-model-invocation: true so they stay explicitly invoked

What it does not convert:

  • Rules with alwaysApply: true
  • Rules scoped with globs / specific files
  • Account-level user rules (they are not on the filesystem the migrator reads)

So: always-on and file-scoped rules stay rules. Only the “agent picks when relevant” rules, and old slash commands, become skills. Review the generated folders before you delete anything. Commands that should stay manual keep disable-model-invocation: true; that matches the old slash-command habit of only loading when you type /name.

A practical split for a typical repo

After migration, a sane layout looks like this:

.cursor/
  rules/
    typescript-conventions.mdc    # Always Apply
    api-route-patterns.mdc        # Apply to app/api/**/*
  skills/
    deploy-staging/
      SKILL.md
      scripts/deploy.sh
    cut-release-notes/
      SKILL.md

Plus, if you still need a personal preference that is not project-specific, keep it in Cursor Settings → user rules, not in the repo.

Checklist before you call it done

  • .cursorrules is gone; an Always Apply rule (or a small set of them) replaced it
  • Long procedures live under .cursor/skills/ or .agents/skills/ with a real description
  • You ran /migrate-to-skills only as a helper, then reviewed what it skipped
  • Always Apply and glob-scoped rules were not forced into skills
  • Team members can see project rules and skills in git; personal ~/.cursor/skills/ are synced for Cloud Agents only if you turned that on

Install paths across Claude Code, Cursor and Codex are covered in the install guide if you share skills beyond Cursor.

Bottom line

Migrate .cursorrules into Always Apply rules first so behavior does not change. Then move multi-step workflows into skills so they stop taxing every conversation. Use /migrate-to-skills for dynamic rules and slash commands — not for the always-on file you just carefully preserved. Rules say how the agent should behave in this repo. Skills say how to run a specific job when that job comes up. Keep those jobs separate and the migration stays boring, which is the point.

Sources

Products change quickly. If something here no longer matches what you see, the official page above is the reference.

Related on Skillaisle

Want the setup steps? Browse the Learn guides or walk the skills aisle.