Мой AGENTS.md в какой-то момент дорос до трёхсот с лишним строк, и я заметил странность: чем подробнее он становился, тем чаще нарушались правила из его середины. Не из конца, не из начала — именно из середины.
Объяснение оказалось скучным. Файл контекста читается целиком и всегда, а внимания на всё не хватает. Дальше я разбирался, что из него вынести и куда.
Скилл технически
Скилл — это каталог с файлом SKILL.md, у которого есть фронтматтер с именем и описанием. Описание работает как условие срабатывания: по нему принимается решение, подключать содержимое к текущей задаче или нет.
---
name: publish-workflow
description: Публикация контента блога: draft → signed preview → publish,
RSS/sitemap, инвалидация кэша и проверка SEO.
applies_to: [claude, cursor, copilot, codex, gemini]
---Вся конструкция держится на одной строке description. Тело файла не читается, пока условие не сработало, поэтому оно не занимает внимания на задачах, к которым не относится.
Отсюда главное отличие от AGENTS.md: файл контекста — это то, что верно всегда, скилл — то, что применяется иногда. Не «важное и второстепенное», а «постоянное и условное».
Порог заведения
Я завожу скилл, когда объясняю одно и то же третий раз.
Первое объяснение — работа. Второе — совпадение. Третье означает, что процедура повторяющаяся, и дальше я буду пересказывать её по памяти, каждый раз чуть иначе.
Второй признак, менее очевидный: у процедуры есть порядок шагов, который легко нарушить. Публикация статьи в блоге — как раз такая. Сначала вычитка, потом обложка, потом конвертация в HTML, потом запись в сидер, потом прогон сидера, и только потом снятие черновика. Переставьте два шага — получите пост без обложки в ленте или сидер, который затрёт правки.
Третий признак — процедура опирается на то, чего в коде не видно. seed-content существует, потому что на проде развёртывание каждый раз пересоздаёт базу целиком: источник правды — сидеры, а не админка. Прочитать это из кода приложения нельзя, оно живёт в скрипте развёртывания.
Если ни одного из трёх признаков нет — это строка в AGENTS.md, а не скилл.
Что остаётся строкой
Разделение проще всего показать на паре.
В файле контекста блога есть строка про то, что все команды идут внутри контейнера. Это верно для любой задачи, где вообще что-то запускается, — от прогона тестов до генерации миграции. Никакого порядка шагов, никакого условия, просто факт среды. Скиллом ей быть незачем.
Рядом лежит filament-resource — процедура создания ресурса админки: раскладка по папкам, форма, таблица, фильтры, действия, права. Она применяется, когда я добавляю раздел админки, то есть раз в несколько недель. Держать её в файле контекста — значит платить вниманием на каждой задаче про шаблоны и модели.
Правило, которым пользуюсь: если строку нужно помнить при любой работе с проектом — она в AGENTS.md. Если только при определённом типе работы — это скилл.
Скилл стоит денег
Про это не пишут в статьях про скиллы, а зря: заведённый скилл надо поддерживать.
Мой publish-workflow описывал путь публикации через админку. Потом путь изменился: контент переехал в сидеры, публикация пошла через файлы и прогон сидера. Скилл я поправил не сразу, и между этими двумя моментами он был не бесполезен, а вреден — он уверенно описывал процедуру, которой больше нет.
Устаревший скилл хуже отсутствующего по той же причине, по которой устаревшая документация хуже отсутствующей: ей верят. Отсутствие процедуры заставляет посмотреть в код, наличие неверной — нет.
Отсюда практическое следствие. Скилл заводится не когда «полезно бы», а когда цена его отсутствия выше цены поддержки. Для процедуры, которая применяется раз в квартал и каждый раз чуть иначе, дешевле не иметь скилла.
Шестнадцать штук и почему не пять
В блоге сейчас шестнадцать скиллов. Общий объём — около девятисот шестидесяти строк, от восемнадцати строк в самом коротком до ста шестидесяти трёх в самом длинном.
Набор удобно делить на три группы; ниже — характерные примеры.
Про способ работы — developer, code-review, repo-discovery, visual-qa, a11y-check, frontend-design. Эти почти одинаковы во всех моих проектах и переезжают из репозитория в репозиторий с правкой команд. Про них будет отдельная статья цикла.
Про предметную область блога — generate-blog-image, publish-workflow, seed-content, seo-structured-data, legal-pages. Вот это ценность, которой нет нигде, кроме этих файлов. Ни из кода, ни из общих знаний о Laravel правила публикации в блоге не выводятся.
Про инфраструктуру проекта — filament-resource, ckeditor-shared-sync, ecosystem-map. Процедуры, завязанные на конкретные решения: раскладку ресурсов админки, общий редактор, связи между сайтами.
Почему не пять: пять покрывают только первую группу, то есть общий способ работы, который и без файлов воспроизводится прилично. Вся польза — во второй группе, а она по определению не сокращается.
Почему не пятьдесят: каждый скилл — это ещё одно описание, конкурирующее за срабатывание. Когда описания начинают перекрываться, выбор становится случайным, и вместо процедуры подключается соседняя. У меня это случилось на паре скиллов про изображения, которые пришлось слить в один.
Как понять, что скилл лишний
Три вопроса, на которых у меня отсеивается большинство кандидатов.
Применялся ли он за последние два месяца? Если нет — либо условие срабатывания написано плохо, либо процедура не нужна.
Отличается ли его содержимое от того, что и так будет сделано? Скилл, который пересказывает общие практики фреймворка, не добавляет ничего. developer у меня выжил только потому, что в нём записаны конкретные решения проекта, а не «пишите тонкие контроллеры».
Пересказывает ли он другой скилл? Дублирование между скиллами — самый быстрый способ получить противоречие: правишь один, забываешь второй.
Что осталось
Шестнадцать — это не целевое число, а текущее. Оно росло медленнее, чем хотелось: за последние месяцы добавилось три штуки, и все три — по третьему повтору объяснения, ровно по правилу.
Чего у меня нет — ревизии. Ни один скилл я ещё не удалял, хотя подозреваю, что два из шестнадцати не срабатывали ни разу. Проверить это нечем: инструмент не показывает, какие скиллы подключались, а вести учёт вручную я не собираюсь. Так что список из трёх вопросов выше — пока теория, которую я применяю на глаз.
