Начало работы с навыками в Google Antigravity

1. Введение

Google Antigravity (далее в документе именуемая просто Antigravity) — это IDE для разработки ИИ-агентств от Google. В практическом занятии «Начало работы с Antigravity» вы можете изучить основы Antigravity. В этом занятии мы будем использовать Antigravity для создания навыков агентов — легковесного открытого формата для расширения возможностей ИИ-агентов с помощью специализированных знаний и рабочих процессов. Вы узнаете, что такое навыки агентов, их преимущества и как они создаются. Затем вы создадите несколько навыков агентов, начиная от форматировщика Git, генератора шаблонов, создания шаблонов кода и многого другого, — все это можно будет использовать в Antigravity.

Предварительные требования:

  • Приложение Google Antigravity установлено и настроено.
  • Базовое понимание Google Antigravity. Рекомендуется пройти практическое занятие: Начало работы с Google Antigravity .

2. Почему важны навыки?

Современные агенты ИИ эволюционировали от простых слушателей до сложных логических рассуждений, интегрирующихся с локальными файловыми системами и внешними инструментами (через MCP-серверы). Однако неизбирательная загрузка агента целыми кодовыми базами и сотнями инструментов приводит к насыщению контекста и «раздуванию инструментов». Даже при больших контекстных окнах, размещение 40–50 тысяч токенов неиспользуемых инструментов в активной памяти приводит к высокой задержке, финансовым потерям и «разложению контекста», когда модель начинает путаться из-за нерелевантных данных.

Решение: Навыки агентов

Для решения этой проблемы компания Anthropic представила Agent Skills , изменив архитектуру с монолитной загрузки контекста на прогрессивное раскрытие информации . Вместо того чтобы заставлять модель «запоминать» каждый конкретный рабочий процесс (например, миграцию баз данных или аудит безопасности) в начале сессии, эти возможности объединены в модульные, легко обнаруживаемые блоки.

Как это работает

Первоначально модель получает доступ только к облегченному «меню» метаданных. Сложные процедурные знания (инструкции и скрипты) загружаются только тогда, когда намерение пользователя точно соответствует навыку. Это гарантирует, что разработчик, желающий рефакторизовать промежуточное ПО аутентификации, получит контекст безопасности без загрузки несвязанных конвейеров CSS, что делает контекст лаконичным, быстрым и экономически эффективным.

d3f4bcb065a19fea.png

3. Навыки агента и антигравитация

В экосистеме Antigravity, если Agent Manager — это мозг, а Editor — холст, то Skills выступают в роли специализированных обучающих модулей, которые заполняют пробел между универсальной моделью Gemini 3 и вашим конкретным контекстом. Они позволяют агенту «оснащаться» определенным набором инструкций и протоколов — таких как стандарты миграции баз данных или проверки безопасности — только тогда, когда запрашивается соответствующая задача. Динамически загружая эти протоколы выполнения, Skills эффективно превращают ИИ из обычного программиста в специалиста, который строго придерживается кодифицированных передовых методов и стандартов безопасности организации.

Что такое навык в условиях антигравитации?

В контексте Google Antigravity навык представляет собой пакет, расположенный в каталоге и содержащий файл определения ( SKILL.md ) и необязательные вспомогательные ресурсы (скрипты, ссылки, шаблоны).

Это механизм для расширения возможностей по запросу.

  • Загрузка по запросу : В отличие от системной подсказки (которая всегда загружена), навык загружается в контекст агента только тогда, когда агент определяет, что он актуален для текущего запроса пользователя. Это оптимизирует контекстное окно и предотвращает отвлечение агента на нерелевантные инструкции. В крупных проектах с десятками инструментов такая выборочная загрузка имеет решающее значение для производительности и точности рассуждений.
  • Расширение возможностей : Навыки могут не только давать инструкции, но и выполнять действия. Благодаря включению скриптов Python или Bash, навык может предоставить агенту возможность выполнять сложные многоэтапные действия на локальном компьютере или во внешних сетях без необходимости ручного запуска команд пользователем. Это превращает агента из генератора текста в пользователя инструмента.

Навыки против экосистемы (инструменты, правила и рабочие процессы)

В то время как протокол контекста модели (MCP) выступает в роли «рук» агента, обеспечивая надежные и постоянные соединения с внешними системами, такими как GitHub или PostgreSQL, навыки действуют как «мозги», управляющие ими.

