Nested Markdown files inside `.cursor/agents` are incorrectly detected as subagents

Support Bug Reports
1

Where does the bug appear (feature/product)?

Cursor IDE

Describe the Bug

Cursor is incorrectly detecting nested Markdown files inside an agent directory as separate agents.

For example:

.cursor/
└── agents/
    └── a11y-agent/
        ├── a11y-agent.md
        └── references/
            └── wcag-1.3.1.md

The file references/wcag-1.3.1.md is only supporting documentation for the a11y-agent. However, if it contains YAML frontmatter (or even just the standard Markdown --- separator), Cursor exposes it as another subagent.

Example:

---
title: WCAG 1.3.1
---

...

Or

## Section 1

---

## Section 2

The — syntax is a standard part of Markdown. It is commonly used for YAML frontmatter, document metadata, or section separators, so its presence alone should not cause a file to be interpreted as a subagent.

Steps to Reproduce

  1. Create an agent:
.cursor/agents/a11y-agent.md

or

.cursor/agents/a11y-agent/a11y-agent.md
  1. Add a nested documentation file:
.cursor/agents/a11y-agent/references/wcag-1.3.1.md
  1. Add YAML frontmatter to the nested file:
---
title: WCAG 1.3.1
---

Content...
  1. Reload Cursor.
  2. Open chat and type /wcag- you will see suggestion of wcag-1.3.1 subagent.

Expected Behavior

Only actual agent definition files should be discovered as agents.

Nested documentation, reference material, examples, prompts, specifications, or any other supporting Markdown files should not appear as separate agents.

Screenshots / Screen Recordings

No issue if no --- string present inside file
No issue if no --- string present inside file2854×718 162 KB
Reproduction of issue
Reproduction of issue2850×898 167 KB

Operating System

MacOS

Version Information

Cursor IDE: 3.12.17

Does this stop you from using Cursor

Sometimes - I can sometimes use Cursor

3

I think there are a few possible approaches.

Option 1

Only scan top-level files inside .cursor/agents.

For example:

.cursor/agents/
    agent-a.md
    agent-b.md

Everything inside subdirectories would be ignored during agent discovery.

Option 2 (Preferred)

Adopt a folder-based agent structure similar to Cursor Skills.

For example:

.cursor/
└── agents/
    └── agent-name/
        ├── AGENT.md
        ├── references/
        ├── prompts/
        ├── examples/
        └── assets/

Only AGENT.md would define the agent, while the remaining files would simply be resources.

This mirrors the existing Skill structure (<skill>/SKILL.md) and would provide a much cleaner and more scalable organization for complex agents.

Option 3

Instead of treating any Markdown file with frontmatter as an agent, require an explicit marker on similar lines of `disable-model-invocation`

6

Hey, thanks for the detailed report with screenshots and the suggested options, it really helps.

I reproduced it, this is a bug on our side. The scan of .cursor/agents/ runs recursively through all subfolders, and any markdown file with YAML frontmatter or a pair of --- separators gets detected as a separate sub-agent. The name is taken from the filename, which is why you see /wcag-1.3.1. I’ve reported it internally. I can’t share an ETA for the fix yet.

Small repro note: a single --- by itself doesn’t trigger it. You specifically need a pair of --- (two horizontal rules) or a real frontmatter block. Your Section 1/2/3 example triggers because it has two separators.

Workaround for now:

  • Keep reference/supporting materials outside .cursor/agents/, for example in a separate folder like .cursor/agent-docs/, or
  • Remove paired --- blocks and frontmatter from nested documents.

Your Option 2 (a folder-based structure with AGENT.md, similar to skills) makes sense. I included it with the report. I’ll post an update in the thread once we have a fix.