Навык ИИ-агента: как собрать SKILL.md и проверить результат

Вы снова объясняете ИИ, какие материалы читать, что считать хорошим результатом и какие ошибки исправить. Вчера вроде договорились. Сегодня новая задача, и разговор начинается заново. В такой ситуации полезно сохранить рабочий порядок в отдельном навыке агента - скилле.

Но папка с инструкцией ещё не доказывает, что помощник стал полезнее. Он может не найти навык, применить его к чужой задаче или аккуратно выполнить устаревший порядок. Разберём, как собрать один небольшой скилл для своей работы и проверить его на реальных примерах. Без коллекции из сотни чужих инструкций.

Что такое навык ИИ-агента и зачем ему SKILL.md

В открытом формате Agent Skills навык - это папка с обязательным файлом SKILL.md. В начале файла находятся метаданные name и description, дальше - инструкция в Markdown. Рядом при необходимости лежат справочные материалы, шаблоны и скрипты. Описание сообщает, какую работу выполняет навык и когда его применять. Это устройство формата, а не обещание качества результата. Спецификация Agent Skills.

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

Если пока непонятно, за какую часть работы отвечает помощник, сначала пригодится карточка роли ИИ-сотрудника. Здесь пойдём дальше: возьмём одну процедуру и зададим для неё вход, шаги и критерии приёмки.

Какую задачу стоит упаковать первой

Я бы выбрал процесс, в котором приходится повторять одни и те же содержательные поправки. Например, проверку черновика на соответствие исходникам. Задача достаточно узкая: помощник не придумывает за автора позицию, а ищет, где текст расходится с предоставленными материалами.

Для первого навыка полезно заранее ответить на три вопроса. Что приходит на вход? Какой результат нужен? По каким признакам человек его примет? Если ответы звучат как «всё что угодно», «качественный контент» и «чтобы понравилось», границы ещё не определены.

Иллюстративный вариант: на входе черновик поста и заметки эксперта. На выходе список спорных утверждений с привязкой к конкретным абзацам. Хороший результат - проверяющий видит, что подтверждено, что отсутствует в заметках и какой вопрос нужно задать автору. Переписать весь пост без запроса в эту задачу не входит.

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

Описание отвечает за включение, инструкция - за работу

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

Описание «помогает создавать лучший контент» не даёт ясного условия. Для нашего примера я бы написал конкретнее: «Проверяет готовый черновик по предоставленным заметкам автора. Применять, когда нужно найти неподтверждённые факты, присвоенный чужой опыт и расхождения с исходниками. Не использовать для написания текста с нуля».

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

Не стоит проверять включение только командой «используй мой навык». Она проверяет прямой вызов. Отдельно дайте обычную формулировку, которой воспользовались бы в работе: «посмотри, не добавил ли я лишних фактов». Затем посмотрите, какой навык действительно был прочитан, если ваша программа показывает такие действия.

Что положить внутрь: небольшой пример процедуры

Ниже учебный фрагмент, который нужно адаптировать под свои документы. Это заготовка для обсуждения, она не проходила испытаний на вашем агенте. Папку можно назвать draft-source-review, а главный файл - SKILL.md.

---
name: draft-source-review
description: Проверяет готовый черновик по заметкам автора. Использовать для поиска неподтверждённых утверждений и расхождений с исходниками. Не использовать для текста с нуля.
---

## Вход
Черновик и материалы, по которым его нужно проверить.
Если исходников нет, запросить их и не объявлять факты проверенными.

## Порядок
1. Прочитать черновик и предоставленные исходники.
2. Найти числа, обещания, описания опыта и причинные выводы.
3. Для каждого спорного места указать абзац и основание проверки.
4. Разделить: подтверждено, требует уточнения, противоречит материалам.
5. Предложить локальную правку. Не переписывать текст целиком.

## Результат
Таблица: фрагмент, статус, основание, вопрос или правка.
Отдельно перечислить ограничения проверки.

Здесь важнее содержание шагов, чем красивое название. «Проверь достоверность» оставляет помощнику слишком много свободы. «Для обещания найди основание в предоставленных исходниках, иначе отметь вопрос автору» задаёт наблюдаемое действие.

