How to Create Cursor Subagents: 5 Practical Examples

A Cursor subagent is a specialized AI agent that the main Cursor Agent can delegate work to. It starts with a clean context window, completes a focused task and returns the result to the parent agent.

If you want to create, configure and trigger custom Cursor subagents, here is the setup—and five practical roles worth trying.

Why Subagents Matter

Context efficiency

Each subagent has its own context window. Research, terminal output and intermediate reasoning stay out of the main conversation.

Time and cost efficiency

Not every task needs your most expensive model. You can route focused work to a faster, cheaper model and reserve the frontier model for decisions that require it.

Parallel execution

Subagents can run in the foreground or background. Independent tasks can run in parallel instead of blocking the entire workflow.

How to Create and Trigger a Custom Subagent in Cursor

Cursor includes three built-in subagents: Explore, Bash and Browser. You can also create your own with a focused prompt, trigger description, model and tool access.

For a project-specific subagent, create an <agent-name>.md file in .cursor/agents/. For a reusable subagent available across all projects, use ~/.cursor/agents/.

Each file contains YAML frontmatter and the agent instructions:

---
name: code-reviewer
description: Reviews completed code for correctness, regressions and missing tests.
---
 
Review the implementation against the requirements. Report concrete issues first,
then list the checks that passed.

Cursor can select the subagent automatically from its description. You can also invoke it explicitly with /code-reviewer or ask the main agent to use it in natural language.

Here are five subagents I started creating for my own workflow:

🧑‍🔬 Researcher

Need information about a framework, library or SDK? Delegate the research and ask for a result in a predictable format. The subagent can compare alternatives and explain their tradeoffs without filling the main context with search output.

🔎 Code Reviewer

Before starting your own code review, let a subagent perform the first pass. Give it your review checklist, ask questions about unfamiliar code or have it review your changes before you publish them.

🍃 Git Master

Use it to generate branch names and commit messages, investigate file history, explain a suspicious line or help resolve merge conflicts. Think of it as Git blame with context.

🐀 Repositories Spy

If your application is split across repositories, let a faster and cheaper model retrieve the necessary information or code snippets and return a compact summary to the main conversation.

📂 File analyzer

Create a separate subagent for PDFs, Google Sheets or CSV files. It can return either an LLM-ready summary or a human-readable report while keeping noisy source data in a separate context window.

Start Small

Start with two or three roles that remove real bottlenecks from your workflow. Give each one a narrow responsibility, a clear output format and an explicit definition of done.

If cost efficiency is the goal, combine subagents with deliberate model routing. I describe that workflow in The Best AI Developers Won’t Write the Best Prompts. They’ll Optimize Cost per Task.

For the broader tool decision, see my 5,000-hour comparison of Cursor, Codex and Claude Code.

Official Docs

Cursor Subagents documentation

About the Author

Yaroslav Dobroskok is an AI for coding expert who has trained 900+ developers across 25+ companies on integrating AI tools into their development workflows. A GitHub Copilot beta tester and Udemy instructor, he helps development teams achieve 25-37% velocity improvements through structured AI adoption.

Connect on LinkedIn: https://www.linkedin.com/in/yardobr/