1. Introduzione
Google Antigravity (denominato Antigravity per il resto del documento) è un IDE autonomo di Google. In Introduzione al codelab Antigravity, puoi imparare le nozioni di base di Antigravity. In questo codelab, utilizzeremo Antigravity per creare le competenze dell'agente, un formato aperto e leggero per estendere le funzionalità dell'agente AI con conoscenze e flussi di lavoro specializzati. Potrai scoprire cosa sono le competenze dell'agente, i loro vantaggi e come vengono create. Successivamente, creerai più competenze dell'agente, tra cui un formattatore Git, un generatore di modelli, uno scaffolding del codice dello strumento e altro ancora, tutti utilizzabili in Antigravity.
Prerequisiti:
- Google Antigravity installato e configurato.
- Conoscenza di base di Google Antigravity. Ti consigliamo di completare il codelab Introduzione a Google Antigravity.
2. Perché le competenze
Gli agenti AI moderni si sono evoluti da semplici ascoltatori a complessi ragionatori che si integrano con i file system locali e gli strumenti esterni (tramite i server MCP). Tuttavia, caricare indiscriminatamente un agente con intere codebase e centinaia di strumenti porta alla saturazione del contesto e all'eccessivo utilizzo di strumenti. Anche con finestre contestuali di grandi dimensioni, il dumping di 40-50.000 token di strumenti inutilizzati nella memoria attiva causa latenza elevata, spreco finanziario e "decadimento del contesto", in cui il modello viene confuso da dati irrilevanti.
La soluzione: competenze dell'agente
Per risolvere questo problema, Anthropic ha introdotto le Agent Skills, spostando l'architettura dal caricamento del contesto monolitico alla Progressive Disclosure. Anziché forzare il modello a "memorizzare" ogni flusso di lavoro specifico (come le migrazioni di database o i controlli di sicurezza) all'inizio di una sessione, queste funzionalità sono raggruppate in unità modulari e rilevabili.
Come funziona
Inizialmente, il modello viene esposto solo a un "menu" leggero di metadati. Carica le conoscenze procedurali pesanti (istruzioni e script) solo quando l'intent dell'utente corrisponde in modo specifico a un'abilità. In questo modo, uno sviluppatore che chiede di eseguire il refactoring del middleware di autenticazione ottiene il contesto di sicurezza senza caricare pipeline CSS non correlate, mantenendo il contesto snello, veloce ed economico.

