Инструменты агенту: обёртка и скилл

Вопрос почти всегда ставят так: «какой MCP поставить». В подавляющем большинстве проектов ответ — никакой. Рабочая связка проще и скучнее: тонкая обёртка над тем, что вам нужно, плюс скилл, который объясняет агенту, когда её звать. Всё остальное — сложность, за которую придётся платить контекстом, правами и сопровождением.

Ниже — три формы по возрастанию цены. Дальше первых двух вы, скорее всего, не пойдёте, и это нормально.

1. Есть официальный скилл — берём его

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

npx aact@beta skill install --claude

После этого агент знает дисциплину C4, каталог паттернов и сам гоняет aact check после правок диаграммы. Никакого сервера при этом не появилось.

Главное свойство скилла: он почти не стоит контекста, пока не понадобился. Агент подтягивает его, когда дошёл до задачи, а не держит описание всё время перед глазами.

2. Есть просто API — пишем тонкую обёртку

Если у сервиса есть HTTP API и вам нужны от него три операции, самый дешёвый путь — маленький скрипт в вашем же репозитории, который эти три операции и делает. Агент вызывает его как обычную команду и читает результат текстом.

# scripts/tracker.py — ровно то, что нужно проекту, и ничего больше
uv run scripts/tracker.py list --sprint current
uv run scripts/tracker.py close UC-02

Что это даёт, кроме простоты:

• Права ровно по задаче. MCP-сервер обычно приносит весь API целиком. Обёртка умеет то, что вы в неё написали, — и ни строчкой больше.
• Вывод под агента. Вы сами решаете, что печатать: короткий текст, который читается с одного взгляда, вместо простыни JSON.
• Это код проекта. Лежит в репозитории, ревьюится в PR, ломается заметно. Такой же артефакт, как всё остальное.

Обёртка — это ещё и сенсор: скрипт, который печатает вывод, проверяем, а значит агент приносит факт, а не уверенность.

Обёртка умеет, скилл объясняет

Скрипт сам по себе агент найдёт не всегда и вызовет не тогда. Поэтому пара: обёртка делает работу, а скилл рассказывает, когда её звать и как читать вывод. Это те же два файла, что и весь харнесс, — просто в миниатюре.

Задачи проекта живут в трекере. Читать и закрывать их — через
`scripts/tracker.py`, напрямую в API не ходить.

- Посмотреть текущий спринт: `uv run scripts/tracker.py list --sprint current`
- Закрыть задачу: `uv run scripts/tracker.py close UC-02`

Закрывать задачу можно только после того, как PR смержен.

Пять строк текста и сорок строк скрипта закрывают ровно ту работу, ради которой обычно поднимают сервер.

3. MCP — редкое исключение

MCP решает настоящую задачу: один протокол, по которому любой агент подключается к любому инструменту. Но для проекта на семестр это почти всегда сложность ради сложности.

Брать его осмысленно ровно в одном случае: сервер уже написан и поддерживается вендором (GitHub, Plane и десятки других), вам нужен живой двусторонний доступ, и вы принимаете, что вместе с ним получаете весь их API целиком.

Если фраза начинается со слов «мы напишем свой MCP-сервер» — почти наверняка вам нужен скрипт на сорок строк.

Цена подключения

Контекст. Определения инструментов уезжают в сессию до первого сообщения. Подключили три «на всякий случай» — и заметная доля окна занята описанием того, чем агент за сессию ни разу не воспользуется. У скилла этой платы нет, у обёртки — тоже.

Права. Каждый подключённый сервер расширяет то, что модель физически может сделать. «Весь GitHub API» вместо трёх нужных методов — это решение с ценой: недетерминированная штука получила детерминированные права, и границу теперь держит только то, как вы её настроили.

Поверхность. MCP-сервер — это процесс с сетевым доступом и правами в системе. Своя сборка означает: обновлять, следить за уязвимостями, чинить, когда упал. Скрипт на сорок строк такого хвоста не тянет.

Как выбирать

1. Это знание или доступ? Знание («как у нас принято оформлять релиз») — скилл. Доступ к живым данным — обёртка.
2. Сколько операций реально нужно? Обычно три-четыре. Это скрипт, а не протокол.
3. Кто это будет поддерживать? Всё, что вы подключили, вы и чините — включая вечер перед защитой.

В курсе действует то же правило, что и с зависимостями: новый инструмент агенту — решение, а не привычка. Подключили MCP — запишите в AGENTS.md, зачем он и какие права вы этим выдали: следующий человек в проекте должен видеть границу, а не выяснять её опытным путём. Обёртку со скиллом описывать отдельно не нужно — они и есть описание.