Antigravity Customization System Guide
The Antigravity Customization System allows you to tailor the agent's behavior,
teach it new workflows, enforce guidelines, and integrate it with external
tools. By customizing the agent, you can transition it from a general-purpose
assistant to an expert pair programmer specialized in your project's codebase
and processes.
Customization Types: Quick Reference
Choose the right customization type based on your goal:
| Type |
Config File/Folder |
Scope |
Best For |
Learn More |
| Rules |
GEMINI.md, AGENTS.md |
Contextual / Hierarchical |
Enforcing coding styles, API restrictions, and local guidelines. |
Rules Guide |
| Skills |
skills/<name>/SKILL.md |
On-Demand (Progressive) |
Teaching the agent multi-step procedures, runbooks, and tool workflows. |
Skills Guide |
| Plugins |
plugins/<name>/plugin.json |
Bundle |
Packaging related skills, rules, and MCP configs into a single unit. |
Plugins Guide |
| Hooks |
hooks.json |
Lifecycle Event |
Running scripts/commands at specific agent lifecycle points (e.g., pre-tool execution). |
Hooks Guide |
| MCP Servers |
mcp_config.json |
Tool Integration |
Connecting the agent to external services and custom tool providers. |
MCP Guide |
Customization Discovery and Locations
Antigravity automatically discovers customizations by traversing specific
directories.
Discovery Locations
- Workspace Customizations (Project-Specific):
- Path:
.agents/ (or .agent/, _agents/, _agent/) at the root of
your project.
- Use this to share customizations with your team by checking them into
version control (VCS).
- The agent walks from your current working directory up to the repository
root (e.g., the folder containing
.git) to find these directories.
- Directory & Project Rules (Hierarchical):
- Paths:
GEMINI.md, AGENTS.md, .agents/rules/*.md
- As you open or edit files, the agent walks up from the file's directory
to the repository root, loading all rules it finds.
- Global Configuration (Machine-Local):
- Path:
~/.gemini/config/
- Applies to all projects and workspaces run on your machine.
Loading Priority and Precedence
When multiple customizations are discovered, they are loaded and applied in a
specific order. If there are naming conflicts (e.g., two skills with the same
name), the higher-priority customization overrides the lower-priority one.
The priority order (from highest to lowest) is:
- Workspace Project: Hierarchical discovery walking up from the CWD to the
repository root.
- Declared Configurations: Customizations explicitly listed in
skills.json or plugins.json in your workspace.
- Global Discovery:
~/.gemini/config/
- Built-in Customizations: Default skills bundled with the application.
- Global Declared Configurations: Explicitly listed in global JSON
configs.
How Customizations are Applied
Progressive Disclosure (Skills and Rules)
To prevent overwhelming the model's context window, Antigravity uses
progressive disclosure:
- Skills are not loaded into the context window by default. Only their
names and descriptions are injected. The full content of a skill is only
loaded if the model (or the user) explicitly decides to activate it.
- Rules with
trigger: model_decision behave similarly. Only always_on
rules are loaded unconditionally.
Deduplication
All customizations (especially rules) are deduplicated by their resolved file
paths. A rule file will never be injected more than once in a single
conversation turn, even if it matches multiple trigger conditions.
Advanced Management: JSON Configs
For customizations stored in non-standard locations, you can use skills.json
and plugins.json to explicitly register them and inherit from shared
configurations.
1---2name: agy-customizations3description: Comprehensive guide and reference for the Antigravity Customization System. Use to explain how customizations work, their loading priority, discovery mechanisms, and to guide the creation of skills, rules, plugins, hooks, and MCP servers.4---56# Antigravity Customization System Guide78The Antigravity Customization System allows you to tailor the agent's behavior,9teach it new workflows, enforce guidelines, and integrate it with external10tools. By customizing the agent, you can transition it from a general-purpose11assistant to an expert pair programmer specialized in your project's codebase12and processes.1314--------------------------------------------------------------------------------1516## Customization Types: Quick Reference1718Choose the right customization type based on your goal:1920Type | Config File/Folder | Scope | Best For | Learn More21:-------------- | :--------------------------- | :------------------------ | :-------------------------------------------------------------------------------------- | :---------22**Rules** | `GEMINI.md`, `AGENTS.md` | Contextual / Hierarchical | Enforcing coding styles, API restrictions, and local guidelines. | [Rules Guide](./docs/rules.md)23**Skills** | `skills/<name>/SKILL.md` | On-Demand (Progressive) | Teaching the agent multi-step procedures, runbooks, and tool workflows. | [Skills Guide](./docs/skills.md)24**Plugins** | `plugins/<name>/plugin.json` | Bundle | Packaging related skills, rules, and MCP configs into a single unit. | [Plugins Guide](./docs/plugins.md)25**Hooks** | `hooks.json` | Lifecycle Event | Running scripts/commands at specific agent lifecycle points (e.g., pre-tool execution). | [Hooks Guide](./docs/hooks.md)26**MCP Servers** | `mcp_config.json` | Tool Integration | Connecting the agent to external services and custom tool providers. | [MCP Guide](./docs/mcp_servers.md)2728--------------------------------------------------------------------------------2930## Customization Discovery and Locations3132Antigravity automatically discovers customizations by traversing specific33directories.3435### Discovery Locations36371. **Workspace Customizations** (Project-Specific):38 * Path: `.agents/` (or `.agent/`, `_agents/`, `_agent/`) at the root of39 your project.40 * Use this to share customizations with your team by checking them into41 version control (VCS).42 * The agent walks from your current working directory up to the repository43 root (e.g., the folder containing `.git`) to find these directories.442. **Directory & Project Rules** (Hierarchical):45 * Paths: `GEMINI.md`, `AGENTS.md`, `.agents/rules/*.md`46 * As you open or edit files, the agent walks up from the file's directory47 to the repository root, loading all rules it finds.483. **Global Configuration** (Machine-Local):49 * Path: `~/.gemini/config/`50 * Applies to all projects and workspaces run on your machine.5152--------------------------------------------------------------------------------5354## Loading Priority and Precedence5556When multiple customizations are discovered, they are loaded and applied in a57specific order. If there are naming conflicts (e.g., two skills with the same58name), the higher-priority customization overrides the lower-priority one.5960The priority order (from highest to lowest) is:61621. **Workspace Project**: Hierarchical discovery walking up from the CWD to the63 repository root.642. **Declared Configurations**: Customizations explicitly listed in65 `skills.json` or `plugins.json` in your workspace.663. **Global Discovery**: `~/.gemini/config/`674. **Built-in Customizations**: Default skills bundled with the application.685. **Global Declared Configurations**: Explicitly listed in global JSON69 configs.7071--------------------------------------------------------------------------------7273## How Customizations are Applied7475### Progressive Disclosure (Skills and Rules)7677To prevent overwhelming the model's context window, Antigravity uses78**progressive disclosure**:7980* **Skills** are not loaded into the context window by default. Only their81 names and descriptions are injected. The full content of a skill is only82 loaded if the model (or the user) explicitly decides to activate it.83* **Rules** with `trigger: model_decision` behave similarly. Only `always_on`84 rules are loaded unconditionally.8586### Deduplication8788All customizations (especially rules) are deduplicated by their resolved file89paths. A rule file will never be injected more than once in a single90conversation turn, even if it matches multiple trigger conditions.9192--------------------------------------------------------------------------------9394## Advanced Management: JSON Configs9596For customizations stored in non-standard locations, you can use `skills.json`97and `plugins.json` to explicitly register them and inherit from shared98configurations.99100* Learn how to configure these in the101 [JSON Configurations Guide](./docs/json_configs.md).
2428424081cn