Как правильно писать навык для ИИ-агента: шесть принципов из практики
Как правильно писать навык для ИИ-агента: шесть принципов из практики Александро Сауседо, директор по ИИ, данным и платформам в Zalando, рассказывает, как за год перестал отдельно писать короткие программы для автоматизации: мелкие автоматизации превратились в «навыки» — процедуры, которые выполняет ИИ-агент. Детерминированные части остаются командами, но живут внутри инструкции, написанной по-английски, как код: файл, который читает человек, — ровно то, что исполняет агент. Свой подход он описывает по пяти принципам плюс одному необязательному. Первый принцип: описание навыка — это маршрутизатор. Агент видит только его до загрузки навыка, поэтому описание должно перечислять фразы-триггеры и принимаемые входные данные словами пользователя, а не абстрактно «комплексная утилита для работы с изменениями кода». Автор пишет описание последним, когда знает, что навык реально делает. Второй принцип: тело навыка — только шаги. Введение, архитектура, глоссарий, «дальнейшее чтение» удаляются; обработка ошибок и ограничения вписываются прямо в тот шаг, где они нужны, а не в отдельный раздел — иначе агент выбирает неверное восстановление ещё до прочтения подсказки. Третий принцип разделяет инструменты: скрипты несут фиксированные последовательности (аутентификация, вызовы API), агент — оценочные решения вроде подготовки описания новой версии в принятом в проекте стиле. Перекос в обе стороны автор испытал на себе: перегруженный скрипт делает навык ненужной обёрткой, перегруженный агент — сжигает минуты и тысячи токенов на то, что делает скрипт из пяти строк. Четвёртый принцип: SKILL.md загружается при каждом запуске и расходует контекст, поэтому держит только шаги, условия и команды; справочные материалы выносятся в отдельные файлы и читаются по мере необходимости. Пятый принцип — проверка. Без неё навык рано или поздно выдаёт неверный результат, и ничто в запуске это не заметит. Проверка вывода — отдельный шаг процедуры, соразмерный ставкам, чтобы не раздувать время каждого запуска. Затем автор проверяет сам навык: не спрашивая модель «хороший ли этот файл», он даёт отдельному агенту, который не участвовал в создании навыка, реальную задачу и смотрит на следы — расход токенов, застревания, выдуманные шаги. Тест он несколько раз повторяет на дешёвой модели: по его опыту, она лучше выявляет ошибки, потому что падает в каждую яму, которую сильная модель перепрыгивает. Необязательный шестой принцип — петля обратной связи с человеком: навык завершается шагом, где агент анализирует собственный запуск и сообщает о том, что потребовало нескольких попыток или обходных путей. Мелкие исправления предлагаются на проверку в репозитории навыка, крупные оформляются как отдельная задача с контекстом и шагами воспроизведения. По словам автора, когда это работает, навык улучшается ещё до того, как он сядет редактировать, — но шаг он держит опциональным, так как он стоит небольшого ресурса на каждом запуске, и не всякому навыку такой цикл оправдан. Принципы выведены из навыков, которые авторские команды используют ежедневно и выложили в открытый Agent Skills Marketplace: release-repo закрепляет последовательность релиза в командах и оставляет агенту заметки и решения об отмене; dependabot-fix чинит падающий Dependabot-PR и мержит его только после срабатывания проверок; dependabot-fix-all прогоняет его по каждому открытому PR; writing-skills применяет методику самой статье. Требование к навыкам в маркетплейсе — процедура, которую реально запускают, и достаточно короткая, чтобы её можно было прочитать и оспорить. Источник: https://hackernoon.com/the-right-way-to-write-an-agent-skill