← назад к разделу

Скиллы: как упаковать методологию в навык AI-агента

У методологии есть неприятное свойство: она живёт в головах и в статьях, а работает — на каждом PR. Между «я прочитал, как правильно» и «код в репозитории написан правильно» лежит зазор, и в этот зазор проваливается почти всё. Человек помнит правило в момент, когда его формулировал; через месяц под давлением дедлайна — уже нет. AI-агент не помнит его вообще: каждая новая сессия начинается с чистого листа, он не был на вашей планёрке и не читал вашу вики.

Скилл — это способ закрыть зазор. Взять кусок методологии, который иначе остался бы в статье или в голове, и превратить его в навык агента — правило, которое агент подключает и применяет автоматически: когда пишет код, когда ревьюит PR, когда проектирует новую операцию. Не «где-то записано», а «применяется каждый раз».

Эта статья — про скиллы как концепт. Она входит в триаду оснастки для AI вместе с MCP и Memory Bank: скилл даёт агенту правила (что можно, чего нельзя, как правильно), MCP даёт руки (доступ к системам), Memory Bank даёт память (контекст проекта). Здесь разберём первую вершину.

Что такое скилл

Проще всего понять через контраст с документацией. Документация — это текст, который человек читает и решает, применять или нет. Скилл — это правило, которое агент применяет, не спрашивая.

Разница не в носителе (и то, и другое — markdown-файлы), а в адресате и в моменте срабатывания. Гайд по стилю API лежит в вики — его прочитают один раз при онбординге и забудут. Тот же гайд, оформленный как скилл, агент подключает в момент, когда пишет контроллер, и следует ему, потому что видит подходящий контекст. Знание перестаёт быть справочным и становится исполняемым.

Возьмём конкретику. Разработчик просит агента: «сделай эндпоинт оплаты заказа». Без скилла агент напишет грамотный, но средний код — тот, что чаще встречался в его обучающих данных: /api/payments/{id}/pay, сырой String вместо типизированного идентификатора, ошибка в виде голой строки. Со скиллом api-design, где записаны правила проекта (URL в kebab-case, версия в пути /v1/, идемпотентность через заголовок, ошибки по RFC 9457), агент напишет эндпоинт в стиле вашего проекта. Промпт при этом не длиннее — правило уже загружено, повторять его в каждом запросе не нужно.

Одно знание в двух формах

Это ядро всего раздела и, пожалуй, всего сайта. Каждый кусок методологии существует дважды: как статья и как парный скилл.

  • Статья — человеку. Чтобы понять предмет: зачем он нужен, какие бывают развилки, как выбрать. Статья объясняет, спорит, приводит контрпримеры, честно говорит, когда правило не нужно. Её задача — построить у тебя в голове модель, по которой ты сам примешь решение.
  • Скилл — агенту. Чтобы применять: тот же предмет, сжатый до проверяемого правила с кодом (API-3, AGG-X4). Скилл не объясняет и не убеждает — он предписывает и цитирует себя в ревью.

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

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

Оставим только скилл — человек потеряет понимание. Правило AGG-X4 без статьи — это команда без обоснования. Разработчик увидит в ревью «нарушение AGG-X4», исправит механически и ничему не научится. А когда правило окажется неуместным для его случая (так бывает — правила не абсолютны), он не сможет об этом судить, потому что не знает, откуда правило и против чего оно защищает.

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

Как устроен скилл

Без глубокого крафта, на пальцах. Скилл — это небольшой markdown-файл из трёх частей:

  • Имя и когда применять. «api-design — проектирование REST-эндпоинта». Агент по этому описанию понимает, в каком контексте скилл релевантен, и подключает его сам.
  • Само правило или инструкция. Что делать и чего избегать. Часто — набор пунктов с уникальными кодами (API-1, API-2, …), чтобы на них можно было ссылаться точечно.
  • Примеры «так» и «не так». Чтобы правило не оставалось абстрактным: агенту (и человеку) нужен образец.

Ключевая тонкость: правила не зашиты в скилл намертво. Скилл тонкий — это инструкция-исполнитель. Сами правила живут отдельным корпусом, который меняется, не ломая скиллы. Аналогия — плагин линтера, где конфиг правил отдельно от движка. Один источник, два рендера: тот же файл превращается в HTML-статью для людей и читается агентом как plain text. Они физически не могут разойтись, потому что это один файл.

Набор таких скиллов образует исполняемый корпус — и по нему видно, как это устроено внутри: имена, коды правил, разбивка по аспектам (API, стиль, тесты, DDD-тактика).

Как написать и поддерживать парный скилл

Рецепт короткий, и он же объясняет, почему формы не расходятся.

  1. Пишешь статью. Проговариваешь предмет для человека: проблема, развилки, как решать. На этом этапе ты сам разбираешься в теме — если не можешь объяснить, скилла ещё нет.
  2. Выделяешь проверяемое правило. Из статьи достаёшь то, что можно проверить механически: не «делай хорошо», а «идентификатор — типизированный VO, не String». Даёшь ему код.
  3. Оформляешь как скилл. Имя, когда применять, правило, примеры «так/не так».

Дальше — главное: они меняются вместе. Передумал про правило — правишь и статью, и скилл, одним движением. Расхождение — это баг, который ловится глазами: если статья говорит одно, а скилл делает другое, кто-то забыл про парность. Поэтому и держим их рядом, в одном репозитории, под одним ревью.

Это узкий, инкрементальный процесс: один аспект — одна статья — один скилл. Не «описать всю разработку разом», а закрывать зазоры по одному, там, где реально болит.

Место в триаде — и частный мощный случай

Скилл сам по себе — половина картины. Он говорит агенту, как правильно, но не даёт доступа к системам (это MCP — руки) и не помнит историю решений именно вашего сервиса (это Memory Bank — память). Втроём они превращают агента из «умного, но чужого» в «умного и вашего»: правила + доступ + контекст.

И один частный случай скилла заслуживает отдельного разговора — когда набор скиллов работает как исполняемый инженерный стандарт: версионируемый корпус правил, который AI применяет на каждом PR вместо тимлида-узкого места, цитируя конкретное правило со ссылкой. Это самая мощная форма «скилла как навыка ревью», и ей посвящена отдельная статья — executable standard. Там же — почему это дотягивается туда, куда не достаёт SonarQube.

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

Коротко

  • Скилл — кусок методологии, упакованный как навык агента: правило, которое агент применяет автоматически на каждом PR, при ревью, при генерации. Не документация, которую читают, — исполняемое правило.
  • Одно знание в двух формах. Статья — человеку, чтобы понять; парный скилл — его агенту, чтобы применять. Одним не обойтись: без статьи агент применяет, но человек не понимает и не может спорить; без скилла человек понимает, но агент не применяет.
  • Устройство простое: имя, когда применять, само правило с кодами, примеры. Правила — отдельный корпус, скилл тонкий; один файл рендерится и в статью, и в инструкцию для агента.
  • Пишется парно: статья → выделяешь проверяемое правило → оформляешь как скилл; дальше меняются вместе. Расхождение — баг.
  • Триада: скилл (правила) работает вместе с MCP (доступ) и Memory Bank (контекст). Мощнейший частный случай — executable standard.