MCP управляет инфраструктурой с сохранением состояния, в то время как Skills представляют собой облегченные, временные определения задач, которые упаковывают методологию использования этих инструментов. Такой бессерверный подход позволяет агентам выполнять задачи по мере необходимости (например, генерацию журналов изменений или миграций) без операционных издержек, связанных с запуском постоянных процессов, загружая контекст только тогда, когда задача активна, и немедленно освобождая его после этого.

С функциональной точки зрения, навыки занимают уникальное промежуточное положение между «правилами» (пассивными, постоянно активными механизмами контроля) и «рабочими процессами» (активными макросами, запускаемыми пользователем). В отличие от рабочих процессов, требующих выполнения конкретных команд (например, /test ), навыки запускаются агентом : модель автоматически определяет намерение пользователя и динамически предоставляет необходимые специфические знания. Такая архитектура обеспечивает мощную компоновку; например, глобальное правило может обеспечивать использование навыка «Безопасная миграция» во время изменений в базе данных, или один рабочий процесс может координировать работу нескольких навыков для построения надежного конвейера развертывания.

4. Развитие навыков

Создание навыка в Antigravity осуществляется в соответствии со специфической структурой каталогов и форматом файлов. Такая стандартизация гарантирует переносимость навыков и возможность надежного анализа и выполнения их агентом. Дизайн намеренно упрощен и основан на широко распространенных форматах, таких как Markdown и YAML, что снижает порог вхождения для разработчиков, желающих расширить возможности своей IDE.

Структура каталогов

Навыки могут быть определены в двух рамках, что позволяет вносить изменения как в рамках конкретного проекта, так и в зависимости от потребностей пользователя:

  1. Область действия рабочей области : находится в <workspace-root>/.agent/skills/ . Эти навыки доступны только в рамках конкретного проекта. Это идеально подходит для скриптов, специфичных для проекта, таких как развертывание в определенной среде, управление базой данных для этого приложения или генерация шаблонного кода для проприетарного фреймворка.
  2. Глобальная область применения : находится в ~/.gemini/antigravity/skills/ . Эти навыки доступны для всех проектов на компьютере пользователя. Подходит для общих утилит, таких как «Форматирование JSON», «Генерация UUID», «Проверка стиля кода», или для интеграции с инструментами повышения личной производительности.

Типичная папка Skill выглядит следующим образом:

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)

Такая структура эффективно разделяет задачи. Логика ( scripts ) отделена от инструкций ( SKILL.md ) и знаний ( references ), что соответствует стандартным методам разработки программного обеспечения.

Файл определения SKILL.md

Файл SKILL.md — это «мозг» навыка. Он сообщает агенту, что представляет собой навык, когда его использовать и как его выполнить.

Оно состоит из двух частей:

  • YAML-заголовок
  • Текст сообщения в формате Markdown.

YAML-заголовок

Это слой метаданных. Это единственная часть навыка, которая индексируется высокоуровневым маршрутизатором агента. Когда пользователь отправляет запрос, агент семантически сопоставляет его с полями описания всех доступных навыков.

---
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.
---

Ключевые области:

  • Имя : Это необязательно. Должно быть уникальным в пределах области видимости. Допускаются строчные буквы и дефисы (например, postgres-query , pr-reviewer ). Если имя не указано, будет использоваться имя каталога по умолчанию.
  • Описание : Это обязательное и наиболее важное поле. Оно служит «ключевой фразой». Оно должно быть достаточно подробным, чтобы специалист в области управления знаниями (LLM) смог определить семантическую значимость. Расплывчатое описание, например, «Инструменты базы данных», недостаточно. Точное описание, например, «Выполняет SQL-запросы только для чтения к локальной базе данных PostgreSQL для получения данных о пользователях или транзакциях. Используйте это для отладки состояний данных», гарантирует правильное освоение навыка.

Текст сообщения в формате Markdown

В теле документа содержатся инструкции. Это «оперативная разработка», сохраненная в файле. При активации навыка это содержимое внедряется в контекстное окно агента.

