Первое время я не мог внятно объяснить, чем скилл отличается от субагента. Оба — markdown-файл с фронтматтером. Оба описывают, как делать работу. Оба подключаются по описанию.
Разница нашлась, когда я перестал сравнивать их по форме и посмотрел на вопрос, на который каждый отвечает.
Два разных вопроса
Скилл отвечает на вопрос «что делать и в каком порядке». Это процедура: публикация статьи, создание ресурса админки, ревью патча, построение карты репозитория.
Субагент отвечает на вопрос «кому поручить». Это исполнитель с зоной ответственности, набором прав и своим контекстом.
Одна процедура может выполняться разными исполнителями. Один исполнитель применяет разные процедуры. Связь многие-ко-многим, и попытка слить их в одну сущность разваливается на первой же задаче.
В общем виде я формулирую это так, и эта же формулировка лежит у меня в описании каталога скиллов:
.ai/skills/ — что делать и как это делается в этом репозитории
.ai/agents/ — специализированные исполнители, которым делегируют
задачу с ограниченной зоной; ссылаются на скиллы
как на спутниковАгент ссылается на скилл
Практически связь выглядит как ссылка в теле агента.
У меня агент публичного фронта не содержит правил про изображения и разметку для поиска. Вместо этого в нём стоит:
Растровые картинки и OG-визуалы — через скилл generate-blog-image;
мета-теги и JSON-LD — через скилл seo-structured-data.Агент бэкенда отправляет к скиллу про ресурс админки и к скиллу про контент в сидерах. Агент разведки — к скиллу про карту репозитория.
Смысл ссылки — не сэкономить строки, а не дублировать процедуру. Процедура генерации обложки одна, а обращаются к ней трое: агент фронта, агент контента и я сам. Если бы она была расписана в теле каждого, я бы правил её в трёх местах и в двух забывал.
Обратная ссылка тоже есть, но слабее: у скилла бывает агент-спутник. В соседнем проекте это оформлено таблицей:
code-review ← code-reviewer
repo-discovery ← flow-orchestrator
visual-qa ← visual-qa
a11y-check ← a11y-reviewer
developer ← backend-symfonyСовпадение имён в трёх строках из пяти — не случайность и не порядок. Это след того, как набор рос: сначала появился скилл, потом под него завёлся исполнитель, и имя переехало вместе с содержимым.
Таблица маршрутизации
Третий элемент, без которого первые два не складываются: таблица в AGENTS.md, где для типа задачи назван агент и скилл.
| Задача | Скилл / агент |
|-----------------------|----------------------------------------|
| Публикация поста | publish-workflow |
| Посты, рубрики, SEO | агент content-seo, seo-structured-data |
| Политика / рассылка | legal-pages |
| OG-обложки | generate-blog-image |
| Общий CKEditor | ckeditor-shared-sync, агент ckeditor-sync |
| Интерфейс | frontend-design → visual-qa, a11y-check |Шесть строк. Не полный справочник по набору, а список того, что я делаю чаще всего.
Полезное наблюдение: в половине строк агента нет вообще. Публикация поста — это процедура, которую я выполняю сам, читая скилл. Заводить под неё исполнителя незачем: зона не выросла, делегировать нечего.
Стрелка в последней строке означает порядок: сначала правки интерфейса по своему скиллу, потом визуальная проверка и доступность. Это единственная строка таблицы, где записана последовательность, и она там потому, что порядок регулярно нарушался.
Что дублировать, а что нет
Правило простое: процедура живёт в одном месте. Дублируется только то, что нужно для маршрутизации.
В теле агента достаточно одной-двух строк о том, когда подключать скилл. Например: «После правок интерфейса — visual-qa». Этого хватает, чтобы не пересказывать процедуру целиком.
Не дублируются: порядок шагов, ограничения, чеклисты. Если в агенте появился чеклист, а такой же чеклист есть в скилле, они разойдутся в течение квартала. Я это проходил с проверками ревью: часть жила в теле агента, часть в скилле, и я правил то одно, то другое, пока не свёл всё в скилл.
Отдельный случай — команды. Форма вызова консоли внутри контейнера у меня записана и в файле контекста, и в теле пишущих агентов, и в скилле про повседневную разработку. Три копии, и я сознательно их держу: команда меняется раз в год, а нужна она в каждой второй задаче, и путь к ней должен быть коротким.
Типичная ошибка: процедура пополам
Самая частая моя ошибка в этой паре — размазать одну процедуру между агентом и скиллом.
Выглядит это так. Скилл про публикацию описывает шаги от черновика до публикации. Агент контента в теле описывает, что проверить после публикации: ленту, карту сайта, канонические адреса. Формально разделение осмысленное: скилл про процедуру, агент про проверку.
Фактически это одна процедура, разрезанная пополам. Тот, кто читает скилл без агента, не знает про проверку. Тот, кто читает агента без скилла, не знает порядка. И я, правя одно, забываю про второе.
Признак, по которому ловлю: если в теле агента появляются пронумерованные шаги — скорее всего, это кусок скилла. У агента должны быть зона, среда, правила и формат ответа. Шаги — не его жанр.
Обратный признак: если в скилле появляются слова «делегируй», «передай агенту» — скилл начал заниматься маршрутизацией, и её место в таблице.
Порядок заведения
Что заводить первым, у меня решается однозначно: сначала скилл.
Скилл дешевле. Он не требует решать вопрос о правах и зоне, не конкурирует за срабатывание с другими исполнителями, не создаёт передачу контекста. Пока процедуры две-три, набора агентов вообще не нужно.
Агент заводится, когда зона выросла до состояния, в котором её можно назвать одной фразой и очертить каталогами. У меня агент общего модуля редактора появился примерно через пару месяцев после соответствующего скилла — ровно тогда, когда файлов модуля стало столько, что задача про него перестала помещаться в общий контекст.
Признак преждевременного агента: его тело состоит из ссылок на скиллы и ничего своего не содержит. Такой можно смело удалять, а скиллы вызывать напрямую.
Что осталось
Разделение «скилл — процедура, агент — исполнитель, таблица — маршрут» держится с весны и не потребовало ни одного исключения. Единственное место, где оно скрипит, — агенты, чья зона задана предметной областью, а не каталогом: у них тело и скилл-спутник частично об одном.
Чего нет — проверки на дублирование. Расхождение между скиллом и телом агента я нахожу случайно, обычно когда правлю одно и вспоминаю про второе. На тринадцати репозиториях это уже не смешно, и напрашивается скучный скрипт, который просто ищет одинаковые абзацы в двух каталогах.
