To describe the RULE.md files, I would expect you to be showing examples of markdown…but you’re showing rendered text.
And a template name which is probably the name of the asset being rendered, but seems like it shouldn’t be rendered.
aka I can’t follow the documentation and I’m not sure it’s my fault.
As an aside, at some point, you should probably link to or pay someone to write a description of what frontmatter is, and which tags are supported - if it is a limited set.
“It’s important to note that Frontmatter is parsed as YAML blocks, so the indentation is important”
Ah.
Every day, we stray further from the light of god.
Hey, thanks for the report. I get the confusion. The docs show the final result after the rules are applied, not the source code of the RULE.md file.
What you need to copy: you need to create the folder structure and the RULE.md file yourself, following the format described.
Example for Express/React:
Create the folder .cursor/rules/templates/
Inside it, create a RULE.md file with this content:
---
description: "Templates for Express services and React components"
alwaysApply: false
---
This rule provides a template for Express services:
Use this template when creating Express service:
- Follow RESTful principles
- Include error handling middleware
- Set up proper logging
@express-service-template.ts
This rule defines React component structure:
React components should follow this layout:
- Props interface at top
- Component as named export
- Styles at bottom
@component-template.tsx
Create the template files next to RULE.md (express-service-template.ts and component-template.tsx) with whatever code you want.
The docs show the final rule content that the AI will see, not the source files. I agree it’s confusing, I’ll pass the feedback to the team.
Re: frontmatter, it’s the YAML block at the top of the markdown file between ---. Supported fields are description, alwaysApply, globs. This is a standard format, not specific to Cursor.
Oddly ‘RULE.md’ has been removed from the documentation, despite RULE.md being the only name that works.
It uses an example of:
.cursor/rules/
react-patterns.mdc # Rule with frontmatter (description, globs)
api-guidelines.md # Simple markdown rule
frontend/ # Organize rules in folders
components.md
Which does not work, it ignores those .md files. The only thing that seems to work is:
.cursor/rules/
react-patterns.mdc # Rule with frontmatter (description, globs)
rulename/ # Organize rules in folders
RULE.md
I believe there was a note about .mdc files being legacy/deprecated, which has been removed also. I guess that is a good thing as the create-rule skill insists on creating rules with .mdc extension.
But that is also a shame, as the .mdc style rules don’t work in sub-directories like this:
But RULE.md may or may not support frontmatter, depending on which way Cursor decides to go tomorrow. It’s also anyone’s guess whether this multi .cursor folder support is intended behaviour or a bug as the documentation is inconsistent and the rules behaviour is constantly changing.
Can we get some kind of confirmation about what is meant to be supported in the long run? We can’t build projects only to find we have to re-write all our rules from a collection of .mdc files to a single RULE.md.. and then later find out multiple .cursor/rules directory support gets removed.
We have an enterprise licence to ensure the software works as specified and will remain supported but this is proving quite difficult without correct documentation or adherance to the doc.
If we’re wishing for things, I think I might need a way to debug rules, or at least sanity check the agent is getting them.
My dev environment is partly PHP running inside a docker container. I wrote two simple rules to point the agent to where the tests live, and how they should be run.
”If you are writing any code, or running any scripts, read the document @docs/development-environment.md.
If you are doing any coding, read the document @docs/testing.md to learn how to run the tests.”
I haven’t seen an agent read those documents yet, unless I mention them in chat.
