Cursor Rules
How rules work in Cursor. Project rules, user rules, team rules, AGENTS.md, frontmatter fields, application modes, rule priority, remote rules, Agent Skills, and legacy .cursorrules migration.
For the official documentation, see Cursor Rules. For VS Code and GitHub Copilot, see VS Code Custom Instructions.
Rules apply only to Agent (Chat). They do not affect Cursor Tab, Inline Edit (Cmd/Ctrl+K), or other AI features.
Rule Types
Cursor has four types of rules:
Stored in .cursor/rules/ within your project directory. Version-controlled and specific to one codebase.
Project rules support frontmatter for managing when and how they apply. This is the most flexible rule type.
Application Modes
Project rules can be applied in four ways, based on their frontmatter:
Included in every chat session automatically. Use for rules that always matter, such as coding conventions, project-wide patterns, and architecture guidelines.
Frontmatter Fields
Project rules use Markdown (.md) or frontmatter-enhanced Markdown (.mdc) with optional YAML frontmatter:
| Field | Purpose |
|---|---|
| description | Tells the AI when this rule is relevant; used for matching |
| alwaysApply | true to include in every session, false for conditional application |
| globs | File patterns that trigger this rule (e.g., ["*.tsx", "src/api/**"]) |
If you omit the frontmatter, the rule functions as a simple Markdown file,
similar to how AGENTS.md works.
Referencing Files in Rules
Use @filename syntax inside a rule to include content from other files without duplication:
The agent resolves these references and loads the relevant file content when the rule is applied.
Rule Priority
When multiple rules apply, they follow this order:
Team Rules (highest priority)
Organization-wide standards always override individual preferences.
Project Rules
Codebase-specific conventions and patterns.
User Rules (lowest priority)
Personal preferences that yield to project and team rules.
Importing Rules
AGENTS.md vs Project Rules
| Feature | AGENTS.md | Project Rules (.cursor/rules/) |
|---|---|---|
| Format | Plain Markdown | Markdown with optional frontmatter |
| Setup | Drop file in directory | Create .cursor/rules/ directory |
| Metadata | None | description, globs, alwaysApply |
| Nesting | Subdirectory support | Subdirectory support |
| Scoping | Directory-based | Pattern-based (globs) |
| Best for | Simple, straightforward rules | Complex, conditionally-applied rules |
Legacy .cursorrules
Cursor previously used a .cursorrules file in the project root. This format
still works but is outdated. Migrate to Project Rules (.cursor/rules/) or
AGENTS.md for better organization and frontmatter support.
Writing Effective Rules
What to Avoid
| Mistake | Why |
|---|---|
| Duplicating linter rules | If ESLint or Prettier handles it, don't repeat it |
| Documenting obvious tool usage | The AI already knows common tools |
| Rare edge cases | Focus on patterns that apply often |
| Copying entire codebases | Reference files with @filename instead |
Selling Cursor Rules on Skly
- List "Cursor" as a supported AI tool so buyers can find compatible rules.
- Use the
.mdformat since it's portable across AI tools, not just Cursor. - Include frontmatter so buyers can configure application mode (always, intelligent, glob-scoped).
- Make rules self-contained so buyers can use them right away without setup.
- Test with Cursor Agent to ensure rules work in chat mode, since that's where they apply.
Comparison with VS Code
| Feature | Cursor | VS Code / Copilot |
|---|---|---|
| File location | .cursor/rules/ | .github/instructions/ |
| Workspace file | AGENTS.md or project rules | .github/copilot-instructions.md |
| Scoping | globs array in frontmatter | applyTo glob in frontmatter |
| Intelligent matching | alwaysApply: false enables AI matching | Not natively supported |
| Inline suggestions | Supported | Not supported |
| Organization sharing | Team rules via dashboard | GitHub org-level instructions |
| AGENTS.md | Supported | Supported (experimental nesting) |
Both formats use Markdown, so rules sold on Skly can usually support both tools with minimal changes.