Criação de habilidades do Google Antigravity

1. Introdução

O Google Antigravity é um IDE agêntico do Google. Neste codelab, vamos usar o Antigravity para criar habilidades de agentes, um formato aberto e leve para estender os recursos de agentes de IA com conhecimento e fluxos de trabalho especializados. Você vai aprender o que são as habilidades de agentes, os benefícios delas e como são construídas. Em seguida, você vai criar várias habilidades de agentes, desde um formatador do Git, um gerador de modelos, um scaffolding de código de ferramenta e muito mais, tudo utilizável no Antigravity.

Pré-requisitos:

2. Por que habilidades

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, o despejo de 40 a 50 mil tokens de ferramentas não utilizadas na memória ativa causa alta latência, desperdício financeiro e "corrupção de contexto", em que o modelo fica confuso com dados irrelevantes.

A solução: habilidades de agentes

Para resolver isso, a Anthropic introduziu habilidades de agentes, mudando a arquitetura do carregamento de contexto monolítico para a divulgação progressiva. Em vez de forçar o modelo a "memorizar" cada fluxo de trabalho específico (como migrações de banco de dados ou auditorias de segurança) no início de uma sessão, esses recursos são empacotados em unidades modulares e detectáveis.

Como funciona

O modelo é inicialmente exposto apenas a um "menu" leve de metadados. Ele carrega o conhecimento processual 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 enxuto, rápido e econômico.

d3f4bcb065a19fea.png

3. Habilidades de agentes e Antigravity

No ecossistema do 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 do Gemini 3 e seu contexto específico. Elas 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 habilidades transformam a IA de um programador genérico em um especialista que adere rigorosamente às práticas recomendadas codificadas e aos padrões de segurança 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 capacidade 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 seja distraído por instruções irrelevantes. Em projetos grandes com dezenas de ferramentas, esse carregamento seletivo é crucial para a performance e a precisão do raciocínio.
  • Extensão de capacidade: as habilidades 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 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)

Embora o Protocolo de Contexto de Modelo (MCP, na sigla em inglês) funcione como as "mãos" do agente, fornecendo conexões persistentes e pesadas a sistemas externos, como GitHub ou PostgreSQL, as habilidades atuam como os "cérebros" que as direcionam.

O MCP processa a infraestrutura com estado, enquanto as habilidades são definições de tarefas leves e efêmeras que empacotam a metodologia para usar essas ferramentas. Essa abordagem sem servidor permite que os agentes executem tarefas ad hoc (como gerar registros de mudanças ou migrações) sem a sobrecarga operacional de processos persistentes, carregando o contexto somente 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 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 experiência específica necessária. Essa arquitetura permite uma capacidade de composição poderosa. Por exemplo, uma regra global pode impor o uso de uma habilidade de "migração segura" durante as 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ório 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, dependendo de formatos amplamente compreendidos, como Markdown e YAML, reduzindo a barreira de entrada para desenvolvedores que desejam 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 :

  1. Escopo do espaço de trabalho: 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 bancos de dados para esse app ou geração de código boilerplate para um framework proprietário.
  2. 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", "Analisar estilo de código" ou integração com ferramentas de produtividade pessoal.

Um diretório de habilidades típico é assim:

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 as preocupações 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:

  • YAML Frontmatter
  • Corpo de 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 do comando com 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, hífens 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. Funciona como a "frase de acionamento". 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" é insuficiente. 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 escolhida corretamente.

O corpo de markdown

O corpo contém as instruções. Essa é a "engenharia de comando" mantida em um arquivo. Quando a habilidade é ativada, esse conteúdo é injetado na janela de contexto do agente.

O corpo precisa incluir:

  1. Objetivo: uma declaração clara do que a habilidade realiza.
  2. Instruções: lógica detalhada.
  3. Exemplos: exemplos de poucas fotos de entradas e saídas para orientar a performance do modelo.
  4. Restrições: regras "não fazer" (por exemplo, "Não executar consultas DELETE").

Exemplo de corpo 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 das habilidades é 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 pelo caminho relativo.

5. Como criar habilidades

O objetivo desta seção é criar habilidades que se integrem ao Antigravity e mostrar progressivamente vários recursos, como recursos, scripts etc.

Faça o download das habilidades no repositório do GitHub aqui: https://github.com/rominirani/antigravity-skills.

Podemos considerar a colocação de cada uma dessas habilidades na pasta ~/.gemini/antigravity/skills ou na pasta /.agent/skills.

