1. Introdução
O Google Antigravity (chamado de Antigravity no restante do documento) é um IDE agêntico do Google. No codelab de introdução ao Antigravity, você pode aprender os conceitos básicos do Antigravity. Neste codelab, vamos usar o Antigravity para criar habilidades de agente, um formato aberto e leve para estender as capacidades de agentes de IA com conhecimentos e fluxos de trabalho especializados. Você vai aprender o que são as habilidades do agente, os benefícios delas e como são construídas. Em seguida, você vai criar várias habilidades de agente, desde um formatador do Git, um gerador de modelos, uma estrutura de código de ferramentas e muito mais, tudo utilizável no Antigravity.
Pré-requisitos:
- O Google Antigravity está instalado e configurado.
- Noções básicas sobre o Google Antigravity. Recomendamos que você conclua o codelab: Introdução ao Google Antigravity.
2. Por que usar o Skills
Os agentes de IA modernos evoluíram de ouvintes simples para raciocinadores complexos que se integram a sistemas de arquivos locais e ferramentas externas (via servidores MCP). No entanto, carregar um agente indiscriminadamente com bases de código inteiras e centenas de ferramentas leva à saturação de contexto e ao "inchaço de ferramentas". Mesmo com grandes janelas de contexto, despejar 40 a 50 mil tokens de ferramentas não utilizadas na memória ativa causa alta latência, desperdício financeiro e "deterioração do contexto", em que o modelo fica confuso com dados irrelevantes.
A solução: habilidades do agente
Para resolver isso, a Anthropic introduziu as Habilidades do agente, mudando a arquitetura do carregamento de contexto monolítico para a Divulgação progressiva. Em vez de forçar o modelo a "memorizar" todos os fluxos de trabalho específicos (como migrações de banco de dados ou auditorias de segurança) no início de uma sessão, essas funcionalidades são agrupadas em unidades modulares e detectáveis.
Como funciona
Inicialmente, o modelo é exposto apenas a um "menu" leve de metadados. Ele carrega o conhecimento procedural pesado (instruções e scripts) somente quando a intenção do usuário corresponde especificamente a uma habilidade. Isso garante que um desenvolvedor que pede para refatorar o middleware de autenticação receba o contexto de segurança sem carregar pipelines CSS não relacionados, mantendo o contexto simples, rápido e econômico.

