Cursor rules

Cursor rules are instructions that Cursor puts at the start of the Agent's context. Project rules are .mdc files in .cursor/rules, and you check them into git. The frontmatter at the top of each file sets when the rule applies. It can apply in every chat, for matching files, when Agent finds it relevant, or only when you mention it.

Where do Cursor rules go?

Cursor has four kinds of rules, and each kind lives in a different place.

A plain .md file inside .cursor/rules is ignored, because it has no frontmatter. You can also sort .mdc files into folders there. AGENTS.md is plain Markdown with no frontmatter, so it suits simple setups.

.cursor/rules/
  react-patterns.mdc     read as a rule
  api-guidelines.md      ignored (wrong extension)
  frontend/
    components.mdc       read as a rule

How does a rule decide when to apply?

Three frontmatter fields decide it: alwaysApply, globs and description. The rule type you pick in Cursor sets those fields for you.

Here is a rule from the Cursor docs that loads only for component files.

---
globs: src/components/**/*.tsx
alwaysApply: false
---
- Use named exports, not default exports
- Co-locate styles in a module CSS file next to the component

How do I make a new Cursor rule?

Type /create-rule in Agent chat and describe what you want. Agent writes the file with the right frontmatter and saves it to .cursor/rules. You can also open Customize, go to Rules and click Add Rule.

What makes a good Cursor rule?

Cursor's own advice is short. Keep each rule under 500 lines, and split a big rule into smaller ones. Give concrete examples, and write each rule like clear internal docs. The docs also say this: "Start simple. Add rules only when you notice Agent making the same mistake repeatedly."

A rule can point to a file, such as @service-template.ts. Agent reads that file with its tools when it needs it. The file is not pasted into the prompt, so put anything that must always be in context in the rule itself.

Which Cursor rule wins when two of them disagree?

Cursor merges every rule that applies. When they conflict, Team rules win over Project rules, and Project rules win over User rules. With nested AGENTS.md files, the file closest to the code you are working on wins.

Should I use a Cursor rule or a skill?

A rule fits a convention with a clear trigger, like a style that every component file should follow. A skill suits a longer playbook, because Agent loads it only when a task needs it. Cursor has a built-in /migrate-to-skills command that turns Apply Intelligently rules and slash commands into skills. It leaves Always Apply rules, glob rules and User rules alone. Our Cursor skills page shows where Cursor reads skills.

FAQ

Do Cursor rules affect Cursor Tab?

They do not. The Cursor docs say rules do not change Tab or the other AI features.

Do User rules apply to Inline Edit?

They do not. Only Agent chat uses User rules, so Inline Edit (Cmd or Ctrl+K) runs without them.

Why is my Cursor rule not loading?

First, check that the file ends in .mdc. Then check the rule type. An Apply Intelligently rule needs a description, and an Apply to Specific Files rule needs a pattern that matches the file you are working on.

Can I keep Cursor rules in subfolders?

You can. Folders inside .cursor/rules work, and you can put an AGENTS.md file in any subfolder of your project. Cursor combines nested AGENTS.md files with the ones above them.