Я написал скилл про публикацию статей и месяц удивлялся, почему он ни разу не подключился. Тело было подробное, шаги правильные, порядок выверен. Не работало ровно одно: описание.
Стояло там «Про публикацию контента в блоге». Это название темы. Условия срабатывания в нём нет, поэтому и срабатывания не было.
Обязательный минимум
Скилл — каталог с одним обязательным файлом. Всё, что нужно, помещается в четыре строки фронтматтера и заголовок.
---
name: publish-workflow
description: Публикация контента блога: draft → signed preview → publish,
RSS/sitemap, инвалидация кэша и проверка SEO.
applies_to: [claude, cursor, copilot, codex, gemini]
---name совпадает с именем каталога. description решает, подключится тело или нет. applies_to — список инструментов, для которых скилл предназначен.
Дальше идёт тело: заголовок, короткий абзац о цели, правила, порядок работы. Опционально — каталог references/ с длинными вещами, которые нужны не всегда.
Ничего больше формат не требует, и это правильно. Чем меньше обязательных полей, тем выше шанс, что скилл вообще будет написан.
Описание — это условие, а не аннотация
Проверка, которой я меряю каждое описание: можно ли подставить его в предложение «используй это, когда…» и получить осмысленный текст.
«Про публикацию контента в блоге» — «используй это, когда про публикацию контента в блоге». Бессмыслица, потому что описание отвечает на вопрос «о чём», а не «когда».
Три моих описания до и после правки.
Было: Работа с изображениями. Стало: Создавать, подбирать и внедрять растровые изображения для блога: обложки статей и рубрик, иллюстрации, реальные фото и скриншоты внутри статей, замена SVG на растр и проверка отображения в публичном layout. Использовать, когда нужно сгенерировать или подключить изображения к статье.
Было: Правила по контенту в базе. Стало: Править контент блога в сидерах (настройки, рубрики, правовые документы, статьи) и применять его полным сбросом БД. Использовать, когда нужно изменить тексты и структуру контента через сидеры, а не через код шаблонов.
Было: Ревью кода. Стало: Проверять изменения в проекте блога (Laravel + Filament) на регрессии в валидации, авторизации, Eloquent, очередях, уведомлениях, выводе Blade, миграциях и CSP. Использовать при ревью патчей и аудите рискованных изменений.
Общее у всех трёх правок: в описание переехали существительные, по которым распознаётся задача. «Обложка», «сидер», «миграция», «CSP» — это слова, которые встречаются в формулировке задачи. По ним скилл и находится.
Второе общее: появился глагол в неопределённой форме и явное «использовать, когда». Описание пишется от третьего лица, как инструкция стороннему исполнителю, а не как заметка себе.
Длина описания
Короткое описание не срабатывает, длинное срабатывает не там.
Мой рабочий диапазон — от одной до трёх строк. В нижней границе живут скиллы с уникальной областью: legal-pages не с чем спутать. В верхней — те, что соседствуют с другими: у frontend-design и visual-qa описания длинные, потому что оба относятся к публичному интерфейсу, но решают разные задачи.
Для соседних скиллов я развожу глаголы и момент запуска: frontend-design улучшает интерфейс, visual-qa подключается после изменений и ищет визуальные регрессии. Общей темы «публичный интерфейс» для маршрутизации недостаточно.
Кросс-агентная переносимость
Поле applies_to перечисляет инструменты, которые могут использовать скилл.
applies_to: [claude, cursor, copilot, codex, gemini]Практическая польза от него скромнее, чем кажется: разные инструменты ищут скиллы в разных местах, и одно поле этого не решает. У меня скиллы лежат в .ai/skills/, а часть из них симлинками проброшена в .claude/skills/, чтобы подхватывались обоими способами.
Зачем тогда поле. Во-первых, оно фиксирует намерение: скилл написан как переносимый, без завязки на конкретный интерфейс. Во-вторых, оно заставляет писать тело нейтрально — без «нажми вот эту кнопку» и без имён инструментов, которых в другом окружении нет.
Скилл, написанный под один инструмент, узнаётся по телу мгновенно: в нём упоминаются кнопки, режимы и названия команд интерфейса. Такой не переносится.
Структура тела
За несколько месяцев у меня устоялась одна и та же раскладка, и я перестал её выдумывать заново.
# Заголовок
Цель одним абзацем: что этот скилл делает и чего не даёт сломать.
## Модель / что где лежит
Сущности, файлы, точки входа — минимум фактов, нужных для работы.
## Workflow
Пронумерованные шаги в правильном порядке.
## Guardrails
Что нельзя. Перечислением, а не принципом.
## Проверка
Как убедиться, что получилось. Команды, если есть.
## Финальный ответ
Что должно быть в отчёте по итогам работы.Из шести разделов два неочевидные.
Guardrails — список запрещённых действий. В скилле про публикацию там строки вроде «не меняй дату публикации, если правишь только текст черновика». Такие вещи не выводятся из порядка шагов, зато стоят дорого при нарушении.
Финальный ответ — описание того, что должно вернуться по итогам. Без него отчёт получается либо на три абзаца прозы, либо из одной строки «готово». В скилле публикации это статус, дата, проверенные адреса, сброс кэша, тесты.
Порядок разделов важнее их состава: сначала факты, потом шаги, потом запреты. Запреты в начале читаются как манифест и теряются.
Когда нужен references/
Каталог рядом со SKILL.md, куда уходит всё длинное: шпаргалки команд, редкие сценарии, развёрнутые примеры.
Мой порог — сотня строк. Ниже — держу одним файлом. Выше — делю, потому что тело скилла загружается целиком, и сотня строк справочника команд занимает место ради случая, который наступает раз в двадцать задач.
Самый короткий мой скилл — восемнадцать строк: перечисление проектов экосистемы и шесть шагов построения карты влияния. Делить там нечего, и никакого references/ ему не нужно. Самый длинный — сто шестьдесят три строки про изображения, и вот его давно пора разрезать.
Отдельная статья цикла будет про прогрессивное раскрытие целиком, здесь достаточно правила: ссылка на справочник — это приглашение, а не обязательство. Формулировка «подробности в references/commands.md» работает, формулировка «прочитай references/commands.md перед началом» превращает разделение в фикцию.
Что осталось
Формат простой до скуки, и это его достоинство. С весны он не менялся, зато описания я переписывал десятки раз.
Чего мне не хватает — обратной связи о срабатываниях. Я не вижу, какой скилл подключился на конкретной задаче, и сужу по косвенным признакам: если в ответе появились шаги из тела, значит сработал. Из-за этого правка описания похожа на настройку антенны с закрытыми глазами: покрутил, стало вроде лучше, доказательств нет.
