Cursor Subagents and Skills: How They Work in 2026
Cursor added subagents and Agent Skills in version 2.4 on January 22, 2026. A month later, version 2.5 added a plugin marketplace to distribute them. Below is what each piece does, where Cursor expects the files, and how to write your own subagent or skill. Everything comes from Cursor's docs and changelogs. None of these features keeps what your agents learned last week, and that gap is covered at the end.
What are Cursor subagents, in one sentence?
A Cursor subagent is a specialized agent that the main Cursor agent hands part of a task to, running in its own context window and returning only its final result.
The Cursor 2.4 changelog introduced them as independent agents for "discrete parts" of a parent agent's task. They run in parallel. Each one can be given a custom prompt and model, and its tool access is configurable too. Skills arrived in the same release. A skill is a folder with a SKILL.md file that teaches the agent a procedure, and the agent loads it when it judges it relevant.
How do subagents, skills and rules differ?
Cursor now has three overlapping ways to shape what its agent does.
| Subagents | Agent Skills | Rules | |
|---|---|---|---|
| What it is | A separate agent with its own context window | A folder with a SKILL.md and optional scripts | Text added to the start of the model's context |
| Where it lives | .cursor/agents/ (also .claude/agents/ and .codex/agents/) | .cursor/skills/ or .agents/skills/ (also .claude/skills/ and .codex/skills/) | .cursor/rules/ as .mdc files, or AGENTS.md |
| When it runs | When the agent delegates, or when you type /name | When the agent judges it relevant, or from the / menu | Always, by file glob, by relevance, or by @-mention |
| Best for | Parallel or noisy work that should not fill the main context | Procedures: "how we deploy", "how we write migrations" | Standing facts and conventions |
| Token cost | Each subagent spends its own tokens | Only loaded when used | Paid on every request it applies to |
| Remembers past sessions? | No. Each starts with a clean context | No. It is static until you edit it | Only what you wrote into it |
Sources: Cursor's subagents docs and skills docs. The rules column follows the rules docs.
How do you create a custom subagent in Cursor?
A custom subagent is a Markdown file with YAML front matter, followed by the prompt. Put project subagents in .cursor/agents/ and personal ones in ~/.cursor/agents/. Cursor also reads the .claude/agents/ and .codex/agents/ folders, so subagents written for Claude Code or Codex work without copying. A project subagent overrides a user subagent with the same name. Within one level, .cursor/ wins over the other two folders.
The subagents docs list five optional fields:
- name: lowercase letters and hyphens. It defaults to the file name.
- description: the agent reads this to decide when to delegate. Writing "use proactively" in it encourages automatic use.
- model: inherit (the default) or a specific model ID. You can add options in brackets, such as an effort setting.
- readonly: when true, the subagent can only read. File edits and state-changing shell commands are blocked.
- is_background: when true, the subagent runs without blocking the parent.
Here is a small read-only reviewer:
---
name: api-reviewer
description: Reviews API handler changes. Use proactively after edits under src/routes.
model: inherit
readonly: true
---
Review the changed route handlers for input validation,
error handling and consistent response shapes.
Report findings by severity, with file and line.
You can call it by name with /api-reviewer, or just mention it in a sentence. Cursor also ships two built-in subagents that need no setup. Explore searches a codebase with many parallel searches on a faster model. Browser drives a browser through MCP tools and filters out noisy page snapshots.
How do subagents run, and what do they cost?
A subagent starts with a clean context. It does not see your conversation, so the parent must put everything it needs in the prompt. By default it shares the parent's checkout, which means parallel edits can collide. On request, each subagent gets its own Git worktree (or a cloud VM) and its own branch, and the parent merges the results.
Foreground subagents block until they return. Background subagents return at once and write their output to ~/.cursor/subagents/, where the parent can check on them. Version 2.5 made this asynchronous mode possible. Per the 2.5 changelog, it also let subagents spawn their own subagents. The docs limit that nesting to one level. Each run returns an agent ID that you can pass back later to resume the subagent with its context.
Cursor's docs say five parallel subagents use roughly five times the tokens of one agent. On simple tasks, startup overhead can also make them slower than the main agent. Cursor recommends starting with two or three focused subagents. Billing follows the model that actually ran. Some legacy request-based plans force subagents onto Composer whatever the model field says.
What is the Cursor skills marketplace?
There is no marketplace for single skills. The Cursor Marketplace arrived in version 2.5 on February 17, 2026, and it lists plugins. A plugin bundles skills, subagents, MCP servers, hooks and rules into one install. The first partners named in the changelog were Amplitude, AWS, Figma, Linear and Stripe. You install a plugin from the marketplace page or inside the editor with the /add-plugin command.
For your own skills you have two routes, per the skills docs:
- Drop a folder into .cursor/skills/ (project) or ~/.cursor/skills/ (personal). The folder name must match the name field in SKILL.md.
- Package skills in a plugin. You can import a GitHub repository that contains a .cursor-plugin/marketplace.json file, or add the repository as a team marketplace.
A SKILL.md needs a name and a description. Optional fields include paths, which limits the skill to matching files, and disable-model-invocation. Setting that one to true makes the skill behave like a classic slash command that only runs when you call it. Cursor's 2.4 changelog says skills suit "procedural 'how-to' instructions" better than always-on rules.
What still resets between sessions?
All three features are instructions you write ahead of time. None of them records what happened while the agent worked.
Cursor's rules docs are direct about the reason: models do not retain memory between completions, so rules exist to re-insert context every time. A subagent is even more forgetful by design. It starts clean on every run, and its findings flow back only as a final message to the parent. When the chat ends, the bug the Explore subagent traced and the deploy step you corrected twice are gone. The next session finds them again, or you paste them into a rule by hand.
That gap grows with the features. More parallel agents means more discoveries made in contexts that close when the task does. If you also use Claude Code or Codex, each tool keeps its own notes, even though Cursor now reads their subagent and skill folders.
The bottom line
Use subagents for parallel or noisy work such as codebase searches and reviews, and keep them read-only unless they must edit. Write skills for procedures your team repeats and keep them in the repository. Check the plugin marketplace before you write one from scratch. Treat all three as static instructions, and plan separately for what your agents learn along the way.
How do Cursor agents keep what they learned across sessions?
Cursor's rules docs say the model retains nothing between completions, and a subagent's findings die with its context. Lessons from yesterday's session have nowhere to go unless a person copies them into a rule.
memU keeps a shared memory as readable Markdown files that every connected host reads. A scheduled background task slices new session logs into jobs. The agent then distills them into memory and skill Markdown, and memU commits the result. memU itself makes no LLM or chat calls. It stores what the agent prepared and retrieves it by embedding search.
A standing instruction in the host's instruction file, such as AGENTS.md, tells the agent to retrieve before it answers. Supported hosts include Cursor and Claude Code, and all hosts share one backend. So a skill distilled from a Claude Code session is available in Cursor too. Support differs by host and OS, so check the matrix in the memU GitHub repository first.
The hosted version on memu.so is free and syncs across devices. Get an API key there and send your agent one message:
Read https://memu.pro/SKILL.md, follow its instructions to install and configure memU, API Key is
YOUR_MEMU_API_KEY.
FAQ
Where do Cursor subagent files go?
Project subagents go in .cursor/agents/ and personal ones in ~/.cursor/agents/. Cursor also reads .claude/agents/ and .codex/agents/, with .cursor/ taking precedence when names clash.
Can Cursor subagents run in parallel?
Yes. The main agent can launch several subagents in one message, and background subagents keep working while the parent continues. Each one spends its own tokens.
Is there a Cursor skills marketplace?
Not for single skills. The Cursor Marketplace at cursor.com/marketplace lists plugins. A plugin can bundle several skills and subagents with other components. Single skills are added as folders or shared through a team marketplace.
Can Cursor use Claude Code skills and subagents?
Yes. Cursor reads skills from .claude/skills/ and subagents from .claude/agents/, along with the Codex folders, so existing files work without copying.
Do Cursor subagents remember previous runs?
No. Each subagent starts with a clean context. You can resume a specific run by passing its agent ID back, but nothing carries over to new runs automatically.