# What are Cursor rules? How to write them

> Cursor rules are saved instructions that Agent reads at the start of a conversation, so you stop repeating yourself. The kind you commit with your code is an `.mdc` file in `.cursor/rules`. A few lines of frontmatter at its top decide whether it applies always, to matching files, when Agent finds it relevant, or only when you mention it.

Mindket editors · Published 2026-11-03 · Updated 2026-11-03 · https://mindket.com/blog/cursor-rules

## In short

- Name rule files `.mdc`, not `.md`, and commit them with your code.
- Turn an old `.cursorrules` file into an Always Apply rule before Cursor deprecates it.
- Read a public rule before you copy it: it steers what Agent does in your project.

## Create a rule

The fastest route is `/create-rule` in Agent chat. Say what the rule should do, and Agent writes the file with the right frontmatter and saves it in `.cursor/rules`. The Add Rule button under Customize, then Rules, creates the same file. To set each field yourself, use the command palette:

1. Open the command palette with Ctrl+Shift+P, or Cmd+Shift+P on a Mac, and run "New Cursor Rule".
2. Name it for one concern, such as `react-patterns` or `api-validation`.
3. Write the instructions as plain markdown, a few short lines to start.
4. Choose a type from the dropdown. For Apply to Specific Files, add the pattern, such as `*.tsx`. For Apply Intelligently, write the description.
5. Save. The file lands in `.cursor/rules/`, ready to commit.