В тексте должны быть указаны следующие сведения:

  1. Цель: Четко сформулировать, чего можно достичь с помощью данного навыка.
  2. Инструкции: Пошаговая логика.
  3. Примеры: Несколько примеров входных и выходных данных для оценки производительности модели.
  4. Ограничения: правила «Не выполнять» (например, «Не выполнять запросы DELETE»).

Пример содержимого файла 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.

Интеграция скриптов

Одна из самых мощных функций Skills — это возможность делегировать выполнение скриптам. Это позволяет агенту выполнять действия, которые сложно или невозможно выполнить напрямую с помощью LLM (например, выполнение бинарных команд, сложные математические вычисления или взаимодействие с устаревшими системами).

Скрипты размещаются в подкаталоге scripts/ . В файле SKILL.md они указаны по относительному пути.

5. Навыки создания контента

Цель этого раздела — разработка навыков, интегрирующихся в Antigravity, и постепенное отображение различных функций, таких как ресурсы, скрипты и т. д.

Скачать навыки можно из репозитория Github здесь: https://github.com/rominirani/antigravity-skills .

Мы можем рассмотреть возможность размещения каждого из этих навыков либо в папке ~/.gemini/antigravity/skills , либо в папке /.agent/skills .

Уровень 1: Базовый маршрутизатор ( git-commit-formatter )

Давайте рассмотрим это как "Привет, мир" навыков.

Разработчики часто пишут ленивые сообщения для коммитов, например, "в процессе", "исправить ошибку", "обновления". Ручное обеспечение соблюдения "стандартных коммитов" утомительно и часто забывается. Давайте реализуем навык, который будет обеспечивать соблюдение спецификации "стандартных коммитов". Просто проинструктировав агента о правилах, мы позволим ему действовать в качестве исполнителя.

git-commit-formatter/
└── SKILL.md  (Instructions only)

Ниже представлен файл SKILL.md :

---
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`

Как запустить этот пример:

  1. Внесите небольшие изменения в любой файл в вашей рабочей области.
  2. Откройте чат и введите: Подтвердите эти изменения.
  3. Агент не просто выполнит команду `git commit`. Сначала он активирует навык `git-commit-formatter`.
  4. Результат: Будет предложено стандартное сообщение коммита Git.

Например, я заставил Antigravity добавить комментарии к тестовому файлу Python, и в результате получился коммит Git в виде сообщения типа docs: add detailed comments to demo_primes.py.

Уровень 2: Использование активов (заголовок лицензии)

Это шаблон "Reference".

В каждом исходном файле корпоративного проекта может потребоваться специальный 20-строчный заголовок лицензии Apache 2.0. Вставлять этот статический текст непосредственно в командную строку (или файл SKILL.md ) неэффективно. Это расходует токены каждый раз при индексации навыка, и модель может «выдавать» опечатки в юридическом тексте.

Выгрузка статического текста в текстовый файл в папке resources/ . Навык дает агенту указание читать этот файл только при необходимости.

Преобразование неструктурированных данных (например, ответа JSON API) в строгий код (например, модели Pydantic) включает в себя десятки решений. Как следует называть классы? Использовать ли Optional ? snake_case или camelCase ? Записывать эти 50 правил на английском языке утомительно и чревато ошибками.

LLM — это системы сопоставления шаблонов.

Показ им наглядного примера (ввод -> вывод) зачастую эффективнее, чем подробные инструкции.

license-header-adder/
├── SKILL.md
└── resources/
   └── HEADER_TEMPLATE.txt  (The heavy text)

Ниже представлен файл SKILL.md :

---
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 `<!-- ... -->`.

Как запустить этот пример:

  1. Создайте новый фиктивный файл Python: touch my_script.py
  2. Тип: Add the license header to my_script.py .
  3. Агент прочтёт файл license-header-adder/resources/HEADER_TEMPLATE.txt .
  4. Содержимое будет вставлено в ваш файл в точности, слово в слово.

Уровень 3: Обучение на примерах (json-to-pydantic)

Схема "Мало выстрелов".

Преобразование неструктурированных данных (например, ответа JSON API) в строгий код (например, модели Pydantic) включает в себя десятки решений. Как следует называть классы? Использовать ли Optional ? snake_case или camelCase ? Записывать эти 50 правил на английском языке утомительно и чревато ошибками.

LLM-ы — это системы сопоставления шаблонов. Демонстрация им эталонного примера (вход -> выход) часто оказывается эффективнее, чем подробные инструкции.

json-to-pydantic/
├── SKILL.md
└── examples/
   ├── input_data.json   (The Before State)
   └── output_model.py   (The After State)

Ниже представлен файл SKILL.md : 

---
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`.

