Agent Skills vs MCP: разбираемся на примере Antigravity

В этой статье предполагается, что вы знакомы с Google Antigravity — агентной платформой, которая развивает IDE в сторону парадигмы с приоритетом агентов. Платформа полностью поддерживает параллельный запуск агентов, способных рассуждать и выполнять задачи от имени пользователя, опираясь на передовые модели рассуждений, такие как Gemini.

Зачем нужны Skills?

Если вы предпочитаете изучать Google Antigravity Skills в формате пошагового codelab, перейдите сюда.

Прежде чем углубляться в Skills и разбираться, зачем они нужны, давайте поймём, как мы к этому пришли.

Если немного отстраниться и посмотреть на Google Antigravity и другие аналогичные агентные AI-платформы, становится ясно, что это уже не просто «слушатели», исполняющие жёстко заданные команды. Это системы, способные интерпретировать намерения пользователя, планировать многошаговые рабочие процессы и выполнять сложные задачи с определённой степенью автономности.

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

И здесь мы подходим к проблеме перенасыщения контекста. Хотя современные модели, такие как Gemini 2.5/3, могут похвастаться контекстными окнами размером более миллиона токенов, бездумная загрузка в активную память модели всего кодовой базы, документации и набора инструментов приводит к серьёзным задержкам и финансовым издержкам. Не говоря уже о «гниении контекста», из-за которого качество рассуждений падает, поскольку модель начинает путаться.

Kurtis Van Gent хорошо разбирает проблему эпидемии разрастания инструментов в статье «Stop Drowning Your Agent in Tools».

Я кратко перескажу несколько ключевых моментов из этой статьи. Посмотрите на объём инструментов, которыми мы нагружаем агента. Например: MCP-сервер GitHub (50 инструментов), MCP-сервер Playwright (24 инструмента) и MCP-сервер Chrome DevTools (26 инструментов). В итоге агенту загружаются сотни инструментов, что потребляет 40–50 тысяч токенов контекста, при том что в конкретном запросе может использоваться всего один инструмент. Теперь становится ясно, к чему приводят разрастание инструментов, путаница агента, гниение контекста, рост задержек и другие проблемы.

Рассмотрим реальный пример. Когда разработчик просит агента «отрефакторить middleware аутентификации», от агента требуется глубокое понимание конкретных протоколов безопасности и структуры файлов. При этом ему совершенно не нужен контекст CSS-пайплайна сборки проекта или маркетинговых материалов.

Anthropic представляет Skills

Чтобы решить эту проблему, Anthropic предложила новый стандарт — Agent Skills. Согласно определению:

Agent Skills — это лёгкий, открытый формат для расширения возможностей AI-агентов за счёт специализированных знаний и рабочих процессов.

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

И это ключевой момент → модели предоставляется лишь лёгкое «меню» таких возможностей (метаданные), а тяжёлые процедурные знания (инструкции и скрипты) подгружаются только тогда, когда намерение пользователя соответствует конкретному skill. Это позволяет избежать разрастания инструментов, удерживать контекст на минимальном уровне и, что немаловажно, экономически оправдано.

Изображение ниже должно помочь понять, как это работает:

Agent Skills и Antigravity

Учитывая, что мы работаем с Antigravity, где же «skill» вписывается в его архитектуру? Если Agent Manager — это мозг, а редактор — холст, то Skills представляют собой специализированные обучающие модули. По умолчанию агент знает основы программирования (благодаря базовой модели Gemini 3) и умеет пользоваться базовыми инструментами (терминал, файловый ввод-вывод). Однако он не знает ваш конкретный контекст.

Skill выступает в роли моста. Это чётко определённый набор инструкций и возможностей, которые агент может «экипировать» для обработки определённых типов запросов. Когда пользователь просит агента «запустить миграцию базы данных», агент просматривает доступные ему Skills (глобальные или привязанные к рабочему пространству). Если он находит skill для миграции базы данных, агент загружает соответствующие инструкции и протоколы выполнения в своё контекстное окно. Это позволяет агенту выполнить задачу не просто корректно в общем смысле, а в строгом соответствии с конкретными стандартами и протоколами безопасности, определёнными командой разработки.

По сути, Skills превращают универсальную модель Gemini в специалиста. Они позволяют организации формализовать лучшие практики — проверки безопасности, предпочтения по стилю кода, шаги деплоя — в виде исполняемых артефактов, которым ИИ следует неукоснительно.

Теперь давайте подробнее разберём, из чего состоит skill, определив его в контексте инструмента Antigravity.

Antigravity Skills: концепции и различия

Официальная документация по Antigravity Skills доступна здесь: https://antigravity.google/docs/skills

