Вы сохранили подробную инструкцию проверки статьи, но агент снова ограничился ответом «текст выглядит нормально». Исправлять весь документ рано. Сначала выясните, обнаружил ли инструмент skill, выбрал ли его для запроса и получил ли доступ к необходимым файлам. Это три разные причины одного внешнего результата.
Разберём учебную процедуру article-preview: подготовить проверяемое превью существующего черновика, не меняя статус публикации. На её примере можно настроить собственный skill и проверить его до использования на рабочем контенте.
Минимальный переносимый формат
В спецификации Agent Skills обязательны name и description во фронтматтере файла SKILL.md. Имя должно соответствовать имени каталога. Для примера используем латиницу в нижнем регистре и дефисы:
---
name: article-preview
description: Подготовка и проверка превью существующего черновика статьи.
Используй, когда нужно проверить статью перед публикацией.
Не используй для публикации или настройки всего сайта.
---
# Проверка превью статьи
Найди черновик по переданному slug. Если запись не найдена,
сообщи об этом; не создавай замену.
Открой предусмотренное проектом превью. Проверь заголовок,
обложку, ссылки и блоки кода. Сохрани статус и дату статьи.
Верни ссылку на превью, найденные ошибки и список проверок.
Если превью открыть нельзя, укажи причину.Это инструкция, а не готовая интеграция с любым блогом. Команду получения превью нужно взять из конкретного проекта. Отсутствующий способ доступа нельзя заменять прямой публикацией: тогда проверка сама меняет объект, который должна оценить.
Поле applies_to, встречающееся в некоторых локальных наборах, не является обязательным полем стандарта и не устанавливает skill в перечисленные продукты. Собственные сведения можно хранить в metadata, но их смысл должен понимать ваш загрузчик. Не приписывайте произвольному YAML-полю поведение программы.
Проверьте каталог обнаружения
Корректный файл в произвольной папке ещё не означает установленный skill. Для проектных skills Codex документирует .agents/skills/; Cursor поддерживает этот каталог и .cursor/skills/. У Claude Code есть проектный .claude/skills/. Конкретное размещение сверяйте с документацией Codex, Cursor или Claude Code.
Выберите один инструмент для первого опыта. Создайте в его поддерживаемом каталоге папку article-preview, положите туда файл и проверьте наличие skill штатным способом этого продукта. Если он не появился, изучайте путь, имя и формат, а не расширяйте описание. В облачной сессии отдельно проверьте доступность файла: наличие на вашем компьютере не доказывает наличие на удалённой машине.
Описание должно отличать соседние задачи
Фраза «всё о статьях» подходит и написанию текста, и настройке редактора, и выпуску новой публикации. Она не помогает выбрать нужную процедуру. Более полезное описание называет вход, действие и границу: существующий черновик, проверка превью, сохранение статуса.
При этом описание не становится программным условием if. Модель может выбрать процедуру неверно. Поэтому утверждение «триггер написан — skill гарантированно сработает» слишком сильное. Для критичного шага нужен явный вызов или предусмотренное продуктом управление доступом, а затем проверка результата.
Не помещайте в описание весь порядок работы. Его задача — помочь выбрать процедуру. Подробные проверки обложки и ссылок относятся к телу. Если рядом есть publish-article, опишите разницу в обоих файлах: один готовит превью, другой переводит материал в публичное состояние в рамках разрешённой задачи.
Проверьте выбор и исполнение отдельно
Подготовьте небольшой набор запросов. Это собственный учебный набор, а не измерение качества модели:
- «Проверь превью черновика с таким-то slug» — процедура нужна.
- «Напиши вступление к статье» — не нужна.
- «Поменяй цвет ссылок во всём блоге» — не нужна.
- «Опубликуй готовую статью» — одного этого skill недостаточно.
- «Проверь черновик, которого нет» — ожидается сообщение об отсутствии, а не новая запись.
Сначала посмотрите, выбран ли нужный skill. Затем оцените действия: найден ли именно переданный черновик, открыт ли адрес, сохранён ли статус, перечислены ли реальные проверки. Успешный выбор без выполненной проверки не считается успехом. И наоборот, правильный результат случайного запуска не доказывает, что автоматический выбор настроен.
Такое разделение согласуется с подходом OpenAI к проверке skills. В своём наборе сохраняйте запрос, версию файла и наблюдаемый результат. После правки описания повторяйте те же запросы, иначе сравниваете разные условия.
Исправляйте тот слой, который дал сбой
Skill не обнаружен — проверьте установку. Обнаружен, но выбран на задаче про CSS — сузьте описание. Выбран правильно, но опубликовал черновик — исправьте границу действий и проверьте разрешения среды. Не смог открыть превью — восстановите доступ или укажите рабочий механизм проекта.
Закончить стоит небольшим файлом, для которого понятны положительные и отрицательные примеры. Длинный перечень красивых правил эту проверяемость не заменяет. Когда процедура начнёт обрастать редкими сценариями, их можно вынести в отдельные справочники.
