Writing Cursor Rules

Cursor rules are persistent instructions that customize how Cursor's AI agent behaves. Instead of repeating the same preferences in every chat message — "use TypeScript interfaces, not types" or "always write tests with Vitest" — you write a rule once and Cursor follows it automatically.

Rules live in your project's .cursor/rules/ directory as .mdc files (markdown with YAML frontmatter). They replace the deprecated .cursorrules root file with a more flexible system that supports conditional activation, file-pattern matching, and team sharing via version control.

Important: Cursor rules only affect the Agent (Chat). They do not affect Tab autocomplete or Inline Edit (Cmd/Ctrl+K).

The Four Rule Types

Cursor supports four rule activation modes, controlled by the frontmatter fields you set:

Type	Frontmatter	When it activates
Always Apply	alwaysApply: true	Every conversation, unconditionally
Auto	description present, no globs	Agent reads the description and decides if it's relevant
Glob-matched	globs: ["**/*.tsx"]	When conversation involves files matching the pattern
Manual	No description, no globs, alwaysApply: false	Only when you type @ruleName in chat

When to use each:

• Always Apply — project-wide conventions that should never be skipped (coding style, language preferences, error handling patterns)
• Auto — context-dependent rules where the agent should judge relevance (framework-specific patterns, testing conventions, API design rules)
• Glob-matched — file-type-specific rules (React component patterns for .tsx, SQL conventions for .sql, test patterns for *.test.*)
• Manual — specialized rules you invoke on demand (migration guides, refactoring checklists, one-off processes)

Rule File Format

Each rule is an .mdc file in .cursor/rules/ with YAML frontmatter and a markdown body:

---
description: "React component conventions using TypeScript interfaces and functional components"
alwaysApply: false
globs: ["**/*.tsx", "**/*.jsx"]
---

# React Component Conventions

## Structure
- Use functional components with arrow function syntax
- Define props using TypeScript interfaces (not type aliases)
- Use named exports, not default exports

## Example