Крайне важно точно определить, что такое Skill в рамках Antigravity и чем он отличается от смежных понятий — Rules, Workflows и MCP-серверов.

Дисклеймер: документации по этой теме пока немного, и я предполагаю, что в ближайшее время появится больше ясности и лучших практик в Antigravity относительно того, когда использовать Skills, а когда — Rules/Workflows, а также как корректно интегрировать их с MCP-серверами. Я могу ошибаться в некоторых из приведённых ниже тезисов и буду признателен за обратную связь.

Что такое Skill?

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

• По требованию: в отличие от System Prompt, который загружается всегда, Skill подгружается в контекст агента только тогда, когда агент определяет его релевантность текущему запросу пользователя. Это оптимизирует использование контекстного окна и предотвращает отвлечение агента нерелевантными инструкциями. В крупных проектах с десятками инструментов такая избирательная загрузка критически важна для производительности и точности рассуждений.

• Расширение возможностей: Skills могут не только инструктировать, но и выполнять действия. За счёт включения Python- или Bash-скриптов Skill может дать агенту возможность выполнять сложные многошаговые операции на локальной машине или во внешних сетях без необходимости ручного запуска команд пользователем. Это превращает агента из генератора текста в полноценного пользователя инструментов.

Skills и Model Context Protocol (MCP)

Одним из самых распространённых источников путаницы является различие между Skills и Model Context Protocol (MCP). Оба механизма расширяют возможности агента, но решают разные задачи и используют разные архитектурные подходы.

Antigravity Skills лучше всего понимать как лёгкие, эфемерные определения задач. Они не требуют серверов и основаны на файлах. При вызове skill агент читает инструкции и при необходимости выполняет скрипт. После завершения задачи контекст skill освобождается. Это делает их идеальными для разовых инженерных задач вроде «сгенерировать changelog», «запустить конкретный набор тестов» или «отформатировать код». Они не требуют постоянной инфраструктуры и могут версионироваться вместе с кодом, над которым работают.

Model Context Protocol (MCP), напротив, — это тяжёлый стандарт взаимодействия. Он предполагает клиент-серверную архитектуру, в которой IDE подключается к работающему серверному процессу. MCP предназначен для поддержания состояния при работе с внешними системами — такими как базы данных PostgreSQL, репозитории GitHub или рабочие пространства Slack. MCP-сервер поддерживает постоянное соединение, управляет состоянием аутентификации и предоставляет агенту динамический набор инструментов и ресурсов. При всей своей мощи этот подход влечёт за собой операционные издержки: потребление памяти работающими процессами, управление портами и усложнение жизненного цикла.

Философия Skills: Skills отражают сдвиг в сторону принципа «меньше инфраструктуры — больше интеллекта». Вместо поддержки сложной сети микросервисов только ради того, чтобы ИИ мог прочитать схему базы данных, Skill может просто содержать скрипт, который подключается, считывает данные и отключается. Эта эфемерная природа делает Skills идеальными для подавляющего большинства локальных задач разработки, где постоянные соединения — избыточная нагрузка.

Вот способ понять различие на интуитивном уровне:

1. MCP Tools — это руки: детерминированные функции вроде read_file, execute_query или search_web.

2. Skills — это мозг: методология, которая определяет, как и когда агенту использовать эти инструменты.

Skill миграции базы данных (методология) может направлять агента к использованию Postgres MCP Tool (функции) для выполнения конкретной команды.

Skills, Rules и Workflows: в чём разница?

В Antigravity также существуют «Rules» и «Workflows». Понимание различий между ними критически важно для корректного проектирования системы.

• Rules (.agent/rules/): это пассивные ограничения. Они всегда «включены» (или срабатывают по типу файла) и внедряются в system prompt для управления поведением агента. Rules следует использовать для требований, которые агент обязан соблюдать всегда, например: «Всегда использовать строгий режим TypeScript» или «Никогда не коммитить секреты». Они ограничивают как выполняется любая задача. Это защитные ограждения системы.

• Workflows (.agent/workflows/): это активные, инициируемые пользователем последовательности действий. Workflow — это сохранённый prompt или набор шагов, который пользователь явно вызывает (например, /test или /review). Они полезны для ручной оркестрации и позволяют разработчикам запускать сложные многошаговые процессы одной командой. Это макросы агентного мира.

• Skills: Skills занимают промежуточное положение. Это возможности, которые активируются самим агентом. Пользователю не нужно вводить команду вида /skill-name. Вместо этого он формулирует цель («Проверь базу данных на наличие пользователя X»), а механизм рассуждений агента определяет, что релевантен skill для запросов к базе данных, и активирует его. Skills лучше всего подходят для отдельных инструментов или возможностей, к которым агент должен иметь доступ, но не использовать их постоянно. Они обеспечивают более естественный, разговорный интерфейс, где пользователь концентрируется на что, а агент сам определяет как.

