Туториал по кастомным агентам Antigravity: создайте собственных специалистов
Превратите повторяющиеся задачи в сохранённых субагентов: один markdown-файл с YAML-frontmatter в .agents/agents, ограниченный список инструментов и правила, воркфлоу и навыки поверх — все скриншоты из реальной записи.
Коротко
- Кастомный агент — это один markdown-файл: YAML-frontmatter (name, description, model, tools) плюс тело с системным промптом — сохраните повторяющегося специалиста один раз и не объясняйте его заново каждую сессию.
- Агенты воркспейса лежат в .agents/agents/<имя>.md и уезжают вместе с репозиторием; личные в ~/.gemini/config/agents/ действуют во всех проектах машины.
- tools принимает точные имена инструментов Antigravity — view_file, grep_search, list_dir — неверное имя убивает агента на старте; subagent: true делает его делегируемым, mainAgent: true добавляет в селектор ввода.
- Быстрый тест — "What are your tools?" в селекторе IDE, делегирование из основного чата или проверка через /agents и Alt+J в CLI — затем надстройте правила, воркфлоу и навыки.
Google Antigravity Livestream: Remote Control and Custom Agents
Канал:Google Antigravity47:43
Antigravity Customization Features That 10X Your Coding Speed
Канал:Code A Program11:02
Defining Custom Subagents (.md) — Antigravity Docs
Документация:antigravity.googleDocs
Скриншоты — кадры из записи экрана Code A Program (указан выше); сам процесс создания файла агента документирован по официальному стриму Google и документации subagents Antigravity — чистой сторонней записи этого процесса пока нет.
При проверке фактов также использовались разборы кастомных агентов от Use AI with Tech Dad и AI with Surya. Все торговые марки принадлежат Google; это независимый туториал, не аффилированный с Google.
От пустой папки до надёжного специалиста
1 · Определите специалиста
- 1
Найдите роль, достойную сохранения
Кастомный агент заслуживает файл, когда одна и та же работа возвращается снова и снова: ревьюер кода с фиксированным чек-листом, обновляющий зависимости, гоняющий тесты, ведущий документацию. Если инструкции стабильны, заметно отличаются от универсального ассистента, а набор инструментов можно назвать заранее — сохраняйте роль. Разовые просьбы лучше оставить обычным промптом.
- 2
Чем он отличается от субагентов и навыков
Субагент — это рабочее место: сессия, которой ваш основной агент делегирует задачи. Кастомный агент — сохранённый профиль, который может занять это место — или с которым можно говорить напрямую. Навыки — отдельный слой: они упаковывают знания о задаче, доступные любому агенту, тогда как кастомный агент меняет собственные инструкции и доступ к инструментам. Для разового исполнителя файл не нужен: Antigravity умеет создавать временного субагента инструментом define_subagent прямо в сессии.
- 3
Выберите область: репозиторий или машина
Antigravity находит .md-файлы кастомных агентов в трёх местах. Настройки воркспейса лежат в .agents/agents/<имя>.md (или .agents/agents/<имя>/agent.md) и едут вместе с репозиторием — правильно для общих конвенций. Глобальные настройки лежат в ~/.gemini/config/agents/<имя>.md и действуют во всех проектах машины — правильно для личных специалистов. Плагины могут поставлять агентов в plugins/<имя_плагина>/agents/.
Страница Rules документации Antigravity: глобальные правила лежат в ~/.gemini/GEMINI.md и действуют во всех воркспейсах, правила воркспейса — в папке .agents — то же разделение, которому следуют файлы кастомных агентов.Смотреть на 0:30
2 · Напишите файл агента
- 4
Создайте файл агента
Внутри проекта создайте папку и файл одним движением — имя файла или папки становится идентичностью агента, поэтому строчными буквами и через дефис: .agents/agents/codereviewer/agent.md. Можно поручить скаффолдинг самому Antigravity: в официальном walkthrough один промпт «I have an idea for a custom agent» вернул полный путь undefined/.agents/agents/codereviewer/agent.md и готовое к правке определение.
- 5
Заполните YAML-frontmatter
Frontmatter объявляет личность и границы специалиста. name должен быть уникальным — именно его вы будете @упоминать. description сообщает Antigravity, когда специалиста следует вызывать, — пишите как объявление о вакансии. model: inherit сохраняет уровень модели родителя, а tools перечисляет ровно то, чем роль может пользоваться. Два флага достраивают картину: subagent по умолчанию true (агента можно делегировать), mainAgent по умолчанию false (поставьте true, чтобы выбирать специалиста прямо в селекторе ввода).
- 6
Напишите тело системного промпта
Всё ниже разделителя frontmatter становится системными инструкциями агента. Официальный пример открывается персоной ("You are an expert, meticulous Code Reviewer"), перечисляет ключевые обязанности — корректность, безопасность, производительность, стиль — и завершается строгим форматом вывода: вердикт Summary, блокирующие Critical findings со ссылками на строки и неблокирующие Suggestions. Стабильный формат отчёта делает результаты специалиста заслуживающими доверия.
---
name: codereviewer
description: >-
Code review specialist that analyzes diffs, inspects code for bugs,
architectural issues, performance bottlenecks, and style compliance.
model: inherit
tools:
- view_file
- grep_search
- list_dir
subagent: true
---
# Code Reviewer Persona & Instructions
You are an expert, meticulous Code Reviewer. Inspect proposed changes,
pull requests, and codebase files for correctness, security, performance,
and style.
## Review Output Format
- **Summary**: high-level assessment (LGTM / Changes Requested)
- **Critical findings**: blocking issues with line references and fixes
- **Suggestions & Improvements**: non-blocking refactors3 · Расширьте и ограничьте
- 7
Ограничьте инструментарий настоящими именами инструментов
Поле tools — явный белый список, имена должны совпадать с реальными инструментами Antigravity. В официальном walkthrough сгенерированный файл содержал read — и агент падал с "Agent execution terminated due to error", пока запись не исправили на view_file. Держитесь имён вроде view_file, grep_search и list_dir и давайте роли лишь необходимое; ревьюеру редко нужна запись.
Файл конфигурации воркспейса со списком инструментов, которые агент может вызывать, — view_file, grep_search, read_file — тот же словарь, что ожидает поле tools кастомного агента.Смотреть на 4:44 - 8
Решите, когда он работает
С subagent: true (по умолчанию) специалист доступен для делегирования: опишите задачу основному агенту, и он передаст ограниченную работу специалисту, чей отчёт вернётся в основной диалог. Делегированные субагенты наследуют границы разрешений родителя — допустимые команды, области файлов, настройки песочницы, — а требующие одобрения действия всплывают в основном интерфейсе. Включите ещё и mainAgent — специалист появится в селекторе ввода, готовый к прямому разговору.
- 9
Откройте Customizations и назовите правило
Кастомные агенты быстро умнеют от внутренних правил. В IDE откройте меню «...» вверху панели агента и выберите Customizations — в той же панели живут Rules и Workflows. В Rules создайте новое правило: глобальные правила лежат в ~/.gemini/GEMINI.md и действуют во всех воркспейсах, правила воркспейса — в папке .agents воркспейса или корня git. Файл правила ограничен 12 000 символов.
Панель Customizations в панели агента Antigravity: активна вкладка Rules, вводится имя нового правила, плейсхолдер — e.g. code-style-guide.Смотреть на 0:56 - 10
Выберите режим активации
Каждое правило отвечает на один вопрос: когда оно применяется? Always On подставляет его в каждый диалог; Manual ждёт @упоминания в поле ввода; Model Decision позволяет агенту включить его по описанию на естественном языке; Glob применяет правило только к файлам по шаблону вроде *.test.ts. Берите самый узкий работающий режим — правило ревьюера, срабатывающее только на диффах, остаётся сфокусированным.
Выпадающий список Activation Mode в редакторе правила Antigravity со всеми четырьмя вариантами — Always On, Manual, Model Decision и Glob.Смотреть на 1:04 - 11
Напишите содержимое правила
Правила — простые ограничения в Markdown: «комментарии объясняют, почему код существует, а не что он делает», «JSDoc для функций», «не оставляй TODO». Одно правило — одна мысль: агент читает их буквально в каждом подходящем диалоге. Правила формируют стиль работы специалиста; следующие два слоя дают ему процедуры и знания.
Файл правила comments.md в редакторе Antigravity, Activation Mode установлен на Always On, готов принять Markdown-инструкции для каждого диалога.Смотреть на 1:02 - 12
Упакуйте повторяющиеся процедуры в воркфлоу
Когда специалист должен повторять многошаговую процедуру — чистить слитые ветки, резать релиз, регенерировать документацию API — сохраните её воркфлоу вместо повторного набора шагов. Воркфлоу — это markdown-файлы с YAML-описанием во frontmatter, вызываемые слэш-командой: введите /cleanup-branches, и агент выполнит каждый перечисленный шаг.
Раздел Workflows документации Antigravity: файлы воркфлоу лежат в папке workflows каталога .agent и вызываются в чате командой /workflow-name.Смотреть на 5:40 - 13
Создайте файл воркфлоу
Попросите агента собрать каркас или сделайте сами: mkdir -p .agent/workflows, затем cleanup-branches.md с кратким описанием во frontmatter и нумерованным списком шагов. В записанном примере шаги идут от git fetch --prune до удаления слитых веток — и поскольку каждый шаг прописан явно, агент останавливается и спрашивает перед деструктивными действиями.
Диалог в Antigravity: агент выполняет mkdir -p .agent/workflows и nano, затем получает markdown воркфлоу — frontmatter с описанием и чек-лист из десяти шагов по git.Смотреть на 6:20
4 · Протестируйте, выкатите, разграничьте слои
- 14
Посмотрите, как работает предохранитель
Записанный запуск воркфлоу заканчивается тем, что агент отчитывается о полученной ветке, называет feature/about-page слитой и безопасной к удалению и спрашивает "Would you like me to proceed with deleting these?", прежде чем что-то трогать. Эта привычка к одобрению распространяется и на делегированных кастомных агентов: действия, требующие авторизации пользователя, всплывают в основном интерфейсе — специалист не пересекает границы молча.
Отчёт агента по воркфлоу: feature/about-page слита и безопасна для удаления, и агент спрашивает "Would you like me to proceed?" перед запуском git branch -d и git gc.Смотреть на 7:46 - 15
Научите его навыку
Правила формируют поведение; навыки добавляют знания. Навык — это папка с файлом SKILL.md: навыки воркспейса в .agents/skills/<имя-навыка>/, личные в ~/.gemini/skills. Name и description во frontmatter сообщают агенту, когда навык уместен; тело несёт полные инструкции, скрипты и справочники. Кастомные агенты и навыки сочетаются: ваш codereviewer может опираться на навык nextjs-reviewer для проверок, специфичных для фреймворка.
Раздел Agent Skills документации Antigravity: создайте папку в одном из каталогов навыков и добавьте файл SKILL.md с YAML-frontmatter.Смотреть на 8:42 - 16
Напишите frontmatter SKILL.md
Пишите description как триггер: "Reviews Next.js and TypeScript code for critical issues only — types, performance, security, and App Router patterns". Когда запрос совпадает, агент загружает навык целиком; когда нет — навык не мешает. Именно поэтому глубокие справочные материалы живут в навыке, а не в системном промпте агента.
SKILL.md навыка nextjs-reviewer в редакторе Antigravity: YAML-frontmatter содержит имя навыка и описание — Reviews Next.js and TypeScript code for critical issues only.Смотреть на 9:16 - 17
Посмотрите, как навык срабатывает на настоящем ревью
В записанной сессии просьба отревьюить код Next.js заставила агента загрузить навык ревьюера, проанализировать страницу и ответить структурированной рецензией: в Project Strengths отмечены типизированные утилиты и оптимизация шрифтов, а агент спросил "Would you like me to apply these fixes for you?" прежде чем редактировать. Ваш кастомный агент наследует эту дисциплину, если промпт требует того же формата вывода.
Агент-ревьюер за работой: перечисляет сильные стороны проекта — типизированные утилиты, next/image, паттерны App Router — и спрашивает, применять ли исправления.Смотреть на 10:15 - 18
Проверьте в IDE и в CLI
С mainAgent: true специалист появляется в селекторе ввода — выберите его и спросите "What are your tools?", чтобы проверить инструментарий; сломанный список tools мгновенно падает с ошибкой выполнения — это самый быстрый смоук-тест. В CLI команда /agents перечисляет обнаруженных агентов, а Alt+J открывает панель субагентов, где делегированная работа видна в реальном времени.
- 19
Закоммитьте папку, чтобы команда использовала тех же специалистов
Всё, что нужно специалисту, теперь в репозитории: .agents/agents/ для определений агентов плюс папка .agent с rules, skills и workflows рядом с исходниками. Закоммитьте — и каждый коллега и каждый запуск CI обнаружит тех же специалистов с теми же границами. Личные определения в ~/.gemini в репозиторий не попадают: это предпочтения уровня машины.
Проводник Antigravity с раскрытой папкой .agent — agent, rules, skills и workflows рядом с исходниками, готовые к коммиту.Смотреть на 9:04 - 20
Знайте, какой слой за что отвечает
Три слоя кастомизации дополняют файл агента, а не заменяют его: Rules — всегда включённые (или срабатывающие по шаблону) стандарты кода, Workflows — процедуры по слэш-команде, Skills — автоматически подхватываемые экспертные знания. Кастомный агент — это идентичность, которая их связывает: один markdown-файл, дающий повторяющейся работе имя, набор инструментов и память.
Сравнительная таблица Rules, Workflows и Skills: стандарты кода применяются автоматически, автоматизация задач — по слэш-командам, экспертные знания подхватываются по мере надобности.Смотреть на 10:20