Antigravity CLI Cookbook 🚀

Welcome to the definitive community guide for extending the Antigravity CLI.

While the official documentation is excellent for basic usage, understanding how the underlying plugin and agent discovery engine works can be tricky. This repository documents the exact, tested methods for building, packaging, and registering Custom Subagents and Skills for your CLI.

---

🛑 The Secret: Agents are Plugins

Many developers try to create a folder (like .agents/agents/my_agent) with an agent.json file, only to find that the CLI completely ignores it on startup.

The missing link: The Antigravity CLI does not automatically scan raw directories for custom agents. To get the CLI's discovery engine to index your subagents and skills, the directory must be packaged as an Antigravity Plugin.

This is achieved simply by placing a plugin.json marker file at the root of your directory and running the plugin installation command.

---

📁 Recommended Directory Structure

To keep your workspace organized and ensure the CLI parses everything correctly, use the following directory structure:

my-project/
├── .agents/                      # The root of your custom plugin
│   ├── plugin.json               # REQUIRED: The plugin marker file
│   ├── agents/                   # Directory containing all your subagents
│   │   ├── research_agent/
│   │   │   └── agent.json        # The strict subagent configuration
│   │   └── code_auditor/
│   │       └── agent.json
│   └── skills/                   # (Optional) Reusable skills
│       ├── web_search/
│       │   └── SKILL.md
│       └── refactor/
│           └── SKILL.md

---

📄 1. The plugin.json Marker

At the root of your .agents folder, create a plugin.json file. This tells the CLI's package manager that this directory contains installable extensions.

{
  "name": "custom_agents",
  "version": "1.0.0",
  "description": "Custom subagents for this workspace"
}

---

🤖 2. The agent.json Schema

Inside your agents/ directory, create a folder for each subagent. Inside that folder, you must define your agent.json.

Critical: The schema is strictly typed based on the underlying Go/Protobuf engine. You must use config.customAgent and explicitly define your toolNames array.

Here is the 100% verified, working schema:

{
  "name": "research_agent",
  "description": "Specialized subagent for performing deep web research, gathering context, and analyzing documentation.",
  "hidden": false,
  "config": {
    "customAgent": {
      "systemPromptSections": [
        {
          "title": "Instructions",
          "content": "You are the **Research Agent**. Your primary purpose is to perform deep, structured research. You do not write code; you investigate, evaluate, and document.\n\nKeep your findings precise and developer-grade."
        }
      ],
      "toolNames": [
        "send_message",
        "find_by_name",
        "grep_search",
        "view_file",
        "list_dir",
        "read_url_content",
        "search_web",
        "schedule",
        "multi_replace_file_content",
        "replace_file_content",
        "write_to_file",
        "run_command",
        "manage_task",
        "define_subagent",
        "invoke_subagent",
        "manage_subagents",
        "call_mcp_tool"
      ],
      "systemPromptConfig": {
        "includeSections": [
          "user_information",
          "mcp_servers",
          "skills",
          "subagent_reminder",
          "messaging",
          "artifacts",
          "user_rules"
        ]
      }
    }
  }
}

Note on toolNames: To ensure your agent can communicate and execute tasks, always include standard tools like send_message, view_file, and run_command.

---

⚡ 3. Installing and Activating

Once your files are in place, you must instruct the CLI to install the plugin. From the root of your project workspace (next to the .agents folder), run:

agy plugin install .agents

If successful, the CLI will output a confirmation:

  [ok]    .agents
          ✔ skills      : 2 processed
          ✔ agents      : 2 processed

Verification

To verify your custom agents were successfully registered, type /agents in the Antigravity CLI chat. Your newly installed agents will immediately appear in the active UI list and are ready to be used!

---

🛠️ 4. Available Tools (toolNames)

When configuring your agent.json, the toolNames array defines exactly what your agent is allowed to do. If you omit a tool, the agent cannot use it.

Here are the most common and powerful tools to include:

• send_message: Required for the agent to communicate back to the user or parent session.
• run_command: Allows the agent to execute terminal commands (bash).
• view_file / read_url_content: Allows reading local files and fetching web pages.
• write_to_file / replace_file_content: Allows the agent to create and modify code files.
• search_web: Enables Google Search capabilities for research.
• call_mcp_tool: Highly Recommended. Allows the agent to interface with your configured Model Context Protocol (MCP) servers (e.g., executing GitHub PRs, querying databases).

---

🧠 5. Context Injection (includeSections)

In your agent.json, you will notice the systemPromptConfig.includeSections array. This is a powerful feature of the Antigravity CLI engine.

Instead of writing a massive static prompt, this array tells the CLI to automatically inject real-time environmental context into the agent's brain on every turn:

• user_information: Injects the current OS, working directory, and user preferences.
• mcp_servers: Injects a dynamic list of currently available MCP tools and their schemas.
• skills: Injects a list of loaded SKILL.md files so the agent knows what workflows are available.
• artifacts: Injects the current state of any markdown artifacts generated in the session.

Always include these in your schema so your agent is context-aware!

---

🐛 6. Troubleshooting & Debugging

If your agent is still not showing up or working, check these common pitfalls:

1. Verify Plugin Processing: Run agy plugin install .agents again. The output must say ✔ agents : X processed. If it says skipped (not found), your agent.json schema has a typo or the plugin.json marker is missing.
2. Check the Internal Logs: The CLI logs all startup errors, including JSON parsing failures. Run this to see what the engine is complaining about:

   tail -n 100 ~/.gemini/antigravity-cli/log/cli-*.log

---

🤝 Contributing

Found a new schema trick? Built an incredibly useful subagent? Pull requests are always welcome! Let's build the ultimate Antigravity CLI toolkit together.