Здесь становится по-настоящему интересно

Несмотря на различия, мы живём в интересное время и потенциально можем использовать все эти механизмы вместе.

Распространённый паттерн — Rule, принуждающее к использованию конкретного Skill. Например, глобальное правило может гласить: «Когда пользователь запрашивает изменение базы данных, ты ОБЯЗАН использовать skill safe-db-migration». Это гарантирует, что агент не попытается напрямую писать raw SQL в терминал, обходя проверки безопасности, заложенные в скрипте skill’а.

Аналогично, Workflow может вызывать Skill как один из своих шагов. Например, workflow /deploy может последовательно вызывать skill сборки, затем skill тестирования и, наконец, skill деплоя в облако. Такая композиционность позволяет создавать сложные и надёжные пайплайны автоматизации, которые при этом остаются достаточно гибкими для реальной разработки.

Создание Skills

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

Структура директорий

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

1. Область рабочего пространства (Workspace Scope): Располагается в <workspace-root>/.agent/skills/. Эти skills доступны только в рамках конкретного проекта. Это идеальный вариант для проектно-специфичных скриптов, таких как деплой в определённое окружение, управление базой данных конкретного приложения или генерация шаблонного кода для проприетарного фреймворка.

2. Глобальная область (Global Scope): Располагается в ~/.gemini/antigravity/skills/. Эти 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)

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

Файл SKILL.md

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

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

• YAML frontmatter

• Markdown-тело

YAML frontmatter

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

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

Ключевые поля:

• name: необязательное поле. Должно быть уникальным в рамках области видимости. Используется нижний регистр, допускаются дефисы (например, postgres-query, pr-reviewer). Если поле не указано, по умолчанию используется имя директории.

• description: обязательное и самое важное поле. Оно выполняет роль «триггерной фразы». Описание должно быть достаточно точным, чтобы LLM могла распознать семантическую релевантность. Размытое описание вроде «Инструменты для работы с базой данных» недостаточно. Точное описание, например: «Выполняет SQL-запросы только на чтение к локальной базе PostgreSQL для получения пользовательских или транзакционных данных. Используется для отладки состояния данных», гарантирует корректное срабатывание skill.

Markdown-тело

Тело содержит инструкции. По сути, это prompt engineering, сохранённый в файл. Когда skill активируется, это содержимое внедряется в контекстное окно агента.

Тело должно включать:

1. Goal: чёткое описание того, какую задачу решает skill.

2. Instructions: пошаговую логику выполнения.

3. Examples: few-shot примеры входных данных и ожидаемых результатов, помогающие направить поведение модели.

4. Constraints: ограничения в формате «нельзя» (например, «Не выполнять 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 сложно или невозможно сделать напрямую (например, запуск бинарников, сложные математические вычисления или взаимодействие с legacy-системами).

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

• Лучшая практика: делайте скрипты атомарными. Скрипт должен хорошо решать одну задачу (например, «выполнить запрос» или «задеплоить в staging»).

• Независимость от языка: Antigravity может выполнять любой скрипт, доступный в PATH окружения хоста (Python, Node, Bash, Go). Однако чаще всего выбирают Python из-за читаемости и богатой экосистемы библиотек.

• Аргументы и флаги: в теле инструкций SKILL.md нужно чётко описать, как передавать аргументы в скрипт. Затем агент будет генерировать корректный вызов CLI на основе запроса пользователя. Например, если скрипт принимает флаг --env, в SKILL.md следует указать агенту извлекать окружение (dev, stage, prod) из запроса пользователя и сопоставлять его с этим флагом.

Давайте соберём несколько Skills

Цель этого раздела — собрать Skills, которые интегрируются в Antigravity и поэтапно покажут разные возможности, такие как resources, scripts и т. д.

Вы можете скачать Skills из репозитория на GitHub здесь:

Мы можем разместить каждый из этих skills либо в папке ~/.gemini/antigravity/skills, либо в папке <workspace-folder>/.agent/skills.

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

Рассмотрим это как «Hello World» для Skills.

Разработчики часто пишут ленивые сообщения коммитов, например: “wip”, “fix bug”, “updates”. Вручную следить за соблюдением “Conventional Commits” утомительно, и про это легко забыть. Давайте реализуем Skill, который будет принуждать к спецификации Conventional Commits. Достаточно просто описать агенту правила — и он сможет выступать в роли контролёра.

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 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. Внесите небольшое изменение в любой файл в вашем workspace.

2. Откройте чат и напишите: Commit these changes.

3. Агент не просто выполнит git commit. Сначала он активирует skill git-commit-formatter.

4. Результат: будет предложено сообщение коммита в формате Conventional Commits.

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

Уровень 2: использование ресурсов (license-header-adder)

Это паттерн «Reference».

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

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

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

Файл SKILL.md показан ниже:

---
name: license-header-adder
description: Adds  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  correct copyright header.

## Instructions

1. **Read  Template**:
   First, read the content of  header template file located at `resources/HEADER_TEMPLATE.txt`.
   
   ```python
   # Pseudocode for agent understanding
   template_content = view_file("resources/HEADER_TEMPLATE.txt")
   ```

2. **Prepend to File**:
   When creating a new file (e.g., `.py`, `.java`, `.js`, `.ts`, `.go`), prepend  `target_file` content with  template content.

3. **Modify Comment Syntax**:
   - For C-style languages (Java, JS, TS, C++), keep  `/* ... */` block as is.
   - For Python, Shell, or YAML, convert  block to use `#` comments.
   - For HTML/XML, use `<!-- ... -->`.

## Example Usage
If  user asks to "create a python script for hello world", you should generate:

```python
# Copyright (c) 2024 Google LLC
# ... (rest of license text) ...

def main():
    print("Hello World")
```

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

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)

