Subagents are a config object now, not a trick

In Claude Code

Subagents are defined in .claude/agents at project level and ~/.claude/agents at user level — Markdown files with YAML frontmatter, body is used as system prompt; name and description fields are mandatory:

---
name: schema-reviewer
description: Reviews database migrations for destructive changes. Use proactively when a migration file is added or changed.
tools: Read, Grep, Glob
model: haiku
---

You review database migrations for destructive changes.

It finds subagent definitions recursively so it works with nested subfolders too; what's more it uses the name field to identify a subagent, not the location of the file. What's more, when you run it from a project it finds every .claude/agents folder up the directory tree from cwd to the project root.

So when it comes to priority, these are the levels in descending order:

• Managed settings

• --agents CLI flag

• .claude/agents

• ~/.claude/agents

• Plugins' agents directory

If there's a subagent defined at a higher-priority level, that one is used; so a project-level subagent beats a personal one. The thing is that if you have two files with the same name in the same directory tree it's not supported, because as the docs say, only one is loaded and which one depends on which order they are read by the filesystem.

The frontmatter supports multiple fields, here are the most valuable ones:

• tools / disallowedTools — to limit the toolset; disallowedTools are checked first and then the rest is resolved using tools

• model (defaults to inherit)

• permissionMode

• maxTurns — a hard cap

• skills — to load the entire skills' bodies

• isolation: worktree — to use a separate repo copy per run

The parent process passes the subagent to it using the Agent tool, which was called Task before 2.1.63 (and is still accessible via Task(...) alias). You can also address it by typing @ and selecting it or by using --agent <name> to run an entire session as this subagent or --agents '<json>' to set up a one-off for a single session.

It's important to be mindful that the behaviour of subagents might differ depending on what version you use:

• At 2.1.198 they removed the /agents wizard, so running it will display a message saying to define it in .claude/agents; and also made subagents run in the background by default

• That's why from now on they use all MCP tools but only a small subset of the built-ins (the docs say that the rest is stripped regardless if inherited or listed in tools, so you can end up with a different toolset for a subagent if you run it in foreground vs background)

• It also means that listing a tool in tools doesn't mean it's available

• But for 2.1.193 (which we used to test it), the /agents wizard was still there and the background-by-default change was in progress, so two people running the same definition a fortnight apart can end up with different toolsets

The conclusion is that if you find a subagent doesn't have a particular tool, check if it ran in the background before changing the definition.

In Codex CLI

