Custom agents turn a general coding assistant into a specialist you define yourself. With the release of Antigravity 2.0 and the Antigravity CLI, Google now gives custom agents first class support, and the Antigravity IDE will follow shortly. A custom agent is a single Markdown file that packages a role, its instructions, its tools and its constraints, so you can spin up a predictable partner for a recurring task in seconds. This post walks through what custom agents are, how they relate to skills and dynamic subagents, and which capabilities are unique to Antigravity.
Why general assistants fall short
General purpose coding assistants are strong generalists, and they run into two structural limits on real projects.
The first limit is a lack of specialization. A general assistant does not know your project’s testing conventions or dependency management rules unless you explain them every single time. That repetition slows you down and invites inconsistency across sessions.
The second limit is context window bloat. Loading one massive prompt with all your coding guidelines, linters and testing rules into every chat turns into a token budget disaster. You pay for tokens you rarely need, and the instructions that matter compete for attention with the ones that do not.
Custom agents solve both problems. They are specialized configurations stored as files, and each one defines a particular role with its own scoped instructions, tools and constraints. Your active context stays clean, token overhead stays low and you get a predictable partner for a specific task. They also enable a real division of labor, since you can break a complex project down into specialized agents that act, verify and run tasks in parallel.
How custom agents fit next to skills and subagents
If you already use skills and dynamic subagents, you might wonder what custom agents add. The short answer is another level of optimization on top of both.
Skills specialize an agent with extra context and instructions, and their progressive discovery keeps the full skill text out of your prompt until the agent decides the work at hand requires it. That helps, and the model still has to read the descriptions of every skill you might ever need. Across all tasks in a real project, that list grows large and the descriptions alone consume serious context. A custom agent lets you declare the subset of skills that is actually relevant for its specialization. The same applies to MCP servers, hooks and every other customization point. On top of that, you can customize the system instruction, the default tools and other core parts of the agent loop.
Dynamic subagents, introduced a few months earlier, let the main agent delegate work so its own context stays clean. The dynamic part is that the main agent writes the prompt it sends down to the subagent. Custom agents take this further. A coordinator can now delegate to a named agent with its own specializations, plus details like its model and its permissions.
One Markdown file per agent
Setting up a custom agent takes a single Markdown file with a YAML frontmatter header, the same convention Antigravity uses for skills. The frontmatter tells the product how to run the agent, and the Markdown body compiles directly into its system prompt. The documentation lists every field that can appear in the frontmatter.
You save agent files in your local workspace under.agents/agents/ or globally for your user account under ~/.gemini/config/agents/. Because the format supports progressive discovery, the agent’s description stays visible to the system while its full instructions load only when needed.
The workspace location has a quiet advantage. Commit the agents that belong to a project to the repository, and every teammate who checks out the code gets the same standardized workflow assistants with zero manual setup. Your review agent, your migration agent and your test agent become part of the project itself.
A minimal agent looks something like this.
--- name: dependency-modernizer description: Modernizes outdated dependencies and verifies the build commandExecutionPolicy: auto --- You are a dependency modernization specialist. Update outdated packages, run the test suite after each change and report any breaking changes.
The moment the file exists in the right folder, the agent is available in the product.
What makes Antigravity custom agents different
If you have used other tools in this space, the Markdown plus frontmatter layout will look familiar. Google deliberately aligned its file conventions so that porting your existing agents takes minimal effort. The real differences live under the hood, in how the agents run.
Symmetry between main agent and subagent
In other tools, custom agents are restricted to subagent duty. You talk to the default main agent, and it decides behind the scenes when to spawn your specialist based on the frontmatter descriptions. You cannot start a primary session directly as your custom agent.
Antigravity introduces execution symmetry through simple configuration flags. You can select an agent like dependency-modernizer straight from the dropdown in the Antigravity 2.0 interface, or launch it through the CLI with agy –agent dependency-modernizer. Its core instructions compile directly into the system prompt, you adopt all execution parameters from the frontmatter and you talk to your specialist directly. The very same agent remains available as a subagent that a coordinator delegates work to. One definition, two ways to run it.
Scoped safety policies
Agents that execute command line operations, like dependency installs or test suites, create a real tension. A safety policy that is too loose risks running unverified code. A policy that is too strict traps you in a loop of constant approval prompts.
Antigravity supports the familiar all or nothing permission levels such as acceptEdits and bypassPermissions, and adds a dedicated execution filter on top. With commandExecutionPolicy set to auto, the agent runs standard test and compilation commands autonomously in the background. High risk commands, like deleting files, stay strictly gated behind manual approval. A dependency modernizer can iterate through rapid trial and error cycles without pinging you every thirty seconds, while the genuinely dangerous actions still require your explicit yes.
Nested lifecycle hooks
Other tools support basic lifecycle hooks scoped to the subagent. Antigravity defines a richer, nested hooks schema directly in the agent definition, with interception points at precise execution boundaries.
A PreInvocation hook runs a setup script that prepares the environment before the agent starts thinking at all. A PreToolUse hook with matchers intercepts specific tool calls. For the modernizer, every terminal command can trigger a verification script first, confirming the local environment is sound before anything executes. The documentation describes several more hook locations.
This granular control stops the agent from making assumptions about the machine it runs on. Many compilation loops simply never start, because the environment check fails fast and the agent adjusts its plan instead of grinding through broken builds.
Four agents worth defining first
The dependency modernizer from Google’s announcement is a strong template, and the pattern extends to almost any recurring job.
- A test runner that knows your framework, your naming conventions and the commands that matter, with commandExecutionPolicy set to auto so it can iterate freely.
- A reviewer that holds your style guide and security checklist, called as a subagent by your coordinator before code lands.
- A documentation writer that turns code changes into changelog entries in your team’s tone of voice.
- A migration specialist that carries the step plan for an upgrade, with a PreInvocation hook that snapshots the environment first.
Each of these starts as a few lines of frontmatter and a focused system prompt, and each one removes a category of repetitive explanation from your day.
Treat your agents like code
The deeper shift here is that agent behavior becomes versioned infrastructure. An agent file sits in your repository, evolves through pull requests and carries the review history of every convention your team has agreed on. When a testing rule changes, you update one file and every teammate’s assistant changes with it. That is a fundamentally different model from tweaking a personal prompt until it behaves. Start with one narrow, repeatable task, define it in.agents/agents/ and let the Custom Agents Guide in the Antigravity documentation walk you through the full set of frontmatter fields.
