Skip to content
Deftro
Start free
Guide

Cursor Rules: Where They Go and How to Share Them

Cursor reads project rules from .mdc files in .cursor/rules/. Each file starts with a short frontmatter block that says when the rule applies, followed by Markdown instructions. The single .cursorrules file at the repository root is the older, legacy format. Commit .cursor/rules/ to give the whole team the same rules.

Updated

What is in a .mdc rule file?

Frontmatter, then Markdown. The frontmatter tells Cursor when to include the rule; the Markdown is what the agent reads.

.cursor/rules/release-notes.mdc
---
description: Write release notes from the pull requests merged since the last tag.
alwaysApply: false
---

# Release notes

1. Find the last tag with `git describe --tags --abbrev=0`.
2. List the pull requests merged since then.
3. Group them under Features, Fixes and Internal.
  • description: what the rule is for. With alwaysApply: false and no globs, the agent decides from this line whether to pull the rule in.
  • globs: file patterns, such as src/**/*.tsx, that attach the rule when matching files are in play.
  • alwaysApply: true puts the rule in every request. Keep that for a few short, universal rules.

How do .cursor/rules, .cursorrules and AGENTS.md differ?

.cursor/rules/ holds many scoped rules and is the current format. .cursorrules is one legacy file. AGENTS.md is a plain Markdown file that many agents read, not only Cursor.

FileWhat it isWhen to use it
.cursor/rules/*.mdcOne file per rule, each with its own frontmatter.Rules for Cursor, scoped to parts of the codebase.
.cursorrulesA single file at the repository root.Older projects. Move its contents into .cursor/rules/ when you can.
AGENTS.mdPlain Markdown, no frontmatter. A convention many coding agents read.Instructions every agent on the project should see, whichever one each person uses.

Can I use a SKILL.md as a Cursor rule?

Yes. Deftro turns a skill into a rule when it installs it: the skill's description becomes the rule's description, and its steps become the body.

Terminal
npx @deftro/cli install <handle>/<slug> --agent cursor

The rule is written to .cursor/rules/<slug>.mdc with alwaysApply: false, so Cursor includes it when a request matches the description. Any other files in the skill are copied to .cursor/rules/<slug>/ and listed at the end of the rule. Without --agent, the CLI writes for every agent folder it finds in the project, so one skill serves the Cursor and Claude Code users on the same team.

How do I share one set of rules across a team?

Commit .cursor/rules/ to the repository. For rules that several repositories need, keep them in one place and install them into each.

  • Committed rules reach everyone who pulls the branch, and changes to them show up in code review like any other file.
  • For rules shared across many repositories, an organisation vault on Deftro holds one copy, attaches it to the projects that need it, and deftro sync writes the reviewed version into each.
  • Read a rule before adding it. It shapes what the agent does with your code; see Should you trust an agent skill?

More guides

All guides
Browse skillsOpen Discover