Паттерн “Few-Shot”.

Преобразование «рыхлых» данных (например, 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 }

2. Введите: Convert this JSON to a Pydantic model.

3. Агент посмотрит на пару примеров в папке skill.

4. Он сгенерирует 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: процедурная логика (database-schema-validator)

Паттерн «Tool Use».

Если спросить LLM: «Этот schema безопасен?», модель может ответить, что всё в порядке, даже если отсутствует критически важный primary key — просто потому, что SQL выглядит корректно.

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

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.
   
   ```bash
 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 mus
t have a primary key named 'id'. 3. No 'DROP TABLE' statement
s 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 TABLEs+(?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'bidb.*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.Агент не будет гадать. Он вызовет скрипт, который завершится с ошибкой (exit code 1), и сообщит нам: «Проверка не пройдена, потому что в таблице users отсутствует primary key с именем id».

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

Этот паттерн охватывает большинство возможностей, доступных в Skills.

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

• Скрипт (для создания файлов и scaffolding),

• Шаблон (для шаблонного кода в resources),

• Пример (для направления генерации логики).

adk-tool-scaffold/
├── SKILL.md
├── resources/
│ └── ToolTemplate.py.hbs (Jinja2 Template)
├── scripts/
│ └── scaffold_tool.py (Generator Script)
└── examples/
 └── WeatherTool.py (Reference Implementation)

Файл SKILL.md показан ниже:

---
name: adk-tool-scaffold
description: Scaffolds a new custom Tool class for  Agent Development Kit (ADK).
---

# ADK Tool Scaffold Skill

This skill automates  creation of standard `BaseTool` implementations for  Agent Development Kit.

## Instructions

1. **Identify  Tool Name**:
   Extract the name of  tool  user wants to build (e.g., "StockPrice", "EmailSender").
   
2. **Review  Example**:
   Check `examples/WeatherTool.py` to understand  expected structure of an ADK tool (imports, inheritance, schema).

3. **Run  Scaffolder**:
   Execute the python script to generate the initial file.
   
   ```bash
   python scripts/scaffold_tool.py <ToolName>
   ```

4. **Refine**:
   After generation, you must edit the file to:
   - Update  `execute` method with real logic.
   - Define  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  `requests` logic and `query` argument schema.

Вы можете обратиться к репозиторию skills и посмотреть файлы в папках scripts, resources и examples. Для этого конкретного skill перейдите в adk-tool-scaffold.

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

1. Введите: Create a new ADK tool called StockPrice to fetch data from an API.

2. Шаг 1 (Scaffolding): агент запускает Python-скрипт. Это мгновенно создаёт StockPriceTool.py с корректной структурой класса, импортами и именем класса StockPriceTool.

3. Шаг 2 (Реализация): агент «читает» файл, который только что создал. Он видит:

# TODO: Implement logic.

4. Шаг 3 (Ориентация): агент не уверен, как определить JSON-схему аргументов инструмента, поэтому он смотрит examples/WeatherTool.py.

5.Завершение: агент редактирует файл, добавляет requests.get(…) и описывает аргумент ticker в схеме, строго в соответствии со стилем ADK.

Русскоязычное сообщество про AI в разработке

Друзья! Эту новость подготовила команда ТГК «AI for Devs» — канала, где мы рассказываем про AI-ассистентов, плагины для IDE, делимся практическими кейсами и свежими новостями из мира ИИ. Подписывайтесь, чтобы быть в курсе и ничего не упустить!