How to Build Custom Skills for Antigravity Using Agent Skills Standard

While many AI CLI tools rely on manual slash-commands (like /test or /deploy), Antigravity takes a different approach: full autonomy.

In Antigravity, you don't trigger skills manually. Instead, the agent uses progressive disclosure—it reads the metadata of your available skills and autonomously activates the right one at the right time based on your prompt.

To achieve this, Antigravity strictly follows the open Agent Skills standard. Here is how you can build a custom, highly focused skill for your autonomous agent.

1. Choose Where to Save Your Skill

You can create skills that apply to a specific project workspace or globally across your machine.

• Workspace-specific (Project Level): Save your skill folder at <workspace-root>/.agents/skills/<skill-folder>/. This is perfect for project-specific workflows like custom testing conventions or deployment pipelines.
• Global (User Level): Save your skill at ~/.gemini/antigravity/skills/<skill-folder>/. Use this for general-purpose utilities you want the agent to remember everywhere.

(Note: Antigravity defaults to .agents/skills, but maintains backward compatibility with older .agent/skills directories).

2. Create the Directory Structure

Create a new folder for your skill. While only the SKILL.md file is strictly mandatory, a robust skill folder usually looks like this:

my-autonomous-skill/
├── SKILL.md       # Required: The brain (metadata and instructions)
├── scripts/       # Optional: Executable helper scripts (Bash, Python, Node)
├── examples/      # Optional: Reference implementations for the AI
└── resources/     # Optional: Templates and static assets

3. Write the SKILL.md File

Every skill must begin with a YAML frontmatter block, followed by the main Markdown instructions.

---
name: generate-python-tests
description: Generates unit tests for Python code using pytest conventions.
---

# Instructions
When this skill is activated, follow these specific testing conventions...

🔥 Crucial Step: The description field is the most important part of this file. Because Antigravity operates autonomously, it uses this exact description to decide when to activate the skill. Write it in the third person and use clear keywords.

Below the frontmatter, write the step-by-step guidance, strict rules, checklists, and patterns the agent must follow.

4. Antigravity Best Practices for AI Engineers

To ensure your skill works perfectly without manual intervention, adhere to these architectural guidelines:

• Keep skills hyper-focused: A skill should do one thing exceptionally well. Do not create a "do-everything" skill. Break disparate tasks down into multiple smaller skills.
• Treat scripts as black boxes: If your skill bundles executable scripts, do not force the AI to read the raw source code. Instruct the agent to run the script with a --help flag first. This saves context tokens and keeps the AI focused on execution.
• Provide decision trees: For complex skills, include a decision tree in your Markdown body (e.g., "If error X occurs, do Y. If state Z is true, do W"). This gives the autonomous agent a clear path to resolve blockers without asking you for help.

How to Trigger It? You Don't.

You do not need to manually trigger the skill. When a conversation starts, Antigravity automatically discovers available skills and activates the full instructions whenever it deems the skill relevant to your prompt.

(If you ever need to force its activation, simply mention the skill's name in your natural language prompt).