Agent Skills ушли в Linux Foundation. Проверяем свои скиллы по новой методичке

Год назад Anthropic открыла формат Agent Skills: markdown-файл с инструкциями, который агент читает по мере необходимости. В октябре этого года стандарт передали в Linux Foundation, тому же фонду, куда раньше ушел MCP. По данным анонса, опубликован миллион скиллов, установлено почти 280 миллионов раз, формат поддерживают больше 70 платформ, включая ChatGPT, Cursor, GitHub Copilot и VS Code.

Вместе со стандартом фонду отдали и официальное руководство по написанию скиллов. Я взял его, прогнал через него все свои скиллы, 229 штук, и починил то, что не соответствовало. Рассказываю, что в методичке, как проверяли и какие промпты для этого нужны. Все промпты в конце, можно копировать.

Про скиллы я писал и раньше: Топ-10 скиллов Hermes Agent на каждый день - по статистике запусков видно, что реально используется, а что лежит мёртвым грузом; Скиллы как способ передавать опыт - пять задач из Skills Hub и как чужие скиллы приживаются; Профили, скиллы и A2A - что происходит с агентом, когда скиллы и профили мутируют. Сегодняшняя тема не про использование, а про качество упаковки.

Шесть правил методички

Полный текст лежит на agentskills.io в разделе skill-creation/best-practices. Ядро умещается в шесть правил.

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

2. Проверяй каждую строку вопросом: ошибся бы агент без этой инструкции? Нет, значит строка уходит.

3. Описание решает всё. При выборе скилла агент читает только имя и description. Формулируй как «Use this skill when...», перечисляй ситуации, включая те, что пользователь не назовет вслух, и держись лимита 1024 символа.

4. Не перегружай SKILL.md. Потолок 500 строк или 5000 токенов. Детали в references/ с указанием, когда какой файл читать.

5. Разделяй жесткие инструкции и рекомендации. Для мест, где легко ошибиться, давай точные команды. Где нужно решение агента, объясняй, почему выбор именно такой. Если задача решается несколькими способами, задай один дефолтный.

6. Веди список граблей. После каждой исправленной ошибки агента добавляй пункт в раздел pitfalls. У многих скиллов это самая полезная часть.

Правила выглядят очевидно. Проверка показывает иначе. Тут уместно сказать так: агент после сессии пишет скиллы, а инженер по итогам сессии пишет руководство для пользователя. Методичка это вторая роль, и дальше речь про неё.

Словарик

Базовые термины разобраны в глоссарии сайта, не буду повторять: скилл - процедурная память агента: триггеры, процедура, гейты, питфоллы; MCP - протокол подключения инструментов, скилл даёт знания, MCP даёт руки; субагент - отдельный агент со своим контекстом, им делегируют куски работы.

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

Аудит 229 скиллов: что оказалось не так

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

Сначала прогнал механическую проверку скриптом: имя совпадает с каталогом и состоит из строчных латинских букв и дефисов, description начинается с триггера и влезает в 1024 символа, тело до 500 строк, есть раздел граблей, ссылки на references живые, существует evals.json с двумя-тремя сценариями.

Итог первой прогона: у большинства описания были существительными без триггера («Зонтичный прожарщик отчетов»), в некоторых описание раздувалось за лимит, evals не было ни у кого, у трети не было раздела граблей. При этом по правилу номер один скиллы были хорошими: живые команды, реальные кейсы, ноль воды. Стандарт ругает не содержание, а упаковку.

Дальше 229 скиллов я правил не руками. Текст переписывал DeepSeek через шлюз tkbk.online, оркестрировали субагенты, а перенос длинных секций делал детерминированный скрипт: границы секций предлагает модель, блоки двигает код и проверяет, что каждая строка переехала дословно. Итог: 680 из 686 eval-сценариев прошли проверку судьей, ноль провалов, шесть частичных, все 229 файла теперь в лимите 500 строк, 18 длинных разнесены на references.

Цифры тут не для гордости, а для масштаба: массовая проверка без скриптов и гейтов на таком объеме не жилец. Руками я до сих пор правил бы первый десяток.

Как проверить свои скиллы за вечер

Чек-лист из семи пунктов, по нему можно пройтись поиском и простым скриптом.

1. Имя каталога равно имени скилла, только строчные латинские буквы, цифры и дефисы.

2. Description начинается с «Use this skill when» или «Используй, когда», перечисляет конкретные ситуации и влезает в 1024 символа. Существительное вместо триггера означает, что агент просто не поймет, когда скилл применять.

