IDE removing YAML frontmatter of agents

[felippe.serralvo]

Where does the bug appear (feature/product)?

Cursor IDE

Describe the Bug

I have some agents written in .cursor/agents and everytime i opened any of those, the IDE automatically remove the header frontmatter of that file (description, model, etc). So everytime i need to create new ones or update the existant ones, i need to put the header from another IDE.
What can i do to solve this issue ?

Steps to Reproduce

Have an agent file in .cursor/agents/NAMEOFTHEAGENT.md with the commons standards of this file with the default YAML Frontmatter header

Expected Behavior

Dont remove it automatically, se we could edit and improve agents from inside of the ide.

Screenshots / Screen Recordings

Operating System

Windows 10/11

Current Cursor Version (Menu → About Cursor → Copy)

Version: 2.3.34 (system setup)
VSCode Version: 1.105.1
Commit: 643ba67cd252e2888e296dd0cf34a0c5d7625b90
Date: 2026-01-10T21:17:10.428Z
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0
OS: Windows_NT x64 10.0.22631

Additional Information

This issue started after the last update

Does this stop you from using Cursor

No - Cursor works, but with this issue

[deanrie]

Hey, thanks for the report. This is a known issue with .mdc files, and the team is aware.

I recommend switching to the new rules format. Instead of single .mdc files, use folders with a RULE.md:

.cursor/rules/
  especialista-tauri-multiplataforma/
    RULE.md

The RULE.md structure is the same, frontmatter plus content:

---
description: "This rule provides standards for frontend components and API validation"
alwaysApply: false
---

...rest of the rule content

More details in the docs: Rules | Cursor Docs

The new format works more reliably with the editor. If you still have issues after migrating, let me know.

[felippe.serralvo]

I just noticed that u specified for me to structure it as a rule, but my problem is on .cursor/agents ! What should i do in these cases ?

[deanrie]

Thanks for clarifying. You’re right, my previous reply was about .cursor/rules/ (which use .mdc), but your issue is with .cursor/agents/.

Important note for the team: .cursor/agents/ is the directory for subagents (a nightly feature). Per the docs (Subagents | Cursor Docs), it should contain .md files with YAML frontmatter, not .mdc:

---
name: security-auditor
description: Security specialist...
model: inherit
---

Content...

The IDE removes the frontmatter when opening these files, which breaks subagent functionality. It might be because you’re using the .mdc extension instead of .md.

For troubleshooting, can you check:

• Are you opening the file on the nightly channel? (Subagents are only available there)
• Do you have any extensions related to Markdown or YAML?

For now, the workaround is to edit the file in an external editor (like you’re doing).

I’ll pass this to the team and note that it affects the nightly subagents feature.

[felippe.serralvo]

Ah i understand! I Didnt notice that was a nightly feature, im using the stable one.
But the problem happen with md or mdc the same (i tried both), and is something that started to happen recently, wasn’t happen before.

[deanrie]

Thanks for the clarification.

One important thing: subagents (.cursor/agents/) are a nightly feature. If you’re on the stable channel (version 2.3.34), this functionality isn’t officially available there. That might be why the IDE is handling these files incorrectly, it doesn’t expect them to exist on stable.

Could you try switching to the nightly channel and check if the issue still happens there?

• Cursor Settings > Beta > Update Access > Nightly
• After switching, restart Cursor
• Open a file from .cursor/agents/ and see if the frontmatter gets removed

Also, please check what extensions you have installed, especially for Markdown or YAML. One of them might be formatting the file on open.

If the issue still happens on nightly, let me know and I’ll pass it to the team for a deeper look.