В папке /examples находятся JSON-файл и выходной файл, то есть файл Python. Оба файла показаны ниже:

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

Как запустить этот пример:

  1. Предоставьте агенту фрагмент JSON-кода (вставьте его в чат или укажите путь к файлу).

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

  1. Тип: Convert this JSON to a Pydantic model .
  2. Агент просматривает пары examples в папке навыков.
  3. Он генерирует класс Python, который идеально имитирует стиль кодирования, импорт и структуру файла output_model.py , включая обработку значения null для stock как Optional.

Пример выходных данных ( product_model.py ) показан ниже: 

from pydantic import BaseModel
from typing import Optional

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

Уровень 4: Процедурная логика (база данных-схема-валидатор)

Это шаблон "Использование инструмента".

Если вы спросите магистра права: «Безопасна ли эта схема?», он, скорее всего, ответит, что всё в порядке, даже если отсутствует критически важный первичный ключ, просто потому что SQL-запрос выглядит корректным.

Давайте делегируем эту проверку детерминированному скрипту. Мы используем навык, чтобы направить агента на выполнение написанного нами скрипта на Python. Скрипт предоставляет бинарную (истина/ложь) истину. 

database-schema-validator/
├── SKILL.md
└── scripts/
   └── validate_schema.py  (The Validator)

Ниже представлен файл SKILL.md : 

---
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.

Ниже представлен файл validate_schema.py : 

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])

Как запустить этот пример:

  1. Создайте некорректный SQL-файл bad_schema.sql : CREATE TABLE users (name TEXT);
  2. Тип: Validate bad_schema.sql .
  3. Агент не гадает. Он запустит скрипт, который завершится с ошибкой (код выхода 1), и сообщит нам: «Проверка не удалась, потому что в таблице 'users' отсутствует первичный ключ».

Уровень 5: Архитектор (adk-tool-scaffold)

Данная схема охватывает большинство функций, доступных в разделе «Навыки».

Сложные задачи часто требуют последовательности операций, объединяющих все, что мы рассмотрели: создание файлов, следование шаблонам и написание логики. Создание нового инструмента для ADK (комплекта разработки агентов) требует всего этого.

Мы объединяем:

  • Скрипт (для обработки создания/генерации структуры файлов)
  • Шаблон (для обработки шаблонного кода в ресурсах)
  • Пример (для наглядного примера построения логики). 
adk-tool-scaffold/
├── SKILL.md
├── resources/
│   └── ToolTemplate.py.hbs (Jinja2 Template)
├── scripts/
│   └── scaffold_tool.py    (Generator Script)
└── examples/
    └── WeatherTool.py      (Reference Implementation)

Файл SKILL.md показан ниже. Вы можете обратиться к репозиторию навыков , чтобы проверить файлы в папках scripts, resources и examples. Для этого конкретного навыка перейдите к навыку 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.

Как запустить этот пример:

  1. Тип: Create a new ADK tool called StockPrice to fetch data from an API .
  2. Шаг 1 (Создание каркаса): Агент запускает скрипт Python. Это мгновенно создает файл StockPriceTool.py с правильной структурой классов, импортами и именем класса StockPriceTool .
  3. Шаг 2 (Реализация): Агент «читает» только что созданный файл. Он видит # TODO: Implement logic.
  4. Шаг 3 (Рекомендации): Неясно, как определить JSON-схему для аргументов инструмента. Проверяется examples/WeatherTool.py .
  5. Завершение: В файл вносятся изменения, добавляющие requests.get(...) и определяющие аргумент ticker в схеме, точно соответствующие стилю ADK.

6. Поздравляем!

Вы успешно завершили лабораторную работу по навыкам антигравитации и развили следующие навыки:

  • Форматировщик коммитов Git.
  • Добавление заголовка лицензии.
  • Преобразование JSON в Pydantic.
  • Валидатор схемы базы данных.
  • Генерация шаблонов для инструментов ADK.

Навыки агентов — это, безусловно, отличный способ заставить Antigravity писать код по-вашему, следовать правилам и использовать ваши инструменты.

Справочная документация