The only exception from the above is Codex — agent definitions in TOML files rather than Markdown files. They are located at either ~/.codex/agents/ or .codex/agents/ depending on what level you define it on (user or repo) and there's only one agent per file like this:

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
"""

There are three mandatory keys:

• name — used to identify the agent, filename doesn't matter

• description — for a little bit of context

• developer_instructions — contains the system prompt instead of the markdown body like in other agents

You can define all the keys that you could define in config.toml file for the config, so anything like:

• model

• model_reasoning_effort

• sandbox_mode

• mcp_servers

• skills.config

It's a configuration layer rather than a purpose-built manifest, and OpenAI say so themselves — that "the format may evolve".

There are three built-ins — default, worker and explorer which come preinstalled, if you create your own agent with the same name it will replace the built-in.

Instead of a single call to the agent there are five different tools:

• spawn_agent

• send_input

• resume_agent

• wait_agent

• close_agent

This is behind the features.multi_agent flag which is stable and enabled by default, so you can just look at this list and understand what the model is — that a subagent is a long-running thread that you open and can feed input to, wait for and close. /agent and /subagents are not changing anything in this regard they just change which thread is in focus, they're not opening new ones.

To create a subagent you can just ask it in the prompt like:

• Create two agents for me

• Can we do it in parallel? etc

There's also an [agents] section in config.toml where you can define things like:

• enabled — whether to enable the feature at all

• max_concurrent_threads_per_session — how many threads a single session (an instance of codex) can run simultaneously

• default_subagent_model

• default_subagent_reasoning_effort

There are two common pitfalls:

• The read-only sandbox_mode is just a default, Codex "reapplies the parent turn's live runtime overrides when it spawns a child" (including the possibly interactively-granted approval and sandbox settings) so if you relax your session the subagent will no longer be read-only

• There's no tool allowlist per agent, it's done by setting sandbox_mode, choosing MCP servers to connect to or disabling skills. There's also no worktree per agent, which is why the docs push you toward read-heavy fan-out and warn to "Be more careful with parallel write-heavy workflows, because agents editing code at once can create conflicts and increase coordination overhead"

In Cursor

Definitions live in the following places in Cursor:

• per project: .cursor/agents/

• per user: ~/.cursor/agents/

They're Markdown files with YAML frontmatter.

Compatibility note: Cursor also reads the folders of other vendors (Claude and Codex) at both scopes:

• per project: .claude/agents/, .codex/agents/

• per user: ~/.claude/agents/, ~/.codex/agents/

If you have a duplicate name, files from .cursor/ will have the higher priority.

Here's an example of a definition file (for a verification subagent), which contains frontmatter and instructions for the LLM to check a change:

---
name: verifier
description: Confirms a change actually works before it is called done. Use after an implementation pass.
readonly: true
---

You verify claims about a change. Run the tests, read the diff, and report what you could not confirm.

All fields in the frontmatter are optional:

• name — the name of the subagent, used when calling it

• description — a description of the subagent, visible in the IDE and the CLI

• model — the model the subagent should use (see below)

• readonly — if set to true, the subagent runs "with restricted write permissions (no file edits, no state-changing shell commands)"

• is_background — if set to true, the subagent is ran asynchronously in the background (see more in the history section below). If false — it's run synchronously

That readonly boolean is the whole tool-restriction story here — there's no allowlist per agent. Otherwise "subagents inherit all tools from the parent, including MCP tools from configured servers".

You can use bracketed parameters in the model field too, for example claude-opus-5 with the effort level set to high and the context size to 300k

model: claude-opus-5[effort=high,context=300k]

You can call the subagent by asking it about sth in natural language, or by calling it using / and its name inside the prompt:

> /verifier confirm the auth flow is complete

The feature's history:

• Implemented in Cursor 2.4 (22nd of January 2026)

• Asynchronous execution was introduced in 2.5 (17th of February 2026) — before that "all subagents ran synchronously, blocking the parent agent until they complete"

• That's why is_background is a newer thing

The docs say "You can use subagents in the editor, CLI, and Cloud Agents", but if you run cursor-agent --help on the build we checked (2026.07.23-e383d2b) there's no parameter or subcommand about it. Probably because there's nothing to pass — it's config-driven, so the files are the whole interface. We couldn't confirm that locally: a headless run in an empty directory stops on a "trust this workspace" prompt that only --trust, --yolo or -f clears, and we didn't want to hand an agent a trust flag just to check how the docs behave. So treat CLI pickup as documented but unverified.

In Antigravity CLI

Definitions are Markdown files with YAML frontmatter, so the structure can look like this:

• .agents/agents/<name>.md

• .agents/agents/<name>/agent.md

The thing is that the global agents folder is in ~/.gemini/config/agents/ (not in ~/.agents/ as one might think) and there's also a possibility that some of plugins come with their own agents located under plugins/<plugin_name>/agents/. So a definition could look like this:

---
name: schema-reviewer
description: Reviews database migrations for destructive changes. Delegate when a migration file changes.
tools:
  - view_file
  - grep_search
model: flash
subagent: true
mainAgent: false
---

You review database migrations for destructive changes.

As said, the most crucial part is the frontmatter with the name and description, then the rest is up to you. But there's a few things that are worth mentioning:

• The two booleans — subagent and mainAgent — the first one tells Antigravity that the agent can be delegated to (so the primary agent may use invoke_subagent to pass some of the work to it) and the latter is about you being able to choose this agent as a primary one. Other harnesses can express both of those, they just do it elsewhere — through permission rules, or through a flag you pass when you start the session. Antigravity is the one that puts the toggles in the definition file itself, and they're independent, so an agent can be delegate-only.

• The model is a tier — inherit, flash or pro — defining what kind of model this agent has.

• commandExecutionPolicy is a setting that defines how Antigravity should run the shell for each agent — off, auto, eager or sandbox.

• A subagent can have its own git worktree, instead of using the primary agent's directory.

The maximum depth of delegation is 10 levels.

You can set a primary agent by running the headless command with a flag like this:

agy -p "Review this function for edge cases." --agent schema-reviewer

When it comes to potential problems, we've found two:

• There's an open issue on Google's side — it's in their known issues list with a fix promised in a later release: "Specifying an unmapped or misspelled tool name in the tools list may cause the subagent process to hang during execution." It won't throw an error, so the only thing you can do about it is not typing tool names but pasting them.

• We've found this one — we had this setup in our test workspace: both supported layouts and added a definition in each of them, then ran agy agents and it returned no results; it was on version 1.1.9, later we updated to 1.1.10 (the CLI updated itself during the session) and still — nothing. What's more, we've also checked if there are any built-in agents and research, browser and self were missing as well so we assume that on these versions it returns sth else than agents that can be found by the CLI. We weren't able to find a solution.

So even if you run agy agents and it returns no results, don't panic — just try selecting the agent.

In Kimi Code CLI

This tool uses Markdown files with YAML frontmatter for definitions. This is also the tool that has the most number of places from which it will look for agents (directories). If the project has .kimi-code/agents/ or .agents/agents/ in it, it will be used. Or you can point to this directory from your home with the KIMI_CODE_HOME environment variable ($KIMI_CODE_HOME/agents/), by default it's ~/.kimi-code/agents/ and also ~/.agents/agents/. There are two paths under the home dir on purpose — the Kimi-specific one moves with KIMI_CODE_HOME, while the generic ~/.agents/agents/ "stays under the real OS home so it can be shared across tools". If you set the --agent-file option explicitly, then this file will be used. If there's no --agent-file specified, the project-level directory will be used, then these additional dirs, then the user-level dir, then the plugin-level dir, and finally the built-in dir.

But let's see an example of a definition:

---
name: schema-reviewer
description: Reviews database migrations for destructive changes.
whenToUse: When a migration file is added or changed.
tools:
  - Read
  - Grep
disallowedTools:
  - Bash
---

You review database migrations for destructive changes.

And then the body of the Markdown file. As you can see, we need to provide only description of an agent, everything else is optional. In terms of tool selection this tool is the most granular, if we were to compare it with the other tools. It uses two arrays: tools and disallowedTools. The first one works as an allow-list, for example you can list all the MCP tools in a glob notation like mcp__github__*, then the agent will be using only these tools. The disallowedTools array is being evaluated after the allow-list and it's used to omit some of the tools that are allowed but you don't want the agent to use. If you set the tools array to an empty one, it won't be using any tool. If you set it to *, it will use every tool. It also supports using multiple models — if you set the KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL=1 environment variable, you'll be able to choose between primary and secondary models with the model_preference property.

And here are the built-in agents:

• coder

• explore

• plan

The best part of this tool is that every sub-agent gets "a fully independent context window".

It also ignores any properties it doesn't recognise from other tools, for example if you were to use Kimi Code CLI with a Claude Code file, the model property will be just ignored.

One thing that looks like the mechanism and isn't. Just want to clarify one thing — /swarm is not about defining agents. It's a flag that pre-approves using of the AgentSwarm tool which is used for running an array of items across a single prompt template. It can be used to run up to 128 subagents, waits for them to all finish, and then returns one report. This is a useful feature but it's not about defining agents. For ordinary delegation you use the Agent tool; for defining agents you create files as described above.

Verification caveat. Just wanted to say that we haven't actually used any of these things, we were just analysing the docs from Moonshot which are for Kimi Code CLI 0.31.1. The thing is that we have a different version of Python's kimi-cli installed on our machine — 1.48.0 — which is a separate program and its docs say it's retired in favour of Kimi Code CLI, so the folder structure is different.