3. Тело до 500 строк. Всё, что длиннее, разноси: справочники, таблицы, примеры и дампы команд в references/, в основном файле оставь ядро процедуры и ссылку с пометкой, когда читать.

4. Раздел граблей существует и наполняется после каждого чиненого косяка агента.

5. Ссылки на references ведут на существующие файлы. Битый пойнтер хуже отсутствующего.

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

7. Есть evals с двумя-тремя сценариями: промпт и ожидаемое поведение. Без них скилл нельзя проверить после правки, любое изменение делается вслепую.

Скрипт проверки не нужно писать самому: собрал инструменты аудита в публичный репозиторий agent-skills-audit. Там три штуки.

skill_audit.py проверяет все пункты чек-листа без сети и печатает таблицу нарушений:

python skill_audit.py <каталог-со-скиллами>
# [ ] working-group-deliverables
#       - description has no trigger phrase (Use when...)
# 1/9 skills pass

split_tool.py разносят длинный SKILL.md на references. План секций даёт модель в JSON, блоки двигает скрипт и построчно проверяет, что каждый переехал дословно; при нарушении любого гейта файл откатывается из бэкапа.

eval_judge.py прогоняет eval-сценарии через LLM-судью с любым OpenAI-совместимым API: скилл вместе с references плюс сценарии на вход, pass/partial/fail с обоснованием на выход.

Массовую правку описаний я гонял субагентами, но повторять именно так не обязательно: тот же промпт исправления ниже работает и с одним агентом, просто дольше.

Промпты

Промпт превращения задачи в скилл. Дается агенту сразу после успешно решенной задачи, в той же сессии.

Следуй руководству https://agentskills.io/skill-creation/best-practices и преврати задачу, которую мы только что решили, в скилл.

Используй только шаги, которые сработали в этой сессии, мои правки и решения из истории git. Не восполняй пробелы общими знаниями.

Опиши скилл в формате «Use this skill when...», включая ситуации, которые я не называл прямо. Не длиннее 1024 символов.

Держи SKILL.md до 500 строк, детали вынеси в references/ и укажи, когда их читать.

Добавь отдельный раздел с граблями.

Имя: строчные латинские буквы, цифры, дефисы, совпадает с каталогом.

В конце создай 2-3 реальных сценария в evals/evals.json: промпт и ожидаемый результат. Покажи их мне.

Промпт массового аудита. Дается агенту, у которого есть доступ к каталогу скиллов.

Пройди все мои скиллы и проверь каждый по правилам стандарта Agent Skills:

1. Имя каталога: строчные латиница, цифры, дефисы, совпадает с именем.
2. Description: начинается с триггера «Use when», не длиннее 1024 символов, перечисляет конкретные ситуации.
3. Тело SKILL.md: не длиннее 500 строк.
4. Есть раздел граблей.
5. Все ссылки references/ ведут на существующие файлы.
6. Есть evals/evals.json с 2-3 сценариями.

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

Промпт исправления. После того как таблица нарушений перед глазами.

Исправь найденные нарушения, но с тремя ограничениями.

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

После каждого скилла проверяй: JSON в evals валиден, описание в лимите, тело не изменилось ни на одну строку вне согласованных мест.

Грабли массового прогона

То, что я вынес из своего прогона, на случай если будете повторять.

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

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

Окно проверки делайте с запасом. Первая версия моей проверки судила скилл по первым 9000 символов и выдавала ложные провалы: после разноса части секций в references судья их просто не видел. Процент pass скакнул с 89 до 99 не от правки скиллов, а от честного окна.

Экранирование в description проверяйте после любой массовой правки. Мой батч-воркер часть файлов записал с двойной обёрткой кавычек: значение description начиналось с экранированной кавычки, триггер «Use when» переставал распознаваться, хотя глазами файл выглядел нормально. Лечится итеративным разворачиванием JSON-строки до чистого текста; в skill_audit.py этот случай ловится как «no trigger phrase».

И последнее. evals, написанные моделью, это сценарии на бумаге. Они проверяют связность скилла, но не живое поведение агента. Для второго нужен настоящий прогон, и это отдельная работа, которую я еще не делал.

Что в сухом остатке

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

Мои скиллы жили год без этого договора и работали. Но после аудита их стало можно менять массово и быстро, а до него каждое изменение было рискованным. Разница именно в этом.

Материалы: agentskills.io/skill-creation/best-practices, там же полный стандарт. Скрипты аудита и разноса: github.com/NikolayGusev-astra/agent-skills-audit.