3. Habilidades do agente e antigravidade
No ecossistema da Antigravity, se o Gerenciador de agentes for o cérebro e o Editor for a tela, as Habilidades vão atuar como módulos de treinamento especializados que preenchem a lacuna entre o modelo generalista Gemini 3 e seu contexto específico. Eles permitem que o agente "equipe" um conjunto definido de instruções e protocolos, como padrões de migração de banco de dados ou verificações de segurança, somente quando uma tarefa relevante é solicitada. Ao carregar dinamicamente esses protocolos de execução, as Skills transformam a IA de um programador genérico em um especialista que segue rigorosamente as práticas recomendadas e os padrões de segurança codificados de uma organização.
O que é uma habilidade no Antigravity?
No contexto do Google Antigravity, uma habilidade é um pacote baseado em diretório que contém um arquivo de definição (SKILL.md) e recursos de suporte opcionais (scripts, referências, modelos).
É um mecanismo para extensão de recursos sob demanda.
- Sob demanda: ao contrário de um comando do sistema (que é sempre carregado), uma habilidade só é carregada no contexto do agente quando ele determina que é relevante para a solicitação atual do usuário. Isso otimiza a janela de contexto e evita que o agente se distraia com instruções irrelevantes. Em projetos grandes com dezenas de ferramentas, esse carregamento seletivo é crucial para o desempenho e a precisão do raciocínio.
- Extensão de capacidade: as skills podem fazer mais do que apenas instruir, elas podem executar. Ao agrupar scripts Python ou Bash, uma habilidade pode dar ao agente a capacidade de realizar ações complexas e de várias etapas na máquina local ou em redes externas sem que o usuário precise executar comandos manualmente. Isso transforma o agente de um gerador de texto em um usuário de ferramentas.
Habilidades x ecossistema (ferramentas, regras e fluxos de trabalho)
Enquanto o Protocolo de Contexto de Modelo (MCP) funciona como as "mãos" do agente, fornecendo conexões persistentes e pesadas a sistemas externos, como GitHub ou PostgreSQL, as habilidades atuam como o "cérebro" que as direciona.
O MCP processa a infraestrutura com estado, enquanto as habilidades são definições de tarefas leves e temporárias que empacotam a metodologia para usar essas ferramentas. Essa abordagem sem servidor permite que os agentes executem tarefas ad hoc (como gerar changelogs ou migrações) sem a sobrecarga operacional de processos persistentes, carregando o contexto apenas quando a tarefa está ativa e liberando-o imediatamente depois.
Funcionalmente, as habilidades ocupam um meio-termo exclusivo entre "Regras" (proteções passivas e sempre ativas) e "Fluxos de trabalho" (macros ativas e acionadas pelo usuário). Ao contrário dos fluxos de trabalho que exigem comandos específicos (por exemplo, /test), as habilidades são acionadas pelo agente: o modelo detecta automaticamente a intenção do usuário e equipa dinamicamente a expertise específica necessária. Essa arquitetura permite uma capacidade de composição avançada. Por exemplo, uma regra global pode exigir o uso de uma habilidade de "migração segura" durante mudanças no banco de dados, ou um único fluxo de trabalho pode orquestrar várias habilidades para criar um pipeline de implantação robusto.
4. Como criar habilidades
A criação de uma habilidade no Antigravity segue uma estrutura de diretórios e um formato de arquivo específicos. Essa padronização garante que as habilidades sejam portáteis e que o agente possa analisá-las e executá-las de maneira confiável. O design é intencionalmente simples, contando com formatos amplamente compreendidos, como Markdown e YAML, reduzindo a barreira de entrada para desenvolvedores que querem estender os recursos do IDE.
Estrutura de diretórios
As habilidades podem ser definidas em dois escopos, permitindo personalizações específicas do projeto e do usuário :
- Escopo do Workspace: localizado em
<workspace-root>/.agent/skills/. Essas habilidades estão disponíveis apenas no projeto específico. Isso é ideal para scripts específicos do projeto, como implantação em um ambiente específico, gerenciamento de banco de dados para esse app ou geração de código boilerplate para uma estrutura proprietária. - Escopo global: localizado em
~/.gemini/antigravity/skills/. Essas habilidades estão disponíveis em todos os projetos na máquina do usuário. Isso é adequado para utilitários gerais, como "Formatar JSON", "Gerar UUIDs", "Revisar estilo de código" ou integração com ferramentas de produtividade pessoal.
Um diretório de habilidade típico tem esta aparência:
my-skill/
├── SKILL.md # The definition file
├── scripts/ # [Optional] Python, Bash, or Node scripts
├── run.py
└── util.sh
├── references/ # [Optional] Documentation or templates
└── api-docs.md
└── assets/ # [Optional] Static assets (images, logos)
Essa estrutura separa os conceitos de maneira eficaz. A lógica (scripts) é separada da instrução (SKILL.md) e do conhecimento (references), espelhando as práticas padrão de engenharia de software.
O arquivo de definição SKILL.md
O arquivo SKILL.md é o cérebro da habilidade. Ele informa ao agente o que é a habilidade, quando usá-la e como executá-la.
Ele consiste em duas partes:
- Frontmatter do YAML
- Corpo em Markdown.
YAML Frontmatter
Essa é a camada de metadados. É a única parte da habilidade indexada pelo roteador de alto nível do agente. Quando um usuário envia um comando, o agente faz uma correspondência semântica entre o comando e os campos de descrição de todas as habilidades disponíveis.
---
name: database-inspector
description: Use this skill when the user asks to query the database, check table schemas, or inspect user data in the local PostgreSQL instance.
---
Campos-chave:
- name: não é obrigatório. Precisa ser exclusivo no escopo. Minúsculas, hifens permitidos (por exemplo,
postgres-query,pr-reviewer). Se não for fornecido, o padrão será o nome do diretório. - description: obrigatório e o campo mais importante. Ela funciona como a "frase de ativação". Ela precisa ser descritiva o suficiente para que o LLM reconheça a relevância semântica. Uma descrição vaga como "Ferramentas de banco de dados" não é suficiente. Uma descrição precisa como "Executa consultas SQL somente leitura no banco de dados PostgreSQL local para recuperar dados de usuários ou transações. Use isso para depurar estados de dados" garante que a habilidade seja captada corretamente.
O corpo do Markdown
O corpo contém as instruções. Isso é a "engenharia de comando" persistida em um arquivo. Quando a habilidade é ativada, esse conteúdo é inserido na janela de contexto do agente.
O corpo precisa incluir:
- Objetivo: uma declaração clara do que a habilidade realiza.
- Instruções: lógica detalhada.
- Exemplos: exemplos de poucas imagens de entradas e saídas para orientar o desempenho do modelo.
- Restrições: regras de "não" (por exemplo, "Não execute consultas DELETE").
Exemplo de corpo de SKILL.md:
Database Inspector
Goal
To safely query the local database and provide insights on the current data state.
Instructions
- Analyze the user's natural language request to understand the data need.
- Formulate a valid SQL query.
- CRITICAL: Only SELECT statements are allowed.
- Use the script scripts/query_runner.py to execute the SQL.
- Command: python scripts/query_runner.py "SELECT * FROM..."
- Present the results in a Markdown table.
Constraints
- Never output raw user passwords or API keys.
- If the query returns > 50 rows, summarize the data instead of listing it all.
Integração de script
Um dos recursos mais poderosos do Skills é a capacidade de delegar a execução a scripts. Isso permite que o agente execute ações difíceis ou impossíveis para um LLM fazer diretamente (como execução binária, cálculo matemático complexo ou interação com sistemas legados).
Os scripts são colocados no subdiretório scripts/. O SKILL.md faz referência a eles por caminho relativo.
5. Habilidades de criação
O objetivo desta seção é criar habilidades que se integram ao Antigravity e mostram progressivamente vários recursos, como recursos / scripts / etc.
Faça o download das habilidades no repositório do GitHub: https://github.com/rominirani/antigravity-skills.
Podemos colocar cada uma dessas habilidades na pasta ~/.gemini/antigravity/skills ou /.agent/skills.
Nível 1 : o roteador básico ( git-commit-formatter )
Vamos considerar isso como o "Hello World" das Skills.
Os desenvolvedores costumam escrever mensagens de commit preguiçosas, por exemplo, "wip", "fix bug", "updates". Aplicar "Conventional Commits" manualmente é tedioso e muitas vezes esquecido. Vamos implementar uma habilidade que aplique a especificação de commits convencionais. Ao instruir o agente sobre as regras, permitimos que ele atue como fiscalizador.
git-commit-formatter/
└── SKILL.md (Instructions only)
O arquivo SKILL.md é mostrado abaixo:
---
name: git-commit-formatter
description: Formats git commit messages according to Conventional Commits specification. Use this when the user asks to commit changes or write a commit message.
---
Git Commit Formatter Skill
When writing a git commit message, you MUST follow the Conventional Commits specification.
Format
`<type>[optional scope]: <description>`
Allowed Types
- **feat**: A new feature
- **fix**: A bug fix
- **docs**: Documentation only changes
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, etc)
- **refactor**: A code change that neither fixes a bug nor adds a feature
- **perf**: A code change that improves performance
- **test**: Adding missing tests or correcting existing tests
- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation
Instructions
1. Analyze the changes to determine the primary `type`.
2. Identify the `scope` if applicable (e.g., specific component or file).
3. Write a concise `description` in an imperative mood (e.g., "add feature" not "added feature").
4. If there are breaking changes, add a footer starting with `BREAKING CHANGE:`.
Example
`feat(auth): implement login with google`
Como executar este exemplo:
- Faça uma pequena mudança em qualquer arquivo no seu espaço de trabalho.
- Abra a conversa e digite: Confirme essas mudanças.
- O agente não vai apenas executar o git commit. Primeiro, ele vai ativar a habilidade git-commit-formatter.
- Resultado: uma mensagem de commit do Git convencional será proposta.
Por exemplo, eu pedi para o Antigravity adicionar alguns comentários a um arquivo de amostra do Python, e ele acabou com uma mensagem de commit do Git como docs: add detailed comments to demo_primes.py.
Nível 2: utilização de recursos (license-header-adder)
Esse é o padrão "Referência".
Cada arquivo de origem em um projeto corporativo pode precisar de um cabeçalho de licença Apache 2.0 específico de 20 linhas. Colocar esse texto estático diretamente no comando (ou SKILL.md) é um desperdício. Ele consome tokens sempre que a habilidade é indexada, e o modelo pode "alucinar" erros de digitação em textos jurídicos.
Descarregar o texto estático em um arquivo de texto simples em uma pasta resources/. A habilidade instrui o agente a ler esse arquivo apenas quando necessário.
Converter dados soltos (como uma resposta da API JSON) em código estrito (como modelos Pydantic) envolve dezenas de decisões. Como devemos nomear as classes? Devemos usar Optional? snake_case ou camelCase? Escrever essas 50 regras em inglês é tedioso e propenso a erros.
Os LLMs são mecanismos de correspondência de padrões.
Mostrar um exemplo de ouro (entrada -> saída) geralmente é mais eficaz do que instruções detalhadas.
license-header-adder/
├── SKILL.md
└── resources/
└── HEADER_TEMPLATE.txt (The heavy text)
O arquivo SKILL.md é mostrado abaixo:
---
name: license-header-adder
description: Adds the standard open-source license header to new source files. Use involves creating new code files that require copyright attribution.
---
# License Header Adder Skill
This skill ensures that all new source files have the correct copyright header.
## Instructions
1. **Read the Template**:
First, read the content of the header template file located at `resources/HEADER_TEMPLATE.txt`.
2. **Prepend to File**:
When creating a new file (e.g., `.py`, `.java`, `.js`, `.ts`, `.go`), prepend the `target_file` content with the template content.
3. **Modify Comment Syntax**:
- For C-style languages (Java, JS, TS, C++), keep the `/* ... */` block as is.
- For Python, Shell, or YAML, convert the block to use `#` comments.
- For HTML/XML, use `<!-- ... -->`.
Como executar este exemplo:
- Crie um novo arquivo Python fictício:
touch my_script.py - Tipo:
Add the license header to my_script.py. - O agente vai ler
license-header-adder/resources/HEADER_TEMPLATE.txt. - Ele vai colar o conteúdo exatamente como está no arquivo.
Nível 3: aprendizado por exemplo (json-to-pydantic)
O padrão "Few-Shot".
Converter dados soltos (como uma resposta da API JSON) em código estrito (como modelos Pydantic) envolve dezenas de decisões. Como devemos nomear as classes? Devemos usar Optional? snake_case ou camelCase? Escrever essas 50 regras em inglês é tedioso e propenso a erros.
Os LLMs são mecanismos de correspondência de padrões. Mostrar um exemplo de ouro (entrada -> saída) geralmente é mais eficaz do que instruções detalhadas.
json-to-pydantic/
├── SKILL.md
└── examples/
├── input_data.json (The Before State)
└── output_model.py (The After State)
O arquivo SKILL.md é mostrado abaixo:
---
name: json-to-pydantic
description: Converts JSON data snippets into Python Pydantic data models.
---
# JSON to Pydantic Skill
This skill helps convert raw JSON data or API responses into structured, strongly-typed Python classes using Pydantic.
Instructions
1. **Analyze the Input**: Look at the JSON object provided by the user.
2. **Infer Types**:
- `string` -> `str`
- `number` -> `int` or `float`
- `boolean` -> `bool`
- `array` -> `List[Type]`
- `null` -> `Optional[Type]`
- Nested Objects -> Create a separate sub-class.
3. **Follow the Example**:
Review `examples/` to see how to structure the output code. notice how nested dictionaries like `preferences` are extracted into their own class.
- Input: `examples/input_data.json`
- Output: `examples/output_model.py`
Style Guidelines
- Use `PascalCase` for class names.
- Use type hints (`List`, `Optional`) from `typing` module.
- If a field can be missing or null, default it to `None`.
Na pasta /examples, há o arquivo JSON e o arquivo de saída, ou seja, o arquivo Python. Ambos são mostrados abaixo:
input_data.json
{
"user_id": 12345,
"username": "jdoe_88",
"is_active": true,
"preferences": {
"theme": "dark",
"notifications": [
"email",
"push"
]
},
"last_login": "2024-03-15T10:30:00Z",
"meta_tags": null
}
output_model.py
from pydantic import BaseModel, Field
from typing import List, Optional
class Preferences(BaseModel):
theme: str
notifications: List[str]
class User(BaseModel):
user_id: int
username: str
is_active: bool
preferences: Preferences
last_login: Optional[str] = None
meta_tags: Optional[List[str]] = None
Como executar este exemplo:
- Forneça ao agente um snippet de JSON (cole no chat ou indique um arquivo).
{ "product": "Widget", "cost": 10.99, "stock": null }
- Tipo:
Convert this JSON to a Pydantic model. - O agente analisa o par
examplesna pasta da habilidade. - Ele gera uma classe Python que imita perfeitamente o estilo de programação, as importações e a estrutura de
output_model.py, incluindo o tratamento do estoque nulo como opcional.
Confira um exemplo de saída (product_model.py):
from pydantic import BaseModel
from typing import Optional
class Product(BaseModel):
product: str
cost: float
stock: Optional[int] = None
Nível 4: lógica procedural (database-schema-validator)
Esse é o padrão "Uso de ferramentas".
Se você perguntar a um LLM "Este esquema é seguro?", ele pode dizer que está tudo bem, mesmo que uma chave primária crítica esteja faltando, simplesmente porque o SQL parece correto.
Vamos delegar essa verificação a um script determinista. Usamos a habilidade para encaminhar o agente e executar um script Python que escrevemos. O script fornece uma verdade binária (verdadeiro/falso).
database-schema-validator/
├── SKILL.md
└── scripts/
└── validate_schema.py (The Validator)
O arquivo SKILL.md é mostrado abaixo:
---
name: database-schema-validator
description: Validates SQL schema files for compliance with internal safety and naming policies.
---
# Database Schema Validator Skill
This skill ensures that all SQL files provided by the user comply with our strict database standards.
Policies Enforced
1. **Safety**: No `DROP TABLE` statements.
2. **Naming**: All tables must use `snake_case`.
3. **Structure**: Every table must have an `id` column as PRIMARY KEY.
Instructions
1. **Do not read the file manually** to check for errors. The rules are complex and easily missed by eye.
2. **Run the Validation Script**:
Use the `run_command` tool to execute the python script provided in the `scripts/` folder against the user's file.
`python scripts/validate_schema.py <path_to_user_file>`
3. **Interpret Output**:
- If the script returns **exit code 0**: Tell the user the schema looks good.
- If the script returns **exit code 1**: Report the specific error messages printed by the script to the user and suggest fixes.
O arquivo validate_schema.py é mostrado abaixo:
import sys
import re
def validate_schema(filename):
"""
Validates a SQL schema file against internal policy:
1. Table names must be snake_case.
2. Every table must have a primary key named 'id'.
3. No 'DROP TABLE' statements allowed (safety).
"""
try:
with open(filename, 'r') as f:
content = f.read()
lines = content.split('\n')
errors = []
# Check 1: No DROP TABLE
if re.search(r'DROP TABLE', content, re.IGNORECASE):
errors.append("ERROR: 'DROP TABLE' statements are forbidden.")
# Check 2 & 3: CREATE TABLE checks
table_defs = re.finditer(r'CREATE TABLE\s+(?P<name>\w+)\s*\((?P<body>.*?)\);', content, re.DOTALL | re.IGNORECASE)
for match in table_defs:
table_name = match.group('name')
body = match.group('body')
# Snake case check
if not re.match(r'^[a-z][a-z0-9_]*$', table_name):
errors.append(f"ERROR: Table '{table_name}' must be snake_case.")
# Primary key check
if not re.search(r'\bid\b.*PRIMARY KEY', body, re.IGNORECASE):
errors.append(f"ERROR: Table '{table_name}' is missing a primary key named 'id'.")
if errors:
for err in errors:
print(err)
sys.exit(1)
else:
print("Schema validation passed.")
sys.exit(0)
except FileNotFoundError:
print(f"Error: File '{filename}' not found.")
sys.exit(1)
if __name__ == "__main__":
if len(sys.argv) != 2:
print("Usage: python validate_schema.py <schema_file>")
sys.exit(1)
validate_schema(sys.argv[1])
Como executar este exemplo:
- Crie um arquivo SQL incorreto
bad_schema.sql:CREATE TABLE users (name TEXT); - Tipo:
Validate bad_schema.sql. - O agente não faz suposições. Ele vai invocar o script, que falha (código de saída 1), e vai informar que "A validação falhou porque a tabela "users" não tem uma chave primária".
Nível 5: o arquiteto (adk-tool-scaffold)
Esse padrão abrange a maioria dos recursos disponíveis no Skills.
Tarefas complexas geralmente exigem uma sequência de operações que combinam tudo o que vimos: criação de arquivos, uso de modelos e escrita de lógica. Para criar uma nova ferramenta para o ADK (Kit de Desenvolvimento de Agente), é necessário fazer tudo isso.
Combinamos:
- Script (para processar a criação/estruturação de arquivos)
- Modelo (para processar texto padrão em recursos)
- Um exemplo (para orientar a geração de lógica).
adk-tool-scaffold/
├── SKILL.md
├── resources/
│ └── ToolTemplate.py.hbs (Jinja2 Template)
├── scripts/
│ └── scaffold_tool.py (Generator Script)
└── examples/
└── WeatherTool.py (Reference Implementation)
O arquivo SKILL.md é mostrado abaixo. Consulte o repositório de habilidades para conferir os arquivos na pasta de scripts, recursos e exemplos. Para essa habilidade específica, acesse a habilidade adk-tool-scaffold.
---
name: adk-tool-scaffold
description: Scaffolds a new custom Tool class for the Agent Development Kit (ADK).
---
# ADK Tool Scaffold Skill
This skill automates the creation of standard `BaseTool` implementations for the Agent Development Kit.
Instructions
1. **Identify the Tool Name**:
Extract the name of the tool the user wants to build (e.g., "StockPrice", "EmailSender").
2. **Review the Example**:
Check `examples/WeatherTool.py` to understand the expected structure of an ADK tool (imports, inheritance, schema).
3. **Run the Scaffolder**:
Execute the python script to generate the initial file.
`python scripts/scaffold_tool.py <ToolName>`
4. **Refine**:
After generation, you must edit the file to:
- Update the `execute` method with real logic.
- Define the JSON schema in `get_schema`.
Example Usage
User: "Create a tool to search Wikipedia."
Agent:
1. Runs `python scripts/scaffold_tool.py WikipediaSearch`
2. Editing `WikipediaSearchTool.py` to add the `requests` logic and `query` argument schema.
Como executar este exemplo:
- Tipo:
Create a new ADK tool called StockPrice to fetch data from an API. - Etapa 1 (estruturação): o agente executa o script Python. Isso cria instantaneamente
StockPriceTool.pycom a estrutura de classe, as importações e o nome de classeStockPriceToolcorretos. - Etapa 2 (implementação): o agente "lê" o arquivo que acabou de criar. Ele vê
# TODO: Implement logic. - Etapa 3 (orientação): não há certeza de como definir o esquema JSON para os argumentos da ferramenta. Ele verifica
examples/WeatherTool.py. - Conclusão: edita o arquivo para adicionar
requests.get(...)e define o argumento de tique-taque no esquema, correspondendo exatamente ao estilo do ADK.
6. Parabéns
Você concluiu o laboratório sobre habilidades de antigravidade e criou as seguintes habilidades:
- Formatador de commit do Git.
- Adicionador de cabeçalho de licença.
- JSON para Pydantic.
- Validador de esquema de banco de dados.
- Estrutura de ferramenta do ADK.
As habilidades do agente são uma ótima maneira de usar o Antigravity para escrever código do seu jeito, seguir regras e usar suas ferramentas.
Documentos de referência
- Codelab : como começar a usar o Google Antigravity
- Site oficial : https://antigravity.google/
- Documentação: https://antigravity.google/docs
- Download : https://antigravity.google/download
- Documentação do Antigravity Skills: https://antigravity.google/docs/skills