\`\`\`tsx
interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: "primary" | "secondary";
}

export const Button = ({ label, onClick, variant = "primary" }: ButtonProps) => {
  return (
    <button className={variant} onClick={onClick}>
      {label}
    </button>
  );
};
\`\`\`

Frontmatter fields:

Field	Type	Purpose
description	string	Tells the agent what this rule covers — used for Auto activation
alwaysApply	boolean	If true, loaded on every conversation
globs	string or string[]	File patterns that trigger this rule

Folders inside .cursor/rules/ are purely for your organization — Cursor flattens the structure when loading rules.

Step 1: Create Your First Rule

mkdir -p .cursor/rules

Create a new file — for example, .cursor/rules/coding-style.mdc:

---
description: "Project coding style and conventions"
alwaysApply: true
---

# Coding Style

- Use 2-space indentation
- Use single quotes for strings
- Add trailing commas in multi-line arrays and objects
- Prefer const over let; never use var
- Use early returns to reduce nesting

This rule applies to every conversation because alwaysApply: true.

Step 2: Write Effective Instructions

The difference between a useful rule and a wasted one comes down to specificity.

Good rules are:

Quality	Bad example	Good example
Specific	"Write clean code"	"Use 2-space indentation, single quotes, trailing commas"
Actionable	"Follow best practices"	"Every async function must have a try/catch with typed error handling"
Example-rich	"Use proper naming"	"Variables: camelCase. Components: PascalCase. Constants: UPPER_SNAKE_CASE. Example: const MAX_RETRIES = 3"
Focused	One file covering everything	One file per topic: react.mdc, testing.mdc, api.mdc

Best practices:

• One topic per file. A rule about React conventions and a rule about SQL queries should be separate files. This lets glob patterns and Auto descriptions work precisely.
• Include code examples. Concrete examples are more effective than abstract descriptions. Show the pattern you want, not just a description of it.
• Keep rules under 500 lines. Longer rules waste context tokens. If a rule grows too large, split it into focused sub-rules.
• Write descriptions like search queries. For Auto rules, the agent reads the description to judge relevance. "React component conventions using TypeScript interfaces and functional components" is better than "React rules."
• Update rules when the agent repeats mistakes. If you find yourself correcting the same behavior, add it to a rule so you don't have to correct it again.

Step 3: Test and Iterate

After creating a rule, verify it works:

1. For Always Apply rules: Start a new chat and ask the agent to write code. Check that it follows your conventions without being told.

2. For Auto rules: Describe a task that matches the rule's description. The agent should pick up the rule automatically. If it doesn't, make the description more specific.

3. For Glob-matched rules: Open or reference a file that matches the glob pattern, then ask the agent to modify it. Verify it follows the file-type-specific conventions.

4. For Manual rules: Type @rule-name in chat and confirm the agent acknowledges and follows the rule's instructions.

If a rule isn't activating, check: Is the file in .cursor/rules/? Does the frontmatter parse correctly (valid YAML)? For glob rules, does the pattern match your files?

Rule Precedence

When multiple rules apply, Cursor merges them with this priority order:

Level	Location	Managed by
Team	Cursor dashboard	Admins (Team/Enterprise plans)
Project	.cursor/rules/ in repo	Developers via git
User	Cursor Settings > Rules	Individual preference

Higher-priority rules win when there are conflicts. In practice, commit project rules to .cursor/rules/ in your repo so the whole team shares them, and use personal User rules for individual preferences like verbosity or language.

Common Rule Categories

Here are the most common types of rules developers create:

• Coding standards — indentation, naming conventions, import ordering
• Framework conventions — React component patterns, Next.js App Router practices, API route structure
• Testing patterns — test file naming, assertion style, mock conventions, coverage requirements
• Documentation style — comment format, JSDoc requirements, README structure
• Architecture rules — folder structure, dependency directions, module boundaries
• Error handling — try/catch patterns, error types, logging conventions
• Security — input validation, authentication checks, secrets handling
• Git workflow — commit message format, branch naming, PR description templates

Cursor Rules vs Skills vs AGENTS.md

Multiple systems exist for giving AI agents persistent instructions. Here's how they compare:

System	Format	Works in	Activation
Cursor Rules	.mdc in .cursor/rules/	Cursor only	Always, Auto, Glob, Manual
Skills	SKILL.md in .claude/skills/	30+ tools (Claude Code, Cursor, VS Code, Windsurf, Codex, etc.)	Auto + slash command
AGENTS.md	Plain markdown in project root	Multiple editors	Always loaded

When to use each:

• Use Cursor Rules if your team uses Cursor exclusively and wants fine-grained control over activation modes
• Use Skills if you want maximum portability across editors — the Agent Skills open standard is supported by the widest range of tools
• Use AGENTS.md for simple, universal instructions that any editor can read

Many rules on Machina are available in both Cursor and Skills formats.

Sharing Your Rules

• Version control. Commit .cursor/rules/ to your repo. Every team member gets the rules automatically.
• Submit to Machina. Submit your rule to the directory and share it with the community. Rules are reviewed before going live, and you get attribution as the creator.
• Cursor Remote Rules. Import rules from a GitHub repo URL via Cursor Settings. The rules auto-sync when the source repo updates.
• Convert to Skills. For maximum portability, convert your best Cursor rules into Agent Skills that work across 30+ tools.

Common Questions

How many rules can I have?

There's no hard limit on the number of rule files. However, every active rule consumes context tokens. Use Always Apply sparingly (only for truly universal conventions) and prefer Auto or Glob-matched rules that load only when relevant.

Do rules affect autocomplete (Tab)?

No. Cursor rules only affect the Agent (Chat). Tab autocomplete and Inline Edit (Cmd/Ctrl+K) do not read rules. If you need consistent autocomplete behavior, that's controlled by Cursor's model settings, not rules.

Can I convert cursor rules to skills?

Yes. The content is compatible — both are markdown with YAML frontmatter. Change the frontmatter fields to the Skills format (name and description), rename the file to SKILL.md, and place it in .claude/skills/. See the Getting Started with Skills tutorial for the full format.

How do I organize rules in a large project?

Use folders within .cursor/rules/ for logical grouping (e.g., frontend/, backend/, testing/). Cursor ignores the folder structure when loading rules, so this is purely for human readability. Prefer many focused rules over one massive file — it's easier to maintain, review, and selectively activate.

Next Steps

• Browse cursor rules — explore community rules for every framework and language
• Get started with skills — portable AI agent instructions for 30+ tools
• Set up MCP servers — connect external tools to your AI assistant
• Submit a rule — share your rules with the community