3. Abilità degli agenti e antigravità
Nell'ecosistema Antigravity, se l'Agent Manager è il cervello e l'Editor è la tela, le Competenze fungono da moduli di addestramento specializzati che colmano il divario tra il modello generalista Gemini 3 e il tuo contesto specifico. Consentono all'agente di "dotarsi" di un insieme definito di istruzioni e protocolli, come standard di migrazione del database o controlli di sicurezza, solo quando viene richiesta un'attività pertinente. Caricando dinamicamente questi protocolli di esecuzione, le competenze trasformano efficacemente l'AI da programmatore generico in uno specialista che aderisce rigorosamente alle best practice e agli standard di sicurezza codificati di un'organizzazione.
Che cos'è un'abilità in Antigravity?
Nel contesto di Google Antigravity, una skill è un pacchetto basato su directory contenente un file di definizione (SKILL.md) e risorse di supporto facoltative (script, riferimenti, modelli).
È un meccanismo per l'estensione delle funzionalità on demand.
- On Demand: a differenza di un prompt di sistema (che viene sempre caricato), una skill viene caricata nel contesto dell'agente solo quando l'agente determina che è pertinente alla richiesta corrente dell'utente. In questo modo, la finestra contestuale viene ottimizzata e l'agente non viene distratto da istruzioni non pertinenti. Nei progetti di grandi dimensioni con decine di strumenti, questo caricamento selettivo è fondamentale per le prestazioni e l'accuratezza del ragionamento.
- Estensione delle funzionalità: le skill possono fare molto di più che dare istruzioni, possono eseguire azioni. Raggruppando script Python o Bash, una skill può dare all'agente la possibilità di eseguire azioni complesse in più passaggi sulla macchina locale o su reti esterne senza che l'utente debba eseguire manualmente i comandi. In questo modo, l'agente non è più un generatore di testo, ma un utente di strumenti.
Competenze e ecosistema (strumenti, regole e flussi di lavoro)
Mentre il protocollo Model Context Protocol (MCP) funge da "mani " dell'agente, fornendo connessioni persistenti e resistenti a sistemi esterni come GitHub o PostgreSQL, le competenze fungono da "cervello" che le dirige.
MCP gestisce l'infrastruttura stateful, mentre le competenze sono definizioni di attività leggere ed effimere che raggruppano la metodologia per l'utilizzo di questi strumenti. Questo approccio serverless consente agli agenti di eseguire attività ad hoc (come la generazione di changelog o migrazioni) senza l'overhead operativo dell'esecuzione di processi persistenti, caricando il contesto solo quando l'attività è attiva e rilasciandolo immediatamente dopo.
A livello funzionale, le competenze occupano una posizione intermedia unica tra le "Regole" (protezioni passive e sempre attive) e i "Flussi di lavoro" (macro attive attivate dall'utente). A differenza dei flussi di lavoro che richiedono comandi specifici (ad es. /test), le competenze sono attivate dall'agente: il modello rileva automaticamente l'intenzione dell'utente e fornisce dinamicamente le competenze specifiche richieste. Questa architettura consente una composizione potente. Ad esempio, una regola globale può imporre l'utilizzo di una competenza "Safe-Migration" durante le modifiche al database oppure un singolo flusso di lavoro può orchestrare più competenze per creare una pipeline di deployment solida.
4. Creazione di competenze
La creazione di una skill in Antigravity segue una struttura di directory e un formato di file specifici. Questa standardizzazione garantisce che le competenze siano portabili e che l'agente possa analizzarle ed eseguirle in modo affidabile. Il design è intenzionalmente semplice e si basa su formati ampiamente compresi come Markdown e YAML, riducendo la barriera all'ingresso per gli sviluppatori che vogliono estendere le funzionalità del proprio IDE.
Struttura delle directory
Le competenze possono essere definite in due ambiti, consentendo personalizzazioni specifiche per il progetto e per l'utente :
- Workspace Scope: si trova in
<workspace-root>/.agent/skills/. Queste competenze sono disponibili solo all'interno del progetto specifico. Questa opzione è ideale per gli script specifici del progetto, ad esempio il deployment in un ambiente specifico, la gestione del database per l'app o la generazione di codice boilerplate per un framework proprietario. - Ambito globale: si trova in
~/.gemini/antigravity/skills/. Queste competenze sono disponibili in tutti i progetti sulla macchina dell'utente. È adatto a utilità generali come "Formatta JSON", "Genera UUID", "Rivedi stile del codice" o all'integrazione con strumenti di produttività personale.
Una tipica directory delle skill ha questo aspetto:
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)
Questa struttura separa efficacemente le problematiche. La logica (scripts) è separata dall'istruzione (SKILL.md) e dalla conoscenza (references), rispecchiando le pratiche standard di ingegneria del software.
Il file di definizione SKILL.md
Il file SKILL.md è il cervello della skill. Indica all'agente cos'è la skill, quando utilizzarla e come eseguirla.
È composto da due parti:
- Frontmatter YAML
- Corpo in Markdown.
YAML Frontmatter
Questo è il livello dei metadati. È l'unica parte della skill indicizzata dal router di primo livello dell'agente. Quando un utente invia un prompt, l'agente esegue la corrispondenza semantica del prompt con i campi di descrizione di tutte le skill disponibili.
---
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.
---
Campi chiave:
- name: questo campo non è obbligatorio. Deve essere univoco nell'ambito. Sono consentite lettere minuscole e trattini (ad es.
postgres-query,pr-reviewer). Se non viene fornito, il valore predefinito sarà il nome della directory. - description: questo campo è obbligatorio ed è il più importante. Funziona come "frase di attivazione". Deve essere sufficientemente descrittivo per consentire all'LLM di riconoscere la pertinenza semantica. Una descrizione vaga come "Strumenti di database" non è sufficiente. Una descrizione precisa come "Esegue query SQL di sola lettura sul database PostgreSQL locale per recuperare dati di utenti o transazioni. Utilizza questa opzione per il debug degli stati dei dati" garantisce che la skill venga rilevata correttamente.
The Markdown Body
Il corpo contiene le istruzioni. Si tratta di "prompt engineering" salvato in un file. Quando la skill viene attivata, questi contenuti vengono inseriti nella finestra di contesto dell'agente.
Il corpo deve includere:
- Obiettivo: una dichiarazione chiara di ciò che la skill ottiene.
- Istruzioni: logica passo passo.
- Esempi: esempi few-shot di input e output per guidare le prestazioni del modello.
- Vincoli: regole "Non" (ad es. "Non eseguire query DELETE").
Esempio di corpo del file 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.
Integrazione di script
Una delle funzionalità più potenti delle skill è la possibilità di delegare l'esecuzione agli script. Ciò consente all'agente di eseguire azioni difficili o impossibili da eseguire direttamente per un LLM (come l'esecuzione di file binari, calcoli matematici complessi o l'interazione con sistemi legacy).
Gli script vengono inseriti nella sottodirectory scripts/. SKILL.md fa riferimento a questi file tramite il percorso relativo.
5. Competenze di creazione
Lo scopo di questa sezione è sviluppare competenze che si integrino in Antigravity e mostrino progressivamente varie funzionalità come risorse, script e così via.
Puoi scaricare le skill dal repository GitHub qui: https://github.com/rominirani/antigravity-skills.
Possiamo esaminare il posizionamento di ciascuna di queste competenze all'interno della cartella ~/.gemini/antigravity/skills o della cartella /.agent/skills.
Livello 1 : il router di base ( git-commit-formatter )
Consideriamolo come l'equivalente di "Hello World" per le skill.
Gli sviluppatori spesso scrivono messaggi di commit pigri, ad esempio "wip", "fix bug", "updates". L'applicazione manuale di "Conventional Commits" è noiosa e spesso dimenticata. Implementiamo una competenza che applichi la specifica Conventional Commits. Basta istruire l'agente sulle regole per consentirgli di agire come responsabile dell'applicazione.
git-commit-formatter/
└── SKILL.md (Instructions only)
Il file SKILL.md è mostrato di seguito:
---
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`
Come eseguire questo esempio:
- Apporta una piccola modifica a un file qualsiasi dello spazio di lavoro.
- Apri la chat e digita: Esegui il commit di queste modifiche.
- L'agente non eseguirà solo il commit Git. Verrà attivata prima la skill git-commit-formatter.
- Risultato: verrà proposto un messaggio di commit Git convenzionale.
Ad esempio, ho chiesto ad Antigravity di aggiungere alcuni commenti a un file Python di esempio e ho ottenuto un messaggio di commit Git come docs: add detailed comments to demo_primes.py.
Livello 2: utilizzo degli asset (license-header-adder)
Questo è il pattern "Riferimento".
Ogni file sorgente di un progetto aziendale potrebbe richiedere un'intestazione di licenza Apache 2.0 specifica di 20 righe. Inserire questo testo statico direttamente nel prompt (o in SKILL.md) è uno spreco. Consuma token ogni volta che la skill viene indicizzata e il modello potrebbe "allucinare" errori di battitura nel testo legale.
Spostando il testo statico in un file di testo normale in una cartella resources/. La competenza indica all'agente di leggere questo file solo quando necessario.
La conversione di dati non strutturati (come una risposta API JSON) in codice strutturato (come i modelli Pydantic) comporta decine di decisioni. Come dobbiamo chiamare i corsi? Dobbiamo usare Optional? snake_case o camelCase? Scrivere queste 50 regole in inglese è noioso e soggetto a errori.
Gli LLM sono motori di corrispondenza di pattern.
Mostrare un esempio perfetto (input -> output) è spesso più efficace di istruzioni dettagliate.
license-header-adder/
├── SKILL.md
└── resources/
└── HEADER_TEMPLATE.txt (The heavy text)
Il file SKILL.md è mostrato di seguito:
---
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 `<!-- ... -->`.
Come eseguire questo esempio:
- Crea un nuovo file Python fittizio:
touch my_script.py - Tipo:
Add the license header to my_script.py. - L'agente leggerà
license-header-adder/resources/HEADER_TEMPLATE.txt. - I contenuti verranno incollati esattamente, parola per parola, nel file.
Livello 3: apprendimento tramite esempi (json-to-pydantic)
Il pattern "Few-Shot".
La conversione di dati non strutturati (come una risposta API JSON) in codice strutturato (come i modelli Pydantic) comporta decine di decisioni. Come dobbiamo chiamare i corsi? Dobbiamo usare Optional? snake_case o camelCase? Scrivere queste 50 regole in inglese è noioso e soggetto a errori.
Gli LLM sono motori di corrispondenza di pattern. Mostrare un esempio perfetto (input -> output) è spesso più efficace di istruzioni dettagliate.
json-to-pydantic/
├── SKILL.md
└── examples/
├── input_data.json (The Before State)
└── output_model.py (The After State)
Il file SKILL.md è mostrato di seguito:
---
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`.
Nella cartella /examples sono presenti il file JSON e il file di output , ovvero il file Python. Entrambi sono mostrati di seguito:
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
Come eseguire questo esempio:
- Fornisci all'agente uno snippet di JSON (incollalo nella chat o indica un file).
{ "product": "Widget", "cost": 10.99, "stock": null }
- Tipo:
Convert this JSON to a Pydantic model. - L'agente esamina la coppia
examplesnella cartella dell'intent. - Genera una classe Python che imita perfettamente lo stile di codifica, le importazioni e la struttura di
output_model.py, inclusa la gestione dello stock nullo come Optional.
Di seguito è riportato un output di esempio (product_model.py):
from pydantic import BaseModel
from typing import Optional
class Product(BaseModel):
product: str
cost: float
stock: Optional[int] = None
Livello 4: logica procedurale (database-schema-validator)
Questo è il pattern "Utilizzo degli strumenti".
Se chiedi a un LLM "Questo schema è sicuro?", potrebbe rispondere che va tutto bene, anche se manca una chiave primaria critica, semplicemente perché l'SQL sembra corretto.
Deleghiamo questo controllo a uno script deterministico. Utilizziamo la competenza per indirizzare l'agente all'esecuzione di uno script Python che abbiamo scritto. Lo script fornisce un valore di verità binario (True/False).
database-schema-validator/
├── SKILL.md
└── scripts/
└── validate_schema.py (The Validator)
Il file SKILL.md è mostrato di seguito:
---
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.
Il file validate_schema.py è mostrato di seguito:
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])
Come eseguire questo esempio:
- Crea un file SQL non valido
bad_schema.sql:CREATE TABLE users (name TEXT); - Tipo:
Validate bad_schema.sql. - L'agente non fa ipotesi. Verrà richiamato lo script, che non andrà a buon fine (codice di uscita 1) e ci verrà comunicato che "La convalida non è riuscita perché nella tabella "users" manca una chiave primaria".
Livello 5: The Architect (adk-tool-scaffold)
Questo pattern copre la maggior parte delle funzionalità disponibili in Skills.
Le attività complesse spesso richiedono una sequenza di operazioni che combinano tutto ciò che abbiamo visto: creazione di file, utilizzo di modelli e scrittura di logica. Per creare un nuovo strumento per l'ADK (Agent Development Kit) è necessario tutto questo.
Combiniamo:
- Script (per gestire la creazione/l'impalcatura del file)
- Modello (per gestire il boilerplate nelle risorse)
- Un esempio (per guidare la generazione della logica).
adk-tool-scaffold/
├── SKILL.md
├── resources/
│ └── ToolTemplate.py.hbs (Jinja2 Template)
├── scripts/
│ └── scaffold_tool.py (Generator Script)
└── examples/
└── WeatherTool.py (Reference Implementation)
Il file SKILL.md è mostrato di seguito. Puoi fare riferimento al repository di skill per controllare i file nelle cartelle script, risorse ed esempi. Per questa skill specifica, vai alla skill 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.
Come eseguire questo esempio:
- Tipo:
Create a new ADK tool called StockPrice to fetch data from an API. - Passaggio 1 (impalcatura): l'agente esegue lo script Python. In questo modo viene creato immediatamente
StockPriceTool.pycon la struttura, le importazioni e il nome del corso correttiStockPriceTool. - Passaggio 2 (implementazione): l'agente "legge" il file appena creato. Vede
# TODO: Implement logic. - Passaggio 3 (indicazioni): non è chiaro come definire lo schema JSON per gli argomenti dello strumento. Controlla
examples/WeatherTool.py. - Completamento: modifica il file per aggiungere
requests.get(...)e definisce l'argomento ticker nello schema, in modo che corrisponda esattamente allo stile ADK.
6. Complimenti
Hai completato correttamente il lab su Antigravity Skills e creato le seguenti skill:
- Formattatore di commit Git.
- Componente aggiuntivo per l'intestazione della licenza.
- JSON a Pydantic.
- Convalida dello schema del database.
- Struttura dello strumento ADK.
Le competenze dell'agente sono sicuramente un ottimo modo per consentire ad Antigravity di scrivere codice a modo tuo, seguire le regole e utilizzare i tuoi strumenti.
Documenti di riferimento
- Codelab : Guida introduttiva a Google Antigravity
- Sito ufficiale : https://antigravity.google/
- Documentazione: https://antigravity.google/docs
- Download : https://antigravity.google/download
- Documentazione sulle competenze di Antigravity: https://antigravity.google/docs/skills