Google Antigravity Skills: The Complete Guide to Building Custom AI Agent Behaviors

Google Antigravity has revolutionized how developers interact with AI-powered development tools. At the heart of this revolution lies a powerful feature called Skills—specialized knowledge packages that transform a generalist AI model into a domain expert tailored to your specific needs. In this comprehensive guide, we'll explore everything you need to know about Antigravity Skills and how they can supercharge your development workflow.

What Are Antigravity Skills?

Antigravity Skills are specialized packages of knowledge that remain dormant until needed, solving one of the most significant challenges in AI-assisted development: tool bloat. Instead of loading every possible capability into the agent's context at once, Skills implement a concept called Progressive Disclosure—loading only the relevant expertise when your specific request matches the skill's description.

Think of Skills as expert consultants who only join your team meeting when their expertise is needed. This approach offers several key advantages:

• Reduced Context Pollution: Your agent's context window stays focused on relevant information
• Faster Response Times: Less context means quicker AI processing
• Domain Expertise On-Demand: Transform a generalist model into a specialist instantly
• Consistent Team Standards: Codify best practices into executable assets

How Antigravity Skills Work

When you make a request to Antigravity, the system analyzes your input and matches it against available skill descriptions. If a match is found, the relevant skill is loaded into the agent's context, providing it with specialized knowledge, templates, and instructions.

This just-in-time loading mechanism ensures that:

1. The AI receives precisely the context it needs for your task
2. Irrelevant information doesn't dilute the agent's focus
3. Your specific requirements and standards are always followed
4. Complex workflows become repeatable and consistent

Skills Directory Structure

Every Antigravity Skill follows a standardized directory-based architecture that ensures portability and reliable parsing:

my-skill/
├── SKILL.md      # Required: metadata & instructions
├── scripts/      # Optional: Python or Bash scripts
├── references/   # Optional: text, documentation, templates
└── assets/       # Optional: images or logos

Understanding Each Component

SKILL.md (Required)

The heart of every skill is the SKILL.md file. This file contains frontmatter with metadata followed by detailed instructions:

---
name: "Code Review"
description: "Performs systematic code review following team standards"
---

# Code Review Skill

When performing a code review, follow these steps:

1. Check for correctness and logic errors
2. Identify edge cases and potential bugs
3. Verify adherence to coding standards
4. Assess performance implications
5. Review security considerations

scripts/ (Optional)

Contains executable Python or Bash scripts that the agent can invoke. This is useful for automation tasks like running linters, formatters, or custom tools.

references/ (Optional)

Stores static resources like documentation, templates, configuration files, or any text-based content the agent might need to reference.

assets/ (Optional)

Houses images, logos, or other binary assets that might be needed for documentation or UI purposes.

Skill Scope: Global vs Workspace

Antigravity supports two levels of skill scope, giving you flexibility in how you organize and share your skills:

Global Skills

Location: ~/.gemini/antigravity/skills/

Global skills are available across all your projects. These are ideal for:

• Personal productivity scripts
• Universal code review guidelines
• Cross-project coding standards
• Utility functions you use everywhere

Workspace Skills

Location: <workspace-root>/.agent/skills/

Workspace skills are specific to a single project. These are perfect for:

• Project-specific conventions
• Team coding standards
• Custom deployment procedures
• Repository-specific templates

Creating Your First Skill: Step-by-Step Guide

Let's walk through creating a practical skill from scratch. We'll build a License Header Skill that automatically adds appropriate copyright headers to new files.

Step 1: Create the Directory Structure

mkdir -p .agent/skills/license-header/references

Step 2: Create the SKILL.md File

Create .agent/skills/license-header/SKILL.md:

---
name: "License Header"
description: "Adds appropriate license headers to new source files"
---

# License Header Skill

When creating new source files, always prepend the appropriate license header.

## Instructions

1. Determine the file type from the extension
2. Select the appropriate comment syntax
3. Insert the license header at the top of the file
4. Ensure one blank line separates the header from the code

## Comment Syntax

- **C-style** (js, ts, java, c, cpp, go): Use `/* */` block comments
- **Python/Ruby/Shell**: Use `#` line comments
- **HTML/XML**: Use `<!-- -->` comments

Refer to the license template in `references/license.txt`.

Step 3: Add the License Template

Create .agent/skills/license-header/references/license.txt:

Copyright 2025 Your Company Name
All rights reserved.

Licensed under the Apache License, Version 2.0.
See LICENSE file for details.

Step 4: Test Your Skill

Now when you ask Antigravity to create a new file, the agent will automatically include the appropriate license header based on the file type.

Advanced Skill Examples

Code Review Skill (Instruction-Only)

A comprehensive code review skill that guides the agent through systematic evaluation:

---
name: "Code Review"
description: "Performs thorough code review following engineering best practices"
---

# Code Review Skill

## Review Checklist

### Correctness
- Does the code do what it's supposed to do?
- Are there any logic errors or off-by-one bugs?
- Are error cases handled properly?

### Edge Cases
- What happens with null/undefined inputs?
- How does it handle empty collections?
- Are boundary conditions tested?

### Code Style
- Does it follow our naming conventions?
- Is the code properly formatted?
- Are functions and variables descriptively named?

### Performance
- Are there any O(n²) operations that could be O(n)?
- Is there unnecessary memory allocation?
- Are database queries optimized?

### Security
- Is user input properly validated?
- Are there any injection vulnerabilities?
- Is sensitive data properly protected?

Git Commit Skill (Script-Based)

A skill that enforces commit message conventions:

---
name: "Git Commit"
description: "Creates well-formatted git commits following conventional commit standards"
---

