Добавляя новый skill, мы ждем от агента простого результата: меньше ошибок, более стабильная работа и лучшее понимание библиотек и фреймворков.
На практике же часто можно наблюдать:
один skill активируется почти всегда, даже когда не нужен
другой — не включается в момент, когда мы на него рассчитываем
третий — срабатывает «в паре» с соседними и они мешают друг другу
В какой-то момент может показаться, что агент работает хаотично и явно хуже, и хочется выключить все skills и вернуться к первоначальному состоянию.
Почему так происходит и что с этим можно сделать, разбираемся в статье.
Анатомия skill
Для начала разберемся с анатомией: skill состоит из двух частей — заголовка и тела.
Заголовок представляет собой YAML frontmatter, чаще всего включающий название skill и его описание, иногда также встречается набор разрешенных tools. Но это не все доступные параметры, которые может содержать YAML frontmatter: полный список можно посмотреть в документации.
---
name: spring-explore
description: > Explores a Spring Boot application and builds primary context:
tech stack, module structure, domain entities, REST endpoints. Triggers on
explicit requests: "explore project", "describe project", "project overview",
"what is this project", "project structure", "tech stack", "give me context
about the project", or whenever you need to understand the project before
starting any task.
---Тело skill — это основная инструкция для агента: что делать, в каких условиях и какой результат считать корректным. Тело может включать пошаговые инструкции, скрипты, референсную документацию и многое другое. Когда вы разрабатываете тело, есть разные подходы, но сегодня не про это.
Активация skill
В момент, когда вы запускаете агента, он читает все YAML frontmatter всех skills, добавленных на уровне пользователя и проекта, и добавляет их в контекст (в действительности LLM-модели не имеют stateful-контекста, но сейчас не об этом). После того как вы сформировали промпт/запрос к агенту и отправили его на выполнение, агент определяет следующее действие.
Таким действием может быть все что угодно, в том числе использование skill. По большому счету для LLM-модели нет большой разницы между вашим промптом и описанием skills: модель в целом решает, что делать дальше. Однако на вероятность того, что агент захочет активировать skills, можно повлиять:
На этапе обучения. Это то, чем долгое время занимались в Anthropic, а теперь занимаются все разработчики моделей. Метрика того, насколько модель активно использует skills, теперь замеряется и является важной характеристикой качественной модели.
На этапе промпта. LLM буквально можно мотивировать активнее использовать skills. Исследователи из Anthropic даже приводят вариант промпта:
You should use tools as much as possible, ideally more than 100 times. You should also implement your own tests first before attempting the problem. You should take time to explore the codebase and understand the root cause of issues, rather than just fixing surface symptoms. You should be thorough in your reasoning and cover all edge cases.
Подобный текст можно добавить в промпт, который вы отправляете в консоли, в CLAUDE.md/AGENTS.md или, как делаем мы в Spring Agent Toolkit, добавить hook.
Итак, теперь при каждом нашем отправленном промпте агент "старается" (ничего не гарантировано) найти подходящий skill и вызывает его. Хорошо ли это?
В случае если ваш набор skills хорошо подобран, а описание качественное, то с высокой вероятностью активируется skill, который будет полезен для решения поставленной задачи. Конечно, нельзя исключать, что будет подгружен skill, который не принесет пользы. Для этого в тело skill можно встроить шаг, который, анализируя контекст, "выйдет", если skill явно загружен по ошибке.
Однако все это необходимо только в том случае, если ваши skills "экологичны".
"Экологичность" skills
Возможно, вы замечали, что некоторые установленные skills довольно часто активируются, при этом не всегда имеет значение, связана ли поставленная агенту задача с целью skill. Происходит это из-за не "экологично написанного" YAML frontmatter.
Достаточно легко заставить модель активировать skill, добавив в него слова-"мотиваторы". Например, указав в YAML frontmatter "MUST", "CRITICAL", "MANDATORY", можно, скажем так, "принудить" агента загрузить skill. При этом вообще не важно, применяете ли вы какую-то технику активации skills из предыдущего раздела.
Проведите эксперимент. Создайте non-eco skill:
---
name: non-eco
description: MUST USE with any prompt
---
Tell user: Hello world!А теперь давайте попросим агента решить любую задачу.
Как видите, агент активировал skill, выполнил тело и остановился. А теперь представьте, что таким образом описанных skills у вас несколько. Загрузив их все, агент легко может начать вести себя хаотично.
Если бороться с подобным поведением можно на уровне агента, например вырезая подобные слова или смягчая их значение, то бороться с широким описанием в skill будет гораздо сложнее.
Например, при тестировании разработчик видит, что его skill с описанием того, как нужно описывать Event Listener, не всегда активируется, когда агент добавляет нового слушателя. После нескольких попыток модификации описания во frontmatter вполне может оказаться описание вида: "Используй данный skill, когда работаешь со Spring Boot/Spring Framework".
В результате skill с таким описанием во frontmatter будет активироваться практически для любой задачи в Spring Boot проекте. В его конкретной комбинации это может и не вызывать проблемы, но в вашем наборе вполне может привести к серьезным последствиям. Значит ли это, что столь широкие формулировки вообще не стоит использовать?
Конечно же нет. Если ваш skill действительно обладает широким набором знаний, методов и внутренней маршрутизацией по работе со Spring Boot, то это стоит указать во frontmatter, поскольку польза от такого skill будет значительной, а внутренняя маршрутизация (с использованием sub-agents) позволит сохранить основной контекст "чистым".
На текущий момент об "экологичности" в основном думают компании и разработчики, предлагающие полноценные наборы; в том же Spring Agent Toolkit skills стараются учитывать этот аспект.
Интересный факт: в Spring Agent Toolkit не все skills "экологичные". Это обусловлено тем, что они знают о своих "соседях" и проходят тестирование, контролирующее, что skills в наборе не мешают друг другу.
Итак, оставив в наборе только "экологичные" skills, самое время поговорить о точках активации.
Точки активации
Вариант, когда мы явным образом стимулируем агента использовать skills при очередном запросе, мы уже обсудили выше. А что же дальше?
Допустим, мы поставили перед агентом задачу доработать всем известную Spring Petclinic, добавив в нее функционал учета рабочего расписания. Для этой задачи агенту потребуется доработать JPA-модель, создать сервисы, добавить новые REST-эндпоинты и модифицировать имеющиеся. В итоге на разных этапах нам потребуются разные skills. Вероятность того, что агент загрузит все нужные skills на этапе отправки промпта, невелика, поэтому определенно skills нужно подгружать в процессе выполнения.
И агенты уже делают это: в целом перед определением каждого следующего шага агент может рассмотреть возможность загрузки нового skill. Однако, по собственным наблюдениям, чем дальше мы от первичного мотивирующего промпта, тем ниже вероятность загрузки нового skill.
В целом, мы показывали весь этот процесс и акцентировали внимание на отдельных вызовах скиллов на прямой трансляции, кому интересно, можете глянуть:
В случае если вы используете режим планирования, агенту в гораздо меньшем количестве мест нужно определять следующий шаг; как результат, вероятность загрузки нового skill еще сильнее снижается. Однако в режиме планирования вы можете прямо в плане указать, что нужно использовать некоторый skill, так например делает spring-planning.
Кроме того, в skill может быть явно указана необходимость использования другого skill. Подобные примеры можно найти в Spring Agent Toolkit: например, Spring Planning использует Spring Explore для быстрого анализа приложения перед формированием вопросов и запуском планирования.
Также skill можно активировать явно (если это не запрещено во frontmatter). Например, skill Spring Planning крайне редко активируется автоматически, поскольку он описывает полноценный процесс планирования изменений в Spring-приложении. Попробуйте его, и вы удивитесь, насколько быстро завершается анализ и выполняется планирование.
Последнее, о чем стоит поговорить, — это деактивация skills.
Деактивация skills
Как бы мы того ни хотели, активированные skills могут оказывать (и оказывают) влияние на загруженные в будущем skills, и не всегда хорошее. Например, можно наблюдать эффект, когда некоторая методика из вновь загруженного skill не исполняется полностью или агент пропускает некоторые шаги, считая, что они не требуются. Это вполне может сказаться на результате. Данную проблему можно частично решить совместным тестированием, но это не всегда возможно.
Возникает логичный вопрос: а можно ли деактивировать skills, которые на данный момент агенту больше не требуются? Теоретически это возможно, но агенты пока не предоставляют такой возможности. Но мы можем сгладить данную проблему, активировав временные skills в sub-agents. Например, в случае если нам требуется как-то модифицировать JPA-модель, мы можем создать sub-agent, поставить перед ним требуемую задачу и указать, что необходимо активировать spring-data-jpa skill.
В ситуации, когда перед тем, как приступить к реализации, разработчик создал план с помощью spring-planning, требование на выполнение шага в sub-agent можно включить в сам план. Сейчас вариант такого skill находится в тестировании. Поэтому ставьте звёздочку на репозиторий и следите за новостями!
Заключение
Как видите, вопрос активации skills не так прост, как может изначально показаться. Хорошо скомпонованный набор skills для агентов, разрабатывающих на Spring, можно установить через Spring Agent Toolkit, а больше про разработку на Java с AI-агентами читайте в нашем ТГК-канале Amplicode.
