Cursor rules: .mdc project rules, examples and the old .cursorrules file

What are Cursor rules?

Cursor rules are instructions that Cursor adds to the start of the model's context so its agent follows your project's conventions. Instead of repeating "use named exports" or "validate inputs with zod" in every chat, you write it once in a rule.

Today the main form is project rules: .mdc files in a .cursor/rules/ folder in your repo, each with a small frontmatter block that decides when the rule applies. If you have an old .cursorrules file in the project root, that is the earlier single-file format. Cursor's rules documentation no longer covers it, so the rest of this guide uses the current format and shows how to move over.

What kinds of Cursor rules are there?

Cursor's docs list four kinds: project rules, user rules, team rules and AGENTS.md.

When guidance conflicts, Cursor applies team rules first, then project rules, then user rules. User rules apply to Agent chat only, not to inline edits, and no rules affect Tab autocomplete.

The .mdc format

Each project rule is a Markdown file with the .mdc extension. The extension matters: Cursor's docs say a plain .md file in .cursor/rules/ "is ignored by the rules system because it has no frontmatter." You can name the files anything and group them in folders:

.cursor/rules/
  react-patterns.mdc       recognized
  api-guidelines.md        ignored, wrong extension
  frontend/
    components.mdc

The frontmatter has three fields: description, globs and alwaysApply. How you combine them sets the rule type.

You can also pick the type from a dropdown in the rule editor, which sets these fields for you.

Examples you can copy

An always-on rule for things that should hold everywhere:

---
alwaysApply: true
---

- Never edit generated files in dist/ or build/.
- Read the relevant source files before proposing changes.
- Run npm test before saying a task is done.

A rule that attaches only to React components. Separate several patterns with commas:

---
globs: src/components/**/*.tsx
alwaysApply: false
---

- Use named exports, not default exports.
- Keep components under 200 lines. Move subcomponents into the same folder.
- Style with Tailwind classes. Do not add new CSS files.

A rule the agent pulls in when the task matches its description:

---
description: Conventions for writing and changing database migrations
alwaysApply: false
---

- Every migration needs both up and down steps.
- Never change a column type in place. Add a column, backfill, then drop the old one.
- Follow the structure in @migration-template.sql.

The @migration-template.sql mention tells the agent where to look. Cursor's docs note that the file is not pasted into the prompt; the agent reads it with its tools when it needs it. If something must always be in context, put it in the rule body.

How do you create a Cursor rule?

1. In Agent chat, type /create-rule and describe what you want. The agent writes the file with frontmatter and saves it to .cursor/rules/.
2. Or open Customize in the sidebar, go to Rules and click Add Rule.
3. Commit the file so your team gets it.

How to write good rules

Cursor's own advice is short and worth following:

• Keep each rule under 500 lines, and split big ones into smaller rules that each cover one topic.
• Be concrete. "Return errors as { code, message }, never throw strings" beats "handle errors well."
• Point to files instead of copying them. A reference to a template stays current; a pasted copy goes stale.
• Skip what the model already knows. No need to explain npm or git, and don't paste a whole style guide when a linter can enforce it.
• Start small. Add a rule when you see the agent make the same mistake twice, not before.

One more habit helps: write the description of an Apply Intelligently rule the way you would describe the task out loud. The agent compares that line to your request, so "Conventions for database migrations" is picked up when you ask for a migration.

Moving off .cursorrules

If your repo still has a .cursorrules file:

1. Create .cursor/rules/ in the project root.
2. Split the old file by topic. Put rules that apply everywhere in one file with alwaysApply: true.
3. Move rules that only matter for some files into their own .mdc files with globs.
4. Move plain project facts, like build commands and folder layout, into AGENTS.md so other agents can read them too.
5. Delete .cursorrules once the new rules work, so there is one source of truth.

Reusing the same instructions in Claude Code and Codex

Cursor rules are Cursor-specific. Claude Code and Codex don't read .mdc files. Two shared formats get you most of the way:

AGENTS.md for project facts. Cursor reads AGENTS.md at the root and in subfolders. Codex reads it too, and Claude Code reads it when there is no CLAUDE.md. See the AGENTS.md guide for a template.

Agent Skills for workflows. Cursor supports Agent Skills: folders with a SKILL.md file. It loads them from .cursor/skills/ and .agents/skills/, and "for compatibility" from .claude/skills/ and .codex/skills/. Cursor even ships a built-in /migrate-to-skills skill that converts Apply Intelligently rules into skills. Rules with alwaysApply: true or globs are not migrated.

The migration rule from earlier, as a skill:

---
name: db-migrations
description: Write or change database migrations. Use when the user asks
  for a migration, a schema change or a new column.
---

# Database migrations

1. Every migration needs both up and down steps.
2. Never change a column type in place. Add a column, backfill, then drop
   the old one in a separate migration.
3. Follow the structure in migration-template.sql in this folder.

Save it as .claude/skills/db-migrations/SKILL.md and it works in Claude Code, and Cursor loads it from the same folder. The name must match the folder name. The SKILL.md guide covers the rest of the format, and the Agent Skills guide explains which tools support it.

A simple way to split things up:

• Always-on, Cursor-only behavior, like file-pattern rules: .cursor/rules/*.mdc
• Project facts every agent should know: AGENTS.md
• Repeatable tasks like reviews, migrations or release notes: skills

Keep your rules and skills in one place

Rules and skills spread across repos are easy to lose. Kipt keeps your prompts and skills in your own private GitHub repo. Paste a rule or prompt to save it, press ⌘K to find it, and use Promote to skill to turn it into a SKILL.md. Each skill then installs into Claude Code or Codex with npx skills add. To convert a single rule right now, paste it into the free SKILL.md generator.