Committed project custom subagents missing from Task enum — Invalid enum on Cursor 3.12.17

Support Bug Reports
1

Where does the bug appear (feature/product)?

Cursor IDE

Describe the Bug

Cursor Desktop / Agent / Custom Subagents / Task tool

Cursor does not register five newly created, committed project custom subagents in the Task tool’s subagent_type enum.

Three previously committed project agents continue to appear:

  • arch-01
  • sec-01
  • qa-01

Five newly committed agents do not appear:

  • aie-01
  • be-01
  • fe-01
  • ops-01
  • cse-01

All five files are present under .cursor/agents/, readable from committed HEAD, and contain valid YAML frontmatter.

Example:

---
name: aie-01
description: AI and agent engineering specialist. Use for model integration, agent workflows, prompts, tools, MCP boundaries, evaluations, retrieval, and governed AI behavior.
model: inherit
readonly: false
---

The other four use the same documented schema with unique lowercase, hyphenated names and descriptions.

Actual behavior

The Task tool rejects the identifier:

subagent_type: Invalid enum value. Expected '... | arch-01 | qa-01 | sec-01 | ...'. Received 'aie-01'

The captured Task enum includes:

generalPurpose
explore
shell
cursor-guide
ci-investigator
bugbot
security-review
best-of-n-runner
arch-01
qa-01
sec-01
ai-architect
deployment-expert
performance-optimizer
ci-watcher
thermo-nuclear-code-quality-review
codebase-navigator
enterprise-searcher
people-finder
plan-prep-researcher
gitlab-assistant

It omits all five new committed project agents.

Steps to Reproduce

  1. Add valid Markdown custom-agent definitions under .cursor/agents/.
  2. Commit the files.
  3. Confirm the repository worktree is clean.
  4. Fully exit all Cursor processes.
  5. Reopen the repository folder in a new Cursor window.
  6. Start a new Agent conversation.
  7. Explicitly invoke /aie-01.
  8. Observe the Task tool rejection.

Expected Behavior

Cursor documentation states that project custom agents in .cursor/agents/ are included in Agent’s available tools and may be explicitly invoked using /name.

The five agents should therefore appear in the Task enum and accept native invocation.

Operating System

Windows 10/11

Version Information

IDE:
Version: 3.12.17
OS: Windows 11
Cursor Agent CLI: 2026.07.16-899851b
Agent files: project-scoped .cursor/agents/*.md
Repository state: committed and clean
Full Cursor process restart performed
New Cursor window and new Agent conversation used

For AI issues: which model did you use?

Agent / Task tool (custom project subagents)

For AI issues: add Request ID with privacy disabled

7ad7a2c6-1b1b-422a-bb5e-3ded13011c6e

Additional Information

Verification already performed

  • Correct repository root confirmed
  • Correct branch and committed HEAD confirmed
  • Worktree clean
  • Agent files present in committed HEAD
  • YAML frontmatter parsed successfully
  • Names match filenames
  • readonly: false is a documented boolean value and default
  • Full Cursor process restart performed
  • New window and new Agent conversation used
  • Failure reproduced in both uncommitted and committed states
  • Existing project agents remain discoverable
  • No fallback roleplay used

Impact

This blocks qualification and use of newly created native project subagents. Existing custom agents work, but Cursor will not add new valid definitions to the Task catalog.

Privacy

No proprietary agent bodies, source code, secrets, or repository contents are included in this report.

Does this stop you from using Cursor

No - Cursor works, but with this issue

6

Hey @OperatorHSX,
The most likely cause: a .cursor/agents/*.md file gets silently dropped from the Task subagent_type enum when it has valid frontmatter but no prompt body - i.e. nothing (or only whitespace) after the closing ---. The loader treats the text after the frontmatter as the subagent’s system prompt and skips any file without one, with no warning, log, or entry in Settings. That fits what you’re seeing: the three older agents load, the five new ones don’t, and the enum simply never learns their names.

Your pasted example ends right at the closing ---. I know you trimmed the bodies for privacy, so this may just be the redaction — but it’s the first thing to confirm: open each of the five new files (aie-01, be-01, fe-01, ops-01, cse-01) and make sure there’s at least one non-blank line of prompt text after the ---, like the example in the subagents docs. Add a line, save, and reload the window (or restart) - if that’s it, all five should appear right away.

If the five already have real bodies, it’s one of the other things that cause a silent skip, roughly in order of likelihood:

  • Extension: the file has to end in .md (.mdc/.markdown also work). A stray .mdx/.txt/.yaml is ignored.
  • Frontmatter fence: the file must start with --- on line 1 with a matching closing ---. A leading blank line/BOM, or a stray --- used as a divider inside a multi-line description, breaks parsing.
  • Duplicate name:: if two files share the same name, or a new name collides with a user-level agent in ~/.cursor/agents/, only one wins and the other is dropped silently.
  • Location: the files need to sit directly under .cursor/agents/, not nested inside a folder like node_modules/dist/build.

I did check the request you shared - it confirms those five names weren’t in the agent’s available tool list at that point, and the turn itself ran fine. But the reason a file gets dropped isn’t visible on our end; it happens during local loading, silently. So the fastest way to settle it is the files themselves: could you share the output of dir .cursor\agents (filenames + extensions) and confirm whether the five new files have any text after the closing ---? That’ll tell us exactly which of the above it is.

And you’re right that a file being dropped with zero feedback is rough - I’ve noted the silent skip internally so we can look at surfacing a warning when a subagent file is ignored, instead of quietly dropping it.

7

This is still a problem, but it only happens in the CLI. When I ask, “What Task subagent_type values do you have?”:

  • CLI returns only the builtins. And it won’t launch them correctly when I use /[subagent-name]
  • Cursor for MacOS returns a complete set, including my custom subagents. It launches them correctly when I use /[subagent-name]

CLI version is 2026.07.23-e383d2b

Both parent agents are “Auto”. In the CLI, switching to a specific model does not fix it.

And I did restart the CLI multiple times.

CleanShot 2026-07-29 at 10.27.21@2x
CleanShot 2026-07-29 at 10.27.21@2x1646×1128 139 KB

8

What you’re describing is actually a different scenario from OP’s report: they were on Windows/IDE with project-level .cursor/agents/, whereas you’re on macOS and the split is specifically IDE-vs-CLI with user-level ~/.cursor/agents/.

This is a parity gap we’re tracking on a separate thread: Cli: User-level subagents (~/.cursor/agents/) not shown in completions. The Cursor IDE picks up both scopes (~/.cursor/agents/ and the project’s .cursor/agents/), but the CLI currently only sees the project-level one - which matches exactly what you’re seeing. Feel free to hop over there and drop a +1 so you get pinged when there’s an update.

In the meantime, the workaround is to copy or symlink the files from ~/.cursor/agents/ into your project’s .cursor/agents/ folder — the CLI picks them up from there and /[subagent-name] should launch correctly. Something like this from the repo root:

mkdir -p .cursor/agents
ln -s ~/.cursor/agents/issue-planner.md .cursor/agents/issue-planner.md

Let me know if that unblocks you.