[![eric zakariasson (@ericzakariasson) on X, 18 April 2025. In a thread about rolling out Cursor 0.49, he says you can now generate rules from a conversation with the command /Generate Cursor Rules. He calls it a good way to capture decisions from back and forth chats you might want to reuse later.](https://mindket.com/blog/shots/x-ericzakariasson-generate-cursor-rules.webp?v=48c04ae8019e)](https://x.com/ericzakariasson/status/1913291812762210454)

eric zakariasson on X, 18 April 2025

> Cursor's help page advises a flat `.cursor/rules` folder as simpler to manage, though its reference groups rules in subfolders, and both work. The screenshot, X's own embed of a reply and the post above it, dates from April 2025, when Cursor 0.49 called its rule command "/Generate Cursor Rules". The docs now describe `/create-rule`.

## The four ways a project rule applies

Whatever you pick in the dropdown is saved as frontmatter, a short block at the top of the `.mdc` file with three fields: `alwaysApply`, `description` and `globs`.

An applied rule's text goes in at the [start of the model's context](https://cursor.com/docs/rules), and Cursor's [ring chart of a chat's tokens](https://cursor.com/docs/agent/prompting) draws Rules as one slice beside skills and MCP. An always-on rule takes that slice in every conversation, and the cost [adds up](https://cursor.com/learn/customizing-agents). Save `alwaysApply: true` for the few lines every task needs, such as the test command, and let a `react-patterns` rule wait behind a `*.tsx` glob.

Always Apply loads the rule into every chat, and Cursor ignores any globs or description beside it. A file rule waits until a file matching its `globs` pattern is in context, and an Apply Intelligently rule until Agent judges its description relevant. A manual rule does nothing until you type its name after an `@`.

## What to put in a rule, with a sample to copy

Cursor's [agent best-practices post](https://cursor.com/blog/agent-best-practices) says to start with no rules and add one only when Agent makes the same mistake more than once. Say it keeps throwing raw strings from your API handlers. The sample below asks for `{ code, message }` error objects instead.

Save it as `.cursor/rules/api-handlers.mdc`, and set `alwaysApply: true` if you want it on in every chat.

Cursor describes rules as persistent context at the prompt level, not checks that run in your code, so the mistake can still come back. Then check that the rule loads and rewrite the line Agent ignores, or tag `@cursor` on a GitHub issue or pull request and Agent edits it for you. For anything security-related, Cursor's docs warn against making AI guidance your only control.

````markdown
---
globs: src/api/**/*.ts
alwaysApply: false
---

- Validate every request body with the zod schema in `src/api/schemas/` before it reaches a service.
- Return errors as `{ code, message }` objects from `src/lib/errors.ts`. Never throw a raw string.
- Put a test beside each handler. Copy the layout of @src/api/handlers/users.test.ts.
- Never edit `src/generated/`. Change the schema and run `npm run generate`.

````

- Cursor's own list of what to leave out starts with whole style guides. A linter does that job, and Agent already knows common conventions.
- No list of every command. Agent knows npm, git and pytest, so name only the ones that are yours.
- Skip edge cases that rarely come up.
- Don't paste code that already sits in your repository. Point to a canonical example instead.

## When a rule doesn't fire

Look at the file name before anything else. Cursor ignores plain `.md` files in `.cursor/rules` because they have no frontmatter, so a rule saved as `.md` never fires until you rename it to `.mdc`. If the name is right, look at the type you picked:

- Apply Intelligently with an empty description. Agent judges relevance from that one line, so write when the rule matters, not what it contains.
- Apply to Specific Files with a pattern that misses. Test it against a real path Agent is working with. `*.ts` skips every subfolder.
- Apply Manually. Nothing happens until you type `@` and the rule's name in chat.

## Cursor rules next to AGENTS.md, CLAUDE.md and skills

AGENTS.md is the plain version of a rule: markdown with no frontmatter and no types. Cursor reads it from the project root and from subfolders, where a nested file's instructions combine with its parents' and the more specific one wins.

Cursor reads [CLAUDE.md](https://mindket.com/blog/claude-md-file), Claude Code's file, the same way, except that it applies to every conversation whatever any `alwaysApply` setting says.

From version 2.1.277, [Claude Code reads AGENTS.md](https://code.claude.com/docs/en/memory) when no CLAUDE.md sits in or above the working folder, and a CLAUDE.md can pull the file in with an `@AGENTS.md` import, so one AGENTS.md serves both tools. Only what needs a glob, a description or a manual switch has to live in `.cursor/rules`.

[Skills](https://mindket.com/blog/what-are-agent-skills) stay out of context until their description fits the task or you type `/skill-name`. For how-to steps and context that changes with the task, Cursor's 2.4 [changelog](https://cursor.com/changelog/2-4) prefers them to always-on rules. Only an Apply Intelligently rule converts with `/migrate-to-skills`. Skill folders you already keep for Claude Code or Codex need no copy, because Cursor [reads those folders](https://cursor.com/docs/skills) as well.

> **When a rule should be a skill**
>
> Keep your rules minimal and high quality. They should be a shared artifact your team is constantly updating. If you only need something occasionally, put it in a skill instead.
>
> Cursor Learn, [Cursor Learn: Customizing agents](https://cursor.com/learn/customizing-agents) (read 2026-11-03)

|  | Project rule | AGENTS.md or CLAUDE.md | Skill |
| --- | --- | --- | --- |
| File | `.cursor/rules/name.mdc` with frontmatter | `AGENTS.md` or `CLAUDE.md`, plain markdown | `.cursor/skills/name/SKILL.md` with `name` and `description` |
| Applies | Always, by file pattern, by description or by mention | Picked up from the project root. A nested AGENTS.md applies to its folder. CLAUDE.md applies to every conversation | Agent picks it from the description, or you type `/name`. An optional `paths` field limits it to matching files |
| Suits | Short guidelines and constraints | Simple, readable instructions | Multi-step workflows and procedures |

**Which tool reads which instruction file**

| | Cursor | Claude Code | Codex |
| --- | --- | --- | --- |
| `AGENTS.md` | ✓ Yes | ◐ Partly | ✓ Yes |
| `CLAUDE.md` | ✓ Yes | ✓ Yes | ◐ Partly |
| A skill folder with a `SKILL.md` | ✓ Yes | ✓ Yes | ✓ Yes |

Sources: [Cursor docs: Rules](https://cursor.com/docs/rules) (read 2026-11-03), [Cursor Help: Rules](https://cursor.com/help/customization/rules) (read 2026-11-03), [Cursor docs: Agent Skills](https://cursor.com/docs/skills) (read 2026-11-03), [Claude Code docs: How Claude remembers your project](https://code.claude.com/docs/en/memory) (read 2026-11-03), [Claude Code docs: Extend Claude with skills](https://code.claude.com/docs/en/skills) (read 2026-11-03), [ChatGPT Learn: Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md) (read 2026-11-03), [ChatGPT Learn: Build skills](https://learn.chatgpt.com/docs/build-skills) (read 2026-11-03)

[![Cursor (@cursor_ai) on X, 23 January 2026. Agent Skills are now available in Cursor. The post says skills let agents find and run specialized prompts and code.](https://mindket.com/blog/shots/x-cursorai-agent-skills.webp?v=4c607ce97c0b)](https://x.com/cursor_ai/status/2014753596223770841)

Cursor on X, 23 January 2026

> Codex reads `CLAUDE.md` only if you list that name in `project_doc_fallback_filenames`. The screenshot shows Cursor's post without its video.

## Project, user and team rules: who gets which

An admin's team rule, a project rule from the repository and your own user rule can all apply to one chat. When they disagree, Cursor merges what applies and lets the earlier one win: team first, then project, then user.

Two rules with the same file name in different folders don't collide. Cursor tells rules apart by their full path, so both apply whenever their conditions match.

**How rules took shape in Cursor**

1. **January 23, 2025** Rules move into `.cursor/rules`. Version 0.45 lets you write several repository-level rules to disk in that folder, and Agent chooses which one to follow.
2. **April 15, 2025** Rules from a conversation. Version 0.49 adds a command that generates a rule from a chat. Rules with path patterns now apply by themselves when Agent reads or writes matching files.
3. **September 29, 2025** Team rules. Version 1.7 lets a team define rules in the dashboard that apply to all its projects.
4. **January 22, 2026** Skills. Version 2.4 adds Agent Skills, which agents can find and use when the task fits.
5. **February 17, 2026** Plugins carry rules. Version 2.5 adds plugins, which package skills, subagents, MCP servers, hooks and rules into one install.

Sources: [Cursor changelog 0.45.x](https://cursor.com/changelog/0-45-x) (read 2026-11-03), [Cursor changelog 0.49](https://cursor.com/changelog/0-49) (read 2026-11-03), [Cursor changelog 1.7](https://cursor.com/changelog/1-7) (read 2026-11-03), [Cursor changelog 2.4](https://cursor.com/changelog/2-4) (read 2026-11-03), [Cursor changelog 2.5](https://cursor.com/changelog/2-5) (read 2026-11-03)

| Kind | Where it lives | Who gets it |
| --- | --- | --- |
| Project rules | `.cursor/rules/*.mdc`, in the repository | Everyone who pulls the repository, once the files are committed. |
| User rules | Customize, then Rules, kept on your Cursor account | You, in every project. They sync when you sign in on another machine. |
| User rule files | `~/.cursor/rules` (`%USERPROFILE%\.cursor\rules` on Windows) | You, on this machine only. They don't sync. |
| Team rules | The Cursor dashboard, on Team and Enterprise plans | Every member. An admin can enforce one so it can't be switched off. |
| AGENTS.md | The project root and its subfolders | Plain markdown with no frontmatter. Nested files add to their parents'. |

> The old `.cursorrules` file in a project's root is legacy, and Cursor's [help page](https://cursor.com/help/customization/rules) says it will be deprecated. To migrate, create a new rule, paste the old file into it, set the type to Always Apply, which matches the old behavior, and delete `.cursorrules`.

## Share rules with a team or another project

Rules from another GitHub repository don't import by themselves. Cursor's route is a [plugin](https://cursor.com/docs/plugins): the `.mdc` files go in the plugin's `rules/` folder, and the plugin is published through a marketplace. In Customize, From GitHub Repository then imports it, provided the repository has a `.cursor-plugin/marketplace.json`.

Other people publish their rules in public repositories. On 3 November, GitHub's [repository search](https://github.com/search?q=cursorrules&type=repositories&s=stars&o=desc) for "cursorrules", sorted by stars, put `PatrickJS/awesome-cursorrules` first and `grapeot/devin.cursorrules` second.

**Stars on the top two GitHub results for "cursorrules"**

- **41,092** stars on `PatrickJS/awesome-cursorrules`, a collection of configuration files for Cursor (Source: [GitHub: PatrickJS/awesome-cursorrules](https://github.com/PatrickJS/awesome-cursorrules), read 2026-11-03)
- **5,956** stars on `grapeot/devin.cursorrules`, a rules setup for Cursor and Windsurf (Source: [GitHub: grapeot/devin.cursorrules](https://github.com/grapeot/devin.cursorrules), read 2026-11-03)

> We read every page cited here on 3 November and tried no rule hands-on, the sample included.

## Reference: frontmatter for each rule type, and glob patterns

`globs` takes patterns separated by commas, and two stars cross folders:

````text
*.ts                           .ts files in the root only
**/*.ts                        .ts files in any folder
src/**                         everything under src
docs/**/*.md, docs/**/*.mdx    two extensions, comma-separated
````

| Dropdown | `alwaysApply` | `description` | `globs` | Result |
| --- | --- | --- | --- | --- |
| Always Apply | `true` | ignored | ignored | Included in every chat session. |
| Apply to Specific Files | `false` | not needed | a pattern | Auto-attached when a matching file is in context. |
| Apply Intelligently | `false` | a sentence | omitted | Agent reads the description and pulls the rule in when it fits. |
| Apply Manually | `false` | omitted | omitted | Included only when you @-mention the rule, as `@my-rule`. |

## Frequently asked questions

### Do Cursor rules work in the Cursor CLI and in Cloud Agents?

Yes. The [CLI](https://cursor.com/docs/cli/using) uses the same rules system as the editor, and it also reads `AGENTS.md` and `CLAUDE.md` at the project root. Cursor's [Cloud Agent guide](https://cursor.com/docs/cloud-agent/best-practices) says those agents follow rules at three levels: user rules, team rules from the dashboard, and `.mdc` files committed to the repository.

### How long can a Cursor rule be?

Cursor suggests staying under 500 lines, though that's a guideline, not a cap. A rule covering both styling and testing works better as two files, each with its own type and glob.

### Can a rule include another file?

Only by pointing at it. Writing `@service-template.ts` in a rule tells Agent where to look, and Agent opens the file with its tools when it needs the contents. The file isn't pasted into the prompt, so anything that must always be in context belongs in the rule body.

### Do Cursor rules affect Tab completion or Bugbot?

No, they apply to Agent chat only, not to Tab completion or Cursor's other AI features. [Bugbot](https://cursor.com/docs/bugbot) has rules of its own for reviewing pull requests: team rules from Bugbot Automations, plus any `.cursor/BUGBOT.md` files in the repository.

## Sources

- [Cursor docs: Rules](https://cursor.com/docs/rules) (read 2026-11-03)
- [Cursor Help: Rules](https://cursor.com/help/customization/rules) (read 2026-11-03)
- [Cursor docs: Agent Skills](https://cursor.com/docs/skills) (read 2026-11-03)
- [Cursor Help: Skills](https://cursor.com/help/customization/skills) (read 2026-11-03)
- [Cursor docs: Using Agent in CLI](https://cursor.com/docs/cli/using) (read 2026-11-03)
- [Cursor docs: Plugins](https://cursor.com/docs/plugins) (read 2026-11-03)
- [Cursor docs: Cloud Agent best practices](https://cursor.com/docs/cloud-agent/best-practices) (read 2026-11-03)
- [Cursor docs: Prompting Agent](https://cursor.com/docs/agent/prompting) (read 2026-11-03)
- [Cursor docs: Bugbot](https://cursor.com/docs/bugbot) (read 2026-11-03)
- [Cursor blog: Best practices for coding with agents](https://cursor.com/blog/agent-best-practices) (read 2026-11-03)
- [Cursor Learn: Customizing agents](https://cursor.com/learn/customizing-agents) (read 2026-11-03)
- [Cursor changelog: 2.4, Subagents, Skills, and Image Generation](https://cursor.com/changelog/2-4) (read 2026-11-03)
- [Claude Code docs: How Claude remembers your project](https://code.claude.com/docs/en/memory) (read 2026-11-03)
- [Cursor changelog: 0.45.x, .cursor/rules, Better Codebase Understanding, New Tab Model](https://cursor.com/changelog/0-45-x) (read 2026-11-03)
- [Cursor changelog: 0.49, Rules generation, improved agent terminal and MCP images](https://cursor.com/changelog/0-49) (read 2026-11-03)
- [Cursor changelog: 1.7, Browser Controls, Plan Mode, and Hooks](https://cursor.com/changelog/1-7) (read 2026-11-03)
- [Cursor changelog: 2.5, Plugins, Sandbox Access Controls, and Async Subagents](https://cursor.com/changelog/2-5) (read 2026-11-03)
- [Claude Code docs: Extend Claude with skills](https://code.claude.com/docs/en/skills) (read 2026-11-03)
- [ChatGPT Learn: Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md) (read 2026-11-03)
- [ChatGPT Learn: Build skills](https://learn.chatgpt.com/docs/build-skills) (read 2026-11-03)
- [GitHub: repository search for cursorrules, sorted by stars](https://github.com/search?q=cursorrules&type=repositories&s=stars&o=desc) (read 2026-11-03)
- [GitHub: PatrickJS/awesome-cursorrules](https://github.com/PatrickJS/awesome-cursorrules) (read 2026-11-03)
- [GitHub: grapeot/devin.cursorrules](https://github.com/grapeot/devin.cursorrules) (read 2026-11-03)
- [eric zakariasson on X: generate rules from a conversation](https://x.com/ericzakariasson/status/1913291812762210454) (read 2026-11-03)
- [Cursor on X: Agent Skills are now available in Cursor](https://x.com/cursor_ai/status/2014753596223770841) (read 2026-11-03)

[Browse kits](https://mindket.com/kits)