Home › Rules › Antigravity subagents

Google Antigravity subagents: custom agents, the agents folder and examples

From Google's own Antigravity docs (Custom subagents, the /agents command, Plugins and Customization discovery), checked Nov 7, 2026. Sources below.

• Guide
• Antigravity
• Subagents
• Custom agents
• Beginners

Short answer: yes, Antigravity has subagents, in the Antigravity App and the Antigravity CLI. The main agent starts them with its invoke_subagent tool, and they run in the background at the same time as you keep working. Three come built in (research, browser and self). You can add your own custom agent by writing a Markdown file with YAML frontmatter in .agents/agents/<name>.md (or .agents/agents/<name>/agent.md) for one project, or in ~/.gemini/config/agents/ for every project. name and description are required. In the CLI, /agents shows them all.

What a subagent is (and isn't)

• Fresh start: Google's docs say a subagent "does not inherit the parent's existing conversation history." It only knows the role and the prompt the main agent hands it. So a good description and a clear prompt matter more than with your main chat.
• Runs in parallel: a parent agent can start several subagents at once. Each one keeps going while you type.
• Its own workspace option: a subagent can use the same folder as its parent (inherit), get its own Git worktree (branch), or share directory storage (share).
• Same safety settings: subagents inherit the parent's allowed command prefixes, file read and write scopes, and sandbox settings. If one needs your approval for a tool, the request shows up in the main window or the subagent panel.
• Not a rule or a skill: a rule is guidance the agent always (or sometimes) reads, and a skill is a set of steps the agent loads when the task matches. A subagent is a separate worker with its own prompt, tool list and model.

The built-in subagents

Where custom agent files go

# One project only
mkdir -p .agents/agents/test-runner
# -> write .agents/agents/test-runner/agent.md

# Every project on this computer
mkdir -p ~/.gemini/config/agents/code-reviewer
# -> write ~/.gemini/config/agents/code-reviewer/agent.md

Two things trip people up, per Google's customization-discovery doc and the /agents page:

• Not too deep: Antigravity loads agents/<name>.md and agents/<name>/agent.md, but not files in deeper folders. To load one from somewhere else, list it in an agents.json discovery manifest.
• Not in the config root: a file dropped straight into .agents/ or ~/.gemini/config/ isn't found. It has to be inside an agents/ folder.

Like rules and skills, Antigravity checks the .agents/ folder in your workspace and each parent folder up to the repository root, never subfolders below where you started. Google also still recognizes .agent/, _agents/ and _agent/, but says to use .agents/ for new projects.

The frontmatter fields

Everything after the closing --- is the agent's system prompt. Google's example uses plain Markdown headings like # System Prompt and # Review Guidelines.

Watch the tool names. Google lists a known issue: a misspelled or unknown name in tools "may cause the subagent process to hang." Copy the names exactly. Google says better validation and a fix are planned.

Examples you can copy

The smallest one (from Google's /agents page)

---
name: code-reviewer
description: Rigorous code review specialist focusing on edge cases and security.
---
You are an expert code reviewer. Analyze diffs carefully and verify edge cases.

That's all you need: a name, a description and a prompt. With no tools line it falls back to the defaults in the table above.

A test runner (our example)

This one and the next are examples we wrote for this page, using only fields and tool names from Google's docs. Change the steps to fit your project.

---
name: test-runner
description: Runs the project's tests after a change, reads the failures and reports which files and lines are broken. Use after any code edit.
tools:
  - view_file
  - grep_search
  - run_command
subagent: true
mainAgent: false
model: flash
commandExecutionPolicy: sandbox
---

# System Prompt
You run tests and report results. You do not edit files.

# Steps
1. Find the test command in package.json, pyproject.toml or the README.
2. Run it once.
3. For each failure, give the test name, the file and line, and one sentence on why it failed.
4. If everything passes, say so in one line.

mainAgent: false keeps it out of your chat agent list, so it only runs when the main agent hands it work. model: flash is the lighter tier, which fits a job like reading test output.

A read-only code researcher (our example)

---
name: docs-researcher
description: Read-only helper that finds where something is handled in this codebase (a route, a setting, a database table) and returns file paths with a short summary. Use before planning a change.
tools:
  - view_file
  - grep_search
subagent: true
mainAgent: false
model: inherit
---

# System Prompt
You only read. Never change files and never run commands.

# Output
- A list of the files that matter, each with one line on what it does.
- The exact function or line where the thing is handled.
- Anything that looks risky to change, in plain words.

No run_command and no replace_file_content in tools, so it can look but not change anything. That's a safe first subagent to try. Google's own longer example, a code-auditor with model: pro and a skills list, is on the Custom subagents page.

How to use them

• Let the main agent decide: if subagent: true, the planner reads each description and hands matching work to that agent. Write the description like a job ad: what it does and when to use it.
• Ask for it by name: you can also tell the main agent which one to use, for example "have test-runner check this change."
• Make it your main agent: if mainAgent: true, pick it in the App's agent selector, in the CLI's /agents panel, or start with agy --agent <name>. In the CLI, switching agents in the middle of a chat forks the conversation so you don't lose the old one.
• One-off helpers: the main agent can also make a temporary subagent during a session with its define_subagent tool. Those aren't saved as files.

# Inside an Antigravity CLI session
/agents          # open the Agent Manager panel

# From your shell
agy agents                 # list built-in, workspace and plugin agents
agy --agent code-reviewer  # start a session with that agent

Watch, message and stop them

• App: click a subagent's conversation in the subagent panel to watch it. Type in its message box to give it new instructions directly. Stop Subagent cancels a running one.
• CLI: /agents lists every subagent as running, done, error or killed. Enter opens its full log, K kills a running one (and its children), A or D approves or denies a pending tool request. Alt+J jumps to the next subagent waiting for approval, and Ctrl+K approves the pending action shown above your prompt.
• Message one directly in the CLI: start your prompt with @ and its name, like Google's example @research:API-Key-Header-Researcher Also check the tests.
• After it finishes: a done subagent goes idle and wakes back up, with its old context, when another agent messages it. A killed one can't be woken, and any Git worktree it made is cleaned up.

Google caps nesting at 10 levels of subagents under the main agent.

Subagents vs /boost and /teamwork

Google also has two built-in multi-agent modes. /boost runs a three-level team for hard bugs and tricky refactors inside a normal session; Google lists it for the Pro and Ultra tiers (Google One AI Premium) and Enterprise plans. /teamwork runs a bigger team (a coordinator, explorers, workers, plus reviewers that check each milestone) for large, multi-day projects; it's on paid plans. Custom subagents are the simple version: you write the agent yourself and the main agent uses it when it fits. Plan quotas still apply to everything subagents do, so see Antigravity limits and AI credits before you start a lot of them.

Coming from Claude Code subagents?

The idea is the same: a Markdown file with YAML frontmatter, a description the main agent matches on, and a tool list. The folder and some field names differ (Claude Code uses .claude/agents/). Our Claude Code subagents examples page has 7 copy-paste agents; to reuse one here, move it to .agents/agents/ and change the tool names to Antigravity's.

Agent not showing up or hanging?

• Not listed in /agents: check it's inside an agents/ folder, not deeper than agents/<name>/agent.md, and has both name and description. Reopen /agents after adding it.
• Main agent never uses it: make sure subagent isn't set to false, and make the description say when to use it.
• It hangs: check every name in tools for typos (Google's known issue).
• It keeps asking for approval: that's the parent's permission settings carrying over. See Google's Agent settings page for the permission presets.

Related

• Google Antigravity skills (skills folder, SKILL.md, workflows vs skills)
• Google Antigravity plugins (install, marketplace, plugin vs skill)
• Google Antigravity rules (examples, triggers, where the files go)
• Google Antigravity limits and AI credits (free tier, quotas, AI credits)
• Claude Code subagents examples (7 copy-paste subagents)
• Antigravity vs Claude Code vs Codex (prices, limits, rules files)
• SKILL.md examples for every tool (format, frontmatter, where the folder goes)
• Free rules file generator

Sources

• Google Antigravity docs: Custom subagents
• Google Antigravity docs: Agents command (/agents)
• Google Antigravity docs: Plugins
• Google Antigravity docs: Customization discovery
• Google Antigravity docs: Teamwork (/teamwork)
• Google Antigravity docs: Agent settings

Every folder, field and command here was checked Nov 7, 2026 on Google's own Antigravity docs. Subagents are new and Google is still changing them. If something here no longer matches, tell us at [email protected].