Google Antigravity adds file-based custom agents

Google Antigravity has introduced Custom Agents, file-based agent definitions designed for specialized roles and repeatable team workflows.

Markdown files define the agent

A custom agent is a single Markdown file with a YAML frontmatter header. The frontmatter can specify the agent’s name, description, model, tools, permissions, relevant skills, MCP servers, hooks, and other parts of the agent loop. The Markdown body becomes the agent’s system prompt.

Project-local agents live under .agents/agents/. User-global agents live under ~/.gemini/config/agents/. Because project agents are ordinary files, a team can commit them to a repository so teammates receive the same workflow assistant when they check out the project.

Main-agent and subagent roles

Antigravity supports execution symmetry for custom agents. A definition can be marked with mainAgent: true so it can be selected directly in the Antigravity 2.0 GUI or launched from the CLI, for example with:

agy --agent dependency-modernizer

The same definition can be marked with subagent: true so a coordinator agent can call it as a specialized worker. This gives teams a way to keep a stable role’s model, tools, permissions, and instructions in version control while still using it either directly or inside a larger agent workflow.

Command-execution policies and hooks

Custom agents can use permission modes such as acceptEdits and bypassPermissions, plus a command-execution policy. With commandExecutionPolicy: auto, standard test and compilation commands can run autonomously in the background, while higher-risk actions such as deleting files remain gated for manual approval.

The custom-agent format also supports lifecycle hooks. A PreInvocation hook can prepare the environment before the agent starts, while a PreToolUse hook can run a verification script when the agent is about to call a selected tool such as run_command.

Availability and relationship to skills

Google says Custom Agents have first-class support in Antigravity 2.0 and the Antigravity CLI, with IDE support described as coming shortly. Custom Agents do not replace skills or dynamic subagents: skills add progressive, task-specific context, while dynamic subagents let a main agent delegate with a prompt. A Custom Agent adds a reusable specialization with its own model, permissions, tools, and supporting integrations.

Why this matters for teams

The practical shift is from one-off prompts to versioned agent roles. A team can define a dependency upgrader, test verifier, release assistant, or security reviewer once, review the Markdown in code review, and make that same configuration available to every teammate and to other agents that call it.

Sources

• Antigravity — “Introducing Custom Agents”: https://antigravity.google/blog/introducing-custom-agents
• Google Antigravity on X — official announcement (August 12, 2026): https://x.com/antigravity/status/2087611597896224961
• Google Antigravity — official account: https://x.com/antigravity