Как писать skill для AI-агента: когда он нужен и как устроен

Через пару месяцев работы с AI-агентом проявляется один паттерн: некоторые инструкции вы пишете снова и снова. «В этом проекте используется Bun», «файл лежит здесь», «сначала черновик, не публикуй».

Это не инструкция. Это незадокументированная процедура. И если вы каждый раз печатаете её вручную, то сами превратились в кэш.

Skill решает ровно эту проблему: повторяющуюся процедуру вы записываете в файл, а агент открывает его сам, когда нужно.

Что такое skill

Технически skill — это markdown-файл. В начале короткие метаданные, дальше текст инструкций.

---
name: notion-blog-writer
description: Написание статьи для блога и сохранение черновика в Notion.
  Используется, когда пользователь говорит "напиши статью".
---

# Процесс

## 1. Понять бриф
...

Основная идея проста: этот текст не висит в контексте постоянно. Агент подгружает его только тогда, когда он нужен. Поэтому даже десяток skill'ов не душит друг друга.

Именно это отличает skill от обычной проектной документации. Документ лежит и ждёт, что кто-то его прочитает. Skill вызывает себя сам в нужный момент.

Самая важная строка — description

При написании skill люди тратят все силы на текст инструкций, а описание пишут наспех. Должно быть наоборот.

Причина: агент решает, какой skill открыть, только по описанию. Текст инструкций ему в этот момент ещё не виден. То есть при плохом описании самые выверенные инструкции внутри просто никогда не запустятся.

Плохое описание:

description: Помощник для работы с блогом

Хорошее описание:

description: Написание статьи для блога и сохранение черновика в Notion.
  Срабатывает на «напиши статью», «новая статья», «опубликуй в блог».
  Пишет статью на трёх языках: uz/ru/en.

Разница в том, что во втором есть триггерные фразы. Вы прямо записываете, какими словами пользователь может обратиться. Это одно изменение даёт наибольший эффект.

Разбивайте инструкции на шаги

Самая надёжная форма для тела skill — нумерованные шаги. Не проза, а список.

Мой блоговый skill устроен так: проверь очередь, пойми бриф, напиши черновик на узбекском, получи подтверждение, переведи, собери payload, сохрани, отчитайся.

Шаги дают две вещи. Первое — порядок становится явным, агент не проскакивает этап. Второе и более важное — появляются точки проверки. Я записал в skill «не переходи к публикации до подтверждения», и одна эта фраза несколько раз спасала от ошибочной публикации.

Обязательно записывайте ловушки

Самая ценная часть skill — не инструкции, а список ловушек. То есть ошибки, которые вы уже съели.

В моём блоговом skill есть такая запись: в Notion две отдельные колонки с датой, одна показывается на сайте и участвует в сортировке, вторая является триггером автопубликации. Если они разъедутся, статья выйдет с неправильной датой.

Это действительно произошло несколько месяцев назад: меняя график публикаций, я перенёс только одну колонку, и несколько статей остались на сайте с датой из будущего.

Теперь эта ловушка записана в файле. То есть я не съем её второй раз, и это знание хранится не в моей памяти, а в системе.

Практическое правило: каждый раз, когда при работе с агентом возникает ошибка, спросите себя — «это повторится?». Если да, после исправления добавьте одну строку в skill.

Как skill экономит контекст

Техническую ценность skill часто понимают неверно. Люди думают, что это способ «дать агенту больше информации». На деле он делает обратное — позволяет давать меньше.

Причина в том, что контекст — ограниченный ресурс. Если записать все инструкции в проектную документацию и грузить её в каждый диалог, десять процедур займут место во всех десяти диалогах — даже если девять из них не понадобятся.

Skill же двухступенчатый: агент сначала видит только список коротких описаний, а полный текст открывает ровно тогда, когда он нужен.

Отсюда практическое следствие: skill можно не бояться писать длинным. Мой блоговый skill состоит из семи шагов, нескольких примеров кода и списка ловушек. Если бы этот текст грузился в каждый диалог, мне пришлось бы его сокращать — и потерялась бы как раз самая полезная часть, подробности.

Не один большой skill, а несколько маленьких

Второй вопрос структуры: писать один большой skill или несколько маленьких.

Я предпочитаю маленькие, и причина вытекает из предыдущего пункта. Если написать один огромный skill «работа с проектом», он будет открываться по самым разным поводам и каждый раз грузиться целиком. Во время деплоя вам не нужны правила написания контента.

Границу стоит проводить так: один skill — одна завершаемая задача. Написать статью. Выпустить релиз. Подготовить отчёт.

Если в описании skill слово «и» встречается больше двух раз, его, скорее всего, пора разделить надвое.

Когда skill не нужен

Эту часть обычно пропускают, но она важна.

Skill не нужен, если:

• Задача разовая. Для однократной работы достаточно обычного промпта.
• Инструкция короткая. Заворачивать одну фразу в skill — лишний слой.
• Знание уже есть в коде. Агент умеет читать код; пересказывать ему структуру проекта — бессмысленная работа.
• Инструкция часто меняется. Если заморозить в файле то, что меняется еженедельно, файл быстро превратится в ложь.

Лучший кандидат — стабильная, повторяющаяся процедура с ловушками. Порядок деплоя, релизный чеклист, формат отчёта, контентный конвейер.

Как тестировать skill

После написания skill его обязательно нужно проверить, потому что самая частая неисправность — он вообще не запускается.

Тест простой: начните новый диалог и обратитесь той естественной фразой, которую напишет пользователь. Если skill не открылся, проблема почти всегда в описании — не хватает триггерных фраз.

Второй тест — отклонение. Дайте запрос, слегка отходящий от инструкции, и посмотрите, адаптируется ли skill или встаёт колом. Хороший skill — не жёсткий скрипт, он задаёт направление.

Вывод

Skill — это память, которую вы дали агенту. Его написание — вложение, и оно окупается при одном условии: процедура действительно повторяется.

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

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