К процедуре полезно приложить свой пример удачного результата и пример ошибки с объяснением. Допустим, в заметках сказано: «хочу сократить время подготовки». В черновике появилось: «сократил подготовку вдвое». Ожидаемая реакция - отметить неподтверждённый результат и запросить подтверждение, а не подобрать убедительную формулировку.

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

Что показывают исследование и практические разборы

В предварительной работе SWE-Skills-Bench авторы сравнили выполнение задач разработки с навыками и без них. В набор вошли 49 публичных навыков и около 565 задач. У 39 навыков прироста доли успешно выполненных задач не оказалось. Средний результат изменился с 89,8% до 91,0% - на 1,2 процентного пункта, при этом отдельные специализированные навыки помогали заметнее. Препринт SWE-Skills-Bench.

У исследования узкие границы: задачи программирования, определённый агент и модель Claude Haiku 4.5, предварительные результаты. Это не измерение качества экспертных постов и не доказательство бесполезности навыков. Для нашей задачи я бы взял отсюда принцип сравнения: сначала посмотреть, что помощник умеет без дополнительной инструкции, затем измерять разницу. Сам факт установки ничего не доказывает.

Есть и независимый практический эксперимент на Хабре: автор alex2061 описал навык обработки обращений, четыре модели и 480 запусков с навыком. На ключевых обращениях он сравнивал отсутствие системной инструкции, короткий промпт и подробную процедуру. Результаты зависели от модели. Важная деталь: содержимое навыка передавалось целиком как системный промпт. Такой опыт проверяет исполнение инструкции, но не автоматическое обнаружение папки. Сам автор называет эксперимент разведочным. Разбор одного навыка на четырёх моделях.

В зарубежном практическом руководстве Travis Media отдельно предлагаются проверки включения, выполнения и сравнение с результатом без навыка. Это рекомендация автора блога, а не независимое измерение эффективности. Она помогает увидеть два разных вопроса: помощник вообще выбрал нужную процедуру и получился ли от неё полезный результат? Руководство Travis Media.

Эти источники не дают универсального процента улучшения для вашей работы. Зато объясняют, почему удачный показ одного ответа недостаточен для решения «теперь можно всё поручать автоматически».

Как проверить навык на своих задачах

Для первого прогона я бы собрал небольшой набор разных черновиков. Один с явной выдумкой, один без ошибок, один с неоднозначным выводом, ещё один без исходников. Добавил бы запрос, который вообще не относится к этому навыку. Такой набор не станет научным исследованием, но покажет очевидные промахи.

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

Записывайте конкретные ошибки: пропустил обещание, неверно назвал чужой случай собственным, потребовал подтверждение очевидной цитаты. Оценка «текст стал солиднее» слишком удобна для самообмана. Для проверки исходников полезнее считать пропуски и ложные замечания, а затем смотреть, сколько ручной работы осталось.

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

Видео от 8 мая 2026 года. Канал автора · Смотреть на YouTube.

Доступ к сервисам и готовая инструкция - разные части работы

В нашем учебном примере агенту достаточно прочитать предоставленные материалы и вернуть замечания. Если вы хотите, чтобы он ещё забирал записи из сервиса и сохранял результат в вашей системе, отдельно понадобятся подключение и права. Эту часть полезно разобрать через подключение ИИ-агента к сервисам через MCP.

Я бы сначала проверил саму процедуру на копиях материалов, затем добавлял действия с внешними системами. Так проще понять источник сбоя: инструкция неверная, данных не хватает или подключение не работает. Чужой готовый навык тоже сначала стоит прочитать целиком, включая приложенные скрипты, и сопоставить с вашей задачей.

Как поддерживать навык, чтобы он не устарел

Назначьте человека, который принимает изменения, и сохраняйте предыдущую версию. Рядом можно вести простой журнал: дата, что изменили, какая ошибка стала причиной и какие примеры перепроверили. Это рабочая рекомендация для небольшого процесса, специальная система управления для неё не обязательна.

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

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

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