When adding a new rule file to cursor/rules, cursor automatically creates a .mdc file. There is no mention of this file type or how the actual description of the rule should be formatted. So, I have a few questions:
is this some kind of markdown extension? The most likely candidate I could find is mdc which afaict was born out of the nuxt front end framework.
Should these files be formatted as markdown? It looks like the .mdc extension exists so that xml can be embedded in a markdown file. So should these rules be encoded as xml? Can we just treat these as plaintext and assume the model will figure it out? It would be great to know what the intention of the cursor developers is here.
This is what I found when I asked cursor about it with @web
This is similar to how other specialized Markdown variants have their own extensions. For example, from the search results we can see:
.md or .markdown for standard Markdown files
.mdc for Cursor’s rule files
Other variants like RMarkdown have their own extensions too
The .mdc extension helps Cursor identify which files should be processed as rules, just like how .md helps systems identify regular Markdown files. It’s a way of telling Cursor “this is a rules file” rather than just a regular Markdown or YAML file.
I did a bit of digging for this, because the docs don’t talk about the file format. This is what I was able to confirm:
File format
Cursor engineer Michael Feldstein (@msfeldstein) mentioned on Twitter that it’s only a Markdown file with structure:
It’s just a markdown file with structured frontmatter that we render a custom editor for so you can @-mention files in your codebase and to make sure the metadata stays intact.
Wild that after more than half a year there’s still no official word on what the .mdc format actually is or how we’re supposed to use it. Is it this format? Your docs only state that it’s “a format supporting metadata and content”. I got a couple of questions, like…
What exactly are mdc: links and how are they meant to work?
Are relative links to non-rules files in the codebase supported or not?
Is there a schema, or are we all just guessing and hoping the model figures it out?
There are way too many open questions here for this to be solved by random digging or using the @web tool. At this point we really need a real, official spec or even a minimal schema from the Cursor team. Otherwise, we’re stuck reverse-engineering a black box — which is pretty frustrating when these files are supposed to be the backbone of project-level rules.
IMO, the agent rules chaos around the industry cries for a standardisation effort that works with any LLM agent/client (just like it was apparently possible with the mpc protocol). Never seen such a chaos with lacking standards since the foundation of the WWW. How about founding an W3C/ISO org just for AI agents standards?
Front page on a google search for “mdc cursor format”. Most of my rules have been Cursor generated so I assume it knows its own format. But a schema would be really helpful.