Nível 1 : o roteador básico ( git-commit-formatter )

Vamos considerar isso como o "Hello World" das habilidades.

Os desenvolvedores costumam escrever mensagens de confirmação preguiçosas, por exemplo, "wip", "fix bug", "updates". A aplicação manual de "commits convencionais" é tediosa e muitas vezes esquecida. Vamos implementar uma habilidade que aplique a especificação de commits convencionais. Ao simplesmente instruir o agente sobre as regras, permitimos que ele atue como o executor.

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:

  1. Faça uma pequena mudança em qualquer arquivo no seu espaço de trabalho.
  2. Abra o chat e digite: Commit these changes.
  3. O agente não vai apenas executar o commit do Git. Primeiro, ele vai ativar a habilidade git-commit-formatter.
  4. Resultado: uma mensagem de commit do Git convencional será proposta.

Por exemplo, fiz o Antigravity adicionar alguns comentários a um arquivo Python de amostra, 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 de "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 no texto legal.

Descarregue o texto estático para um arquivo de texto simples em uma pasta resources/. A habilidade instrui o agente a ler esse arquivo somente quando necessário.

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:

  1. Crie um novo arquivo Python fictício: touch my_script.py
  2. Digite: Add the license header to my_script.py.
  3. O agente vai ler license-header-adder/resources/HEADER_TEMPLATE.txt.
  4. Ele vai colar o conteúdo exatamente, literalmente, no seu arquivo.

Nível 3: aprendizado por exemplo (json-to-pydantic)

O padrão "Few-Shot".

A conversão de dados soltos (como uma resposta de 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 (Input -> Output) costuma ser 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:

  1. Forneça ao agente um snippet de JSON (cole-o no chat ou aponte para um arquivo).

{ "product": "Widget", "cost": 10.99, "stock": null }

  1. Digite: Convert this JSON to a Pydantic model.
  2. O agente analisa o par examples na pasta de habilidades.
  3. Ele gera uma classe Python que imita perfeitamente o estilo de codificação, as importações e a estrutura de output_model.py, incluindo o processamento do estoque nulo como opcional.

Um exemplo de saída (product_model.py) é mostrado abaixo:

from pydantic import BaseModel
from typing import Optional

class Product(BaseModel):
   product: str
   cost: float
   stock: Optional[int] = None

Nível 4: lógica processual (database-schema-validator)

Esse é o padrão de "uso de ferramentas".

Se você perguntar a um LLM "Esse esquema é seguro?", ele poderá dizer que tudo está bem, mesmo que uma chave primária crítica esteja ausente, simplesmente porque o SQL parece correto.

Vamos delegar essa verificação a um script determinístico. Usamos a habilidade para direcionar o agente a executar um script Python que escrevemos. O script fornece 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:

  1. Crie um arquivo SQL ruim bad_schema.sql: CREATE TABLE users (name TEXT);
  2. Digite: Validate bad_schema.sql.
  3. O agente não adivinha. 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 nas habilidades.

Tarefas complexas geralmente exigem uma sequência de operações que combinam tudo o que vimos: criação de arquivos, modelos e lógica de gravação. A criação de uma nova ferramenta para o ADK (Kit de Desenvolvimento de Agente) exige tudo isso.

Combinamos:

  • Script (para processar a criação/scaffolding 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 verificar os arquivos nas pastas 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:

  1. Digite: Create a new ADK tool called StockPrice to fetch data from an API.
  2. Etapa 1 (scaffolding): o agente executa o script Python. Isso cria instantaneamente StockPriceTool.py com a estrutura de classe correta, importações e nome de classe StockPriceTool.
  3. Etapa 2 (implementação): o agente "lê" o arquivo que acabou de criar. Ele vê # TODO: Implement logic.
  4. Etapa 3 (orientação): não sabe como definir o esquema JSON para os argumentos da ferramenta. Ele verifica examples/WeatherTool.py.
  5. Conclusão: ele edita o arquivo para adicionar requests.get(...) e define o argumento do ticker no esquema, correspondendo exatamente ao estilo do ADK.

6. Parabéns

Você concluiu o laboratório sobre habilidades do Antigravity 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.
  • Scaffolding de ferramentas do ADK.

As habilidades de agentes são uma ótima maneira de fazer com que o Antigravity escreva código do seu jeito, siga regras e use suas ferramentas.

Documentos de referência