Writing a subagent brief that returns data, not prose

In Claude Code

On 2.1.193 we've discovered that no registration is actually needed — we created .claude/agents/scout.md and it appeared in the list on the next run of the app. The same works at ~/.claude/agents/ for the ones you want everywhere, and both are scanned recursively. But within an already running session only the directories that were there at start are watched for changes: the watcher "covers only directories that existed when the session started, so the first file in a new directory needs a session restart", and according to the docs this is the most frequent reason why people can't find their agent.

The only mandatory fields in an agent file are name and description. tools defines what a particular agent can access, and model can be one of sonnet, opus, haiku, fable, a full model ID, or inherit.

The main challenge is where to put the output contract, and it's bound by a single limitation — @agent-scout pins which subagent gets run, but it doesn't carry your message to it: "Your full message still goes to Claude, which writes the subagent's task prompt based on what you asked. The @-mention controls which subagent Claude invokes, not what prompt it receives." So it's the parent that relays your request, rewritten. Anything non-negotiable — the locator rule, the empty result's shape, no prose — goes into the agent file's system prompt, which arrives unaltered.

Another thing is there's no place to define the output schema at all. There are 16 fields available in frontmatter and none of them is connected with the return type — tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color and initialPrompt, alongside the two required ones. Which means the only way to describe it is prose, so you need to provide the contract in the task.

Finally, with 2.1.210 there's been a change: the subagent's final message is examined before reaching the parent agent. During this examination the scan "never removes or rewords anything", but it might prepend a line starting with [harness: subagent output matched instruction-shaped pattern(s): and it inserts a backslash if it finds something that looks like a system reminder or a line starting with Human:. So as long as it works like this — the best practice is to parse the JSON from within the subagent's reply, rather than treating the entire thing as JSON.

In Codex CLI

It's not only that the format of an agent definition is different (TOML instead of Markdown) and lives under ~/.codex/agents/ or .codex/agents/ for personal and repo scope respectively — it's also the way these files are used by the engine. Codex "loads these files as configuration layers for spawned sessions", and the official documentation acknowledges this "can feel heavier than a dedicated agent manifest".

For such a TOML file to be recognised as an agent definition, it needs 3 keys:

• name

• description

• developer_instructions

That being said, here's how the aforementioned scout looks like as a Codex TOML definition:

name = "scout"
description = "Read-only investigator. Returns structured findings with file:line locators and never edits anything."
sandbox_mode = "read-only"
developer_instructions = """
You are a scout. You investigate and report. Your caller is a program, not a person.
Return only a JSON object matching the schema the request gives you, with no preamble.

1. Every claim carries a `file` and a `line` the caller can open. No locator, no claim.
2. Found nothing? Return the empty result the schema defines, not a sentence about having looked.
3. Ran out of budget? Return what you have, and set `"complete": false`.
4. Paths are relative to the repository root.
"""

The name is what's actually used as the spawn identifier, so it doesn't matter what you call your file. If you reuse the name of a built-in one — default, worker or explorer — yours takes precedence over Codex's.

This can be initiated by a standard natural language request like "spawn two agents", "delegate this work in parallel" or "use one agent per point", but also from an AGENTS.md file or a skill's instruction. Remember that the /agent command doesn't actually create anything, it only changes which agent thread is being shown.

Subagent workflows ship enabled: "Current Codex releases enable subagent workflows by default", and agents.enabled defaults to true, so you don't need to do anything for this to work.

However, the output channel is a bit thinner than the documentation suggests. It says "The main thread collects the subagent results into its final response" — but if you take a look at the 0.146.0 source, a completed agent status is built from exactly one thing, the turn's last_agent_message. No transcript, no tool output, no structured payload, which means everything that's not in that last message is lost.

The best practice recommended by OpenAI is to "Return summaries from subagents instead of raw intermediate output", and that "A good subagent prompt should explain how to divide the work, whether Codex should wait for all agents before continuing, and what summary or output to return." With that in mind, take the "output" part literally and define the schema there.

Also remember that setting sandbox_mode to read-only in the TOML doesn't mean it's actually read-only in the subagent session. Codex "reapplies the parent turn's live runtime overrides when it spawns a child ... even if the selected custom agent file sets different defaults" — so if you change a permission interactively in the parent, the subagent inherits it. Read-only in the file is a default, not a guarantee.

In Cursor

The definition of agents lives in the .cursor/agents/ directory at the repository level, or at ~/.cursor/agents/ for user-level ones. The Claude and Codex directories are also checked (.claude/agents/ and .codex/agents/) in both places, with priority to .cursor/ on name collisions — so a file you already keep in the Claude layout gets found here as is.

Found, not converted. There are 5 frontmatter fields, all optional:

• name

• description

• model — either inherit or a concrete ID like composer-2

• readonly

• is_background

There's no tools field. "Subagents inherit all tools from the parent, including MCP tools from configured servers", and the only limitation is readonly: true, which "runs with restricted write permissions (no file edits, no state-changing shell commands)".

So for the artifact below to mean anything here you need to swap its head — remove tools, remove model: haiku, and keep the body as-is:

---
name: scout
description: Read-only investigator. Returns structured findings with file:line locators and never edits anything.
model: inherit
readonly: true
---

It's all about a single boolean whereas elsewhere people use a tool list to achieve it.

To invoke it you type a slash, not an at-sign: /scout find every call to the payments API without a timeout.

Cursor's own docs are even saying that hooks are the sensible place for this: "If you need subagents to produce structured output files, consider using hooks to process and save their results consistently." The subagentStop hook provides summary and also agent_transcript_path — "Path to the subagent's own transcript file (separate from the parent conversation)" — so if needed you can read the subagent's output as-is instead of the parent's paraphrase.

This works in the CLI too, it's not an editor-only feature. The March 2026 CLI release put it as "Parallel agents execute locally with live status in interactive, headless, and editor sessions, inheriting your credentials, rules, and approval policy"… but there's no CLI flag for it, you drive it from the prompt.

In Antigravity CLI

You can define per-workspace agents under .agents/agents/<name>.md or .agents/agents/<name>/agent.md, and machine-wide ones under ~/.gemini/config/agents/. The parent starts a subagent using the invoke_subagent tool, and a file qualifies while its frontmatter subagent flag is true — which is the default, so you only ever write it to turn delegation off.

The frontmatter can contain:

• name (required)

• description (required)

• tools — an array of Antigravity's native tool names, like view_file, grep_search, run_command

• model — inherit, flash, pro

• commandExecutionPolicy — sandbox unless defined

• mainAgent: false — hides the agent from the primary-agent picker

Important — tool names must be identical, the docs say "specifying an unmapped or misspelled tool name in the tools list may cause the subagent process to hang during execution."

To see which agents were loaded run agy agents; if it comes back empty on a machine without any agent files, that's how you know you put your file in the wrong place. Inside a session the /agents panel gives you the same view, and opening a subagent there reveals "the subagent's entire reasoning log, including its private internal thoughts, tool calls, and execution outputs."

What Antigravity does differently compared to other systems is that after the subagent completes its task it goes into idle instead of disappearing — it "has completed its task, sent a result message to its parent agent, and paused execution" — so if another agent sends it a message it resumes, keeping the context. There's more too: agents can "read each other's conversation transcripts", and even after a subagent is killed "historical conversation transcripts remain readable in JSONL logs". These transcripts persist here unlike anywhere else, so the natural instinct is to go and look. Try not to. By reading the transcript you're spending the very context you wanted to preserve by using a subagent, and the point of the contract is that the answer arrives already checkable.

In Kimi Code CLI

Agent files are discovered in a few places:

• .kimi-code/agents/ (or .agents/agents/) at the project level

• ~/.kimi-code/agents/ (or ~/.agents/agents/) for the user

Subdirectories are scanned too, and if the same agent is defined in both places, the project one wins. --agent-file <path> outranks all the other sources, but only for a single launch.

Only description is mandatory; if not specified, name defaults to the name of the file. tools accepts either a YAML list or a single comma-separated string, disallowedTools is evaluated after tools, and subagents limits which types this agent can delegate to in turn. Any other keys are ignored — so "a minimal file with description and a body works across tools", which means an agent file written for another harness loads here unchanged.

Moonshot is the one vendor that tells you to write the return contract into the agent body: "Custom agents delegated as sub-agents run without the built-in sub-agent framing ('your final message is the entire handoff'). If you write an agent meant for delegation, state in the body that its last message should be the complete, self-contained result for the caller." A custom agent here doesn't inherit the built-in reminder that its last message is all the caller gets. Leave that out and it'll behave like it's in the middle of a chat.

Dispatch happens on its own — "sub-agents are scheduled automatically by the main Agent" — and each dispatch is presented as an approval request showing the task description, which is a free preview of the brief the parent actually wrote. But only if you haven't allowed it away: the Agent tool is auto-allow by default, "enabling the main Agent to delegate multiple times without interrupting the user", so out of the box you never see that prompt.

If you were to use AgentSwarm, the cost of a bad schema increases significantly. You define a single prompt_template with an {{item}} placeholder and an array of items; for each item a subagent is created (maximum 128) and the tool "waits for all subagents to finish, and returns an aggregated report". /swarm <task> turns on the mode that auto-approves it. So if you get the return type wrong here, you get it wrong 128 times, concurrently, and you pay for each one.