# Git Commit Skill

## Commit Message Format

Follow the Conventional Commits specification:

():

[optional body]

[optional footer(s)]

## Types
- **feat**: New feature
- **fix**: Bug fix
- **docs**: Documentation changes
- **style**: Formatting, semicolons, etc.
- **refactor**: Code restructuring
- **test**: Adding tests
- **chore**: Maintenance tasks

## Rules
1. Subject line max 50 characters
2. Body wrapped at 72 characters
3. Use imperative mood ("Add feature" not "Added feature")
4. Reference issues in footer

Best Practices for Creating Skills

1. Write Clear Descriptions

The skill description is crucial for proper matching. Be specific about what the skill does:

Good: "Performs database migration with rollback support for PostgreSQL"

Bad: "Database stuff"

2. Keep Instructions Actionable

Write instructions as clear, step-by-step procedures the agent can follow:

## Steps

1. First, check if the database connection is active
2. Create a backup of affected tables
3. Execute the migration script
4. Verify data integrity
5. Log the migration result

3. Use Templates for Consistency

When you need consistent output formats, include templates in your references/ directory:

references/
├── pr-template.md
├── issue-template.md
└── release-notes-template.md

4. Version Control Your Skills

Since workspace skills live in your repository, they benefit from version control:

• Track changes to team standards over time
• Review skill modifications through pull requests
• Roll back if a skill change causes issues

5. Document Edge Cases

Include guidance for ambiguous situations:

## Edge Cases

- If the file already has a license header, do not add another
- For generated files, skip the license header
- For test files, use the short-form header

Why Skills Matter for Teams

Codifying Best Practices

Every team has unwritten rules—coding conventions, review standards, deployment procedures. Skills transform these implicit expectations into explicit, executable instructions that the AI follows consistently.

Reducing Repetitive Prompting

Without Skills, developers often find themselves repeating the same instructions:

• "Remember to add the license header"
• "Follow our commit message format"
• "Use our error handling pattern"

Skills eliminate this repetition by encoding these requirements once.

Onboarding New Developers

When new team members join, Skills serve as living documentation of your team's practices. The AI doesn't just explain the rules—it actively enforces them.

Consistency at Scale

As teams grow, maintaining consistency becomes challenging. Skills ensure that whether you have 5 or 500 developers, everyone's AI assistant follows the same standards.

Integrating Skills with Your Workflow

IDE Integration

Skills work seamlessly within Antigravity's Visual Studio Code-based interface. Simply:

1. Open your project
2. Ensure skills are in the correct directory
3. Start working—relevant skills activate automatically

CI/CD Integration

Consider creating skills that align with your CI/CD pipeline:

• Pre-commit validation skills
• Build verification skills
• Deployment checklist skills

Team Collaboration

Share skills across your organization:

1. Create a shared skills repository
2. Include it as a git submodule in projects
3. Keep skills updated through pull requests

Troubleshooting Common Issues

Skill Not Loading

Problem: Your skill doesn't activate when expected.

Solutions:

• Verify the SKILL.md file exists and has valid frontmatter
• Check that the description accurately matches your request patterns
• Ensure the skill directory is in the correct location

Conflicting Skills

Problem: Multiple skills try to handle the same request.

Solutions:

• Make skill descriptions more specific
• Use workspace skills to override global defaults
• Review and consolidate overlapping skills

Outdated Instructions

Problem: Skill instructions don't match current requirements.

Solutions:

• Regularly review and update skill content
• Use version control to track changes
• Include update dates in skill documentation

The Future of AI-Assisted Development

Antigravity Skills represent a fundamental shift in how we interact with AI development tools. Instead of treating AI as a generic assistant, Skills allow us to create specialized, context-aware agents that understand our specific needs.

As the ecosystem matures, we expect to see:

• Skill Marketplaces: Community-shared skills for common frameworks and tools
• AI-Generated Skills: Agents that learn from your patterns and suggest new skills
• Cross-Platform Skills: Standards for portable skills across different AI IDEs

Conclusion

Google Antigravity Skills transform how developers work with AI assistants. By codifying your team's best practices, coding standards, and workflows into specialized knowledge packages, you create a more consistent, efficient, and intelligent development environment.

Whether you're a solo developer looking to automate repetitive tasks or a team lead establishing standards across your organization, Skills provide the framework to make your AI assistant truly yours.

Start small—create one skill for your most repetitive task. As you experience the benefits, you'll naturally identify more opportunities to leverage this powerful feature.

---

Frequently Asked Questions

Q: Do I need programming skills to create Antigravity Skills? A: No, basic Skills only require writing markdown files with clear instructions. Advanced Skills with scripts do require some programming knowledge.

Q: Can I share Skills between different projects? A: Yes, you can place Skills in the global directory (~/.gemini/antigravity/skills/) to make them available across all projects, or use git submodules to share workspace Skills.

Q: How many Skills can I have active at once? A: There's no hard limit, but only relevant Skills are loaded into context when needed. The Progressive Disclosure system ensures optimal performance regardless of how many Skills you have defined.

Q: Can Skills call external APIs or services? A: Yes, through the scripts directory, Skills can include Python or Bash scripts that interact with external services, subject to Antigravity's permission system.

Q: Are Skills compatible with all AI models in Antigravity? A: Yes, Skills work with all supported models including Gemini 3, Claude Sonnet 4.5, and Claude Opus 4.5. The skill content is model-agnostic.

Q: How do I update a Skill without disrupting my team? A: Since workspace Skills are version-controlled with your repository, use standard pull request workflows to review and deploy skill updates.

---

Last updated: December 20, 2025