Skills для агентов.
Зачем и как собрать

Задача, из которой растут skills

Модель в терминальном агенте умеет многое. Но она не помнит, как именно у вас принято выкатывать рабочую версию, как не сломать схему с двумя слотами выката, какие статьи КоАП сверять с первоисточником, и что «готово» без свежего вывода команды — это ложь. Каждый раз вбивать это в чат — можно. Через неделю вы устанете, агент «забудет», и снова снесёт символическую ссылку выката или процитирует закон из памяти 2023 года.

Агент в проекте читает корневые гиды, правила по путям, иногда перехватчики команд. Этого хватает, пока процедур мало. Когда появляются повторяющиеся сценарии — «сделай выпуск колонки», «перед выкатом проверь инварианты», «проверь норму по праву РФ», «после доработки подчисти документацию» — корневой гид начинает раздуваться. Всё важное в одном файле значит: всё важное конкурирует за внимание каждый раз, даже когда вы чините одну кнопку.

Проблема не в том, что модель «тупая». Проблема в бюджете внимания — сколько текста и правил агент способен удержать в одной сессии, не потеряв суть. В сессии одновременно живут: системная инструкция, история переписки, открытые файлы, схемы инструментов. Если запихнуть туда полный регламент по авторской колонке (у меня один такой skill — больше 600 строк) плюс юридическую сверку плюс выкат плюс рекламные кабинеты — агент либо не дочитает, либо начнёт смешивать правила из разных областей.

Skill решает это не «силой воли», а устройством хранения. Чтобы не говорить жаргоном, ниже — одна сквозная метафора.

Магазин skills: витрина, полка, склад

Представьте, что вы в магазине. Не в интернет-каталоге, а в обычном: зал, стеллажи, подсобка. Вы не тащите со склада сразу все коробки в тележку — иначе не пройти между рядами. Сначала смотрите витрину: ценники, короткие названия, «для чего это». Если что-то подходит — берёте с полки полную инструкцию. Если нужны редкие детали — идёте в склад за справкой. Так же устроен skill.

Ещё раз, коротко, без магазина. Витрина — это не сайт и не картинка. Это список карточек skills в голове агента на старте сессии: у каждой карточки имя и описание на десятки слов. Агент не читает все 600-строчные регламенты сразу — он смотрит витрину и решает, какой skill открыть. Тело — то, что открывается после выбора. Склад — приложения, которые тело может запросить.

Крючок — это не крючок для пальто. Это описание на витрине, написанное так, чтобы модель узнала вашу задачу («перед выкатом», «проверь договор», «готово?») и не прошла мимо. Если крючок слабый — skill недосрабатывает (висит на витрине, но не берётся). Если слишком широкий — цепляется к чужим задачам.

На диске пакет skill обычно выглядит так (имена папок у оболочек чуть отличаются — смысл один):

имя-навыка/
├── главный файл       # шапка = витрина (имя, описание) + тело инструкции
├── справочники/       # склад: не грузятся, пока не открыл
├── скрипты/           # готовый код для повторяющихся шагов
└── материалы/         # шаблоны и заготовки для результата

Итог в задумке: можно держать десятки skills, не таща полное тело каждого в каждую сессию. Платите вниманием в первую очередь за витрину (все ценники в зале); полку и склад — только по делу. Но если ценников слишком много, зал сам становится проблемой — об этом следующий раздел.

Налог на витрину: когда в зале слишком много ценников

Вернёмся в магазин. «Платите только за витрину, а не за весь склад» — правда относительно полного тела, но не абсолют. Все ценники висят в зале постоянно. Пять–пятнадцать skills — зал просторный. Тридцать–шестьдесят — вы уже не видите товар за ценниками: каждый взгляд на полку стоит сил, а похожие названия путаются.

У агента то же самое. Описания на витрине сидят в поле зрения почти всегда. Когда skills мало — это копейки бюджета внимания. Когда их десятки — налог на витрину: сама витрина становится статьёй расхода, ещё до того как открыли хоть одно тело.

Замер по живым пакетам на одном сервере (июль 2026, 61 оформленный skill с заполненным описанием):

• среднее описание — около 50 слов (медиана 47; хвост до 150+);
• сумма всех описаний — около 3000 слов;
• в пересчёте на куски текста, которые модель «ест» как единицы внимания, это порядок тысяч — грубо от трёх–четырёх тысяч в оптимистичной оценке до заметно большего, если описания на русском и длинные.

Важная оговорка: в одной сессии обычно не висят все skills со всего сервера. Типично — общие плюс skills текущего репозитория. На связке «общий слой + крупный продуктовый проект» это уже около 35 карточек на витрине и снова тысячи единиц внимания только на крючки — ещё до первого файла кода.

Дальше растут не только расход, но и коллизии. Описание делают напористым, чтобы skill не простаивал. Несколько skills про выкат, проверку «готово», рекламный кабинет — и модель начинает путать соседние крючки: подключает не тот регламент или пытается удержать два сразу.

Что делать, когда skills переваливают за несколько десятков:

1. Резать слой, а не только текст. Общее — в пользовательский каталог; узкое — только в репозиторий. Не копировать «на всякий» один и тот же skill во все проекты.
2. Сужать описание. Каждое лишнее предложение на витрине умножается на число skills и на число сессий. «Когда не подключать» иногда важнее, чем ещё один синоним триггера.
3. Выкидывать и сливать. Два skill с пересекающимися крючками хуже одного чёткого.
4. Группировать по смыслу, когда простого деления мало. Семейство (ядро + спутники) вместо россыпи равноправных карточек; отдельный «входной» skill-маршрутизатор в широкую область, детали — в спутниках, которые не обязаны все висеть на общей витрине с одинаковой напористостью. Где оболочка умеет подключать наборы skills пакетами или по проекту — пользоваться этим, а не держать один плоский список на всё.

Коротко: skills снимают налог полного склада с каждой сессии. При масштабе налог переезжает на витрину — и залом (списком ценников) тоже надо управлять: меньше похожих карточек, чётче «когда брать / когда не брать», семейства вместо россыпи.

Skill, правило, вспомогательный агент — три разных ящика

Кратко, без пересказа отдельного выпуска про операционный слой.

В шапке файла поля называются по-разному у skill и у карточки вспомогательного агента. Путать имена — мелочь, из-за которой агент молча игнорирует ограничение на инструменты.

Ещё один нюанс с рабочей среды: skill можно закрыть от самозапуска моделью. В одном продуктовом репозитории skill выката помечен так, что его запускает только человек командой, а модель сама на рабочую версию не выкатывает. Это уже не «инструкция», а ворота: регламент есть, автономии нет.

Что выросло, когда skills жили месяцами

Я не проектировал «классификацию skills» заранее. На сервере с несколькими проектами просто копились файлы. Когда разложил все оформленные пакеты (июль 2026), получилась такая картина:

Общие — то, что повторяется везде: уборка после доработки, проверка свежести фактов про модели, навигация по коду через граф связей, рекламные кабинеты (Яндекс Директ, VK, Авито), подключение второго терминального агента. Проектные — инварианты этого выката, этой схемы данных, этого контента.

Сами типы — как они сами назвались по смыслу, не по папкам:

1. Жёсткие предохранители. «Перед любой правкой выката / шапки урока / баланса — прочитай это». Описание начинается с «Используй ПЕРЕД…», «ловит ошибку уровня инцидента…». Тело — запреты с причиной: почему сборка «напрямую», в обход скрипта выката, ломает схему с двумя слотами; почему пропуск обязательного поля в шапке урока валит всю сборку. Без skill агент «логично» чинит рабочую версию неправильной командой.

2. Проверка перед «готово». Железное правило: не писать «готово», пока в этом же сообщении нет свежего вывода проверки. Клоны этого приёма расползлись по проектам — значит, боль общая. Рядом — уборка после доработки: документация, типы, синхронизация инструкций между двумя терминальными агентами.

3. Регламенты предметной области. Длинные: авторская колонка (больше 600 строк плюс файл блоков оформления), мобильный интерфейс, режиссура видео со справочниками по форматам и озвучке. Это не «запрет», а полный конвейер от входа до готового результата.

4. Регламенты кабинетов и внешних сервисов. Рекламные кабинеты: техника безопасности (форматы чисел, запись только по явной просьбе), карта проектов в кабинете, «сначала готовый инструмент агента, не сырой запрос в обход». В одном продукте поверх общего skill по Директу лежат ещё четыре проектных: встраивание в код, запуск, семантика, фильтр нереалистичных ожиданий.

5. Skills только как текст. В конвейере графа знаний у части skills список разрешённых инструментов пустой. Это не баг: skill вшивается в системную инструкцию извлекателя как рубрика качества, без цикла «взял инструмент — сделал шаг». Skill — не обязательно «агент с инструментами». Иногда это контракт, каким должен быть ответ.

6. Пакеты с постепенной подгрузкой. Расширения для браузера: больше 500 строк тела плюс десятки справочников. Мобильный интерфейс: короткое тело плюс десять справочников. Режиссура видео: около 85 строк-маршрутизатора плюс четыре тяжёлых справочника. Приём один: в главном файле — куда идти, детали — на полке.

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

Как устроен skill, который срабатывает

1. Описание на витрине — восемьдесят процентов успеха

Плохо:

Помогает с выкатом.

Хорошо (сжатый смысл реальных предохранителей):

Обязательные правила выката. Используй ПЕРЕД любой правкой скрипта выкладки, перед сборкой, перед переиндексацией поиска. Ловит: прямую сборку в обход скрипта (ломает схему с двумя слотами), выкат не из корня проекта, перезапуск общих сервисов без запроса.

В описание кладут: что / когда (фразы человека и ситуации) / какую катастрофу предотвращает. Без третьего агент считает skill необязательной справкой.

2. Тело — алгоритм, не эссе

Работающая структура тела:

1. Зачем (один абзац) — цена ошибки. Модель лучше соблюдает правило, когда понимает почему, а не когда видит «ОБЯЗАТЕЛЬНО» капсом.
2. Когда включать / когда нет — границы области.
3. Пошаговый алгоритм — нумерованный, с ветками «если так — то иначе».
4. Формат результата — шаблон отчёта, структура документа, список «готово».
5. Ссылки на справочники — «источники — в папке справочников, читай когда дошёл до шага N».
6. Жёсткие запреты — коротко, в конце или в выделенном блоке, с причиной.

Повелительное наклонение («проверь», «открой», «не цитируй по памяти») читается надёжнее, чем «следует рассмотреть возможность проверки».

3. Справочники — то, что меняется или раздувает тело

В юридическом пакете (ниже) список первоисточников и «западные ловушки» вынесены из ядра. В skill выката нет смысла тащить полный справочник по веб-серверу: достаточно «не трогай общий веб-сервер без запроса» и отсылки к операционной документации. Правило: если блок нужен в одном запуске из десяти — в справочники.

4. Скрипты — когда агент каждый раз пишет один и тот же код

Если три прогона skill подряд заканчиваются тем, что агент заново пишет один и тот же вспомогательный скрипт — положите скрипт в пакет и скажите «используй его». Повторяемый код дешевле, чем «каждый раз чуть другая самодельная программа».

5. Список разрешённых инструментов

По желанию. Сужает руки: skill авторской колонки не обязан ходить в биллинг. Skill уборки после доработки — наоборот, явно просит граф кода. Пустой список — «только текст, без инструментов». Не ставьте ограничение «на всякий случай»: либо осознанное сужение, либо не трогайте.

Эталон семейства: пакет skills по праву РФ

Внешний пример — собранный пакет skills, не «статья про закон». Четыре skill, одна ось:

юрист-рф/
├── фактчек-права/          # ЯДРО: норма только из первоисточника
│   ├── главный файл
│   └── справочники/
│       ├── источники       # иерархия: pravo.gov.ru → Консультант/Гарант
│       └── западные-ловушки  # «возмещение любых убытков», европейские ПДн-кальки…
├── анализ-рисков/          # «какие риски» → зовёт фактчек
├── составление-документов/ # «составь договор, оферту, документы по ПДн»
│   └── справочники/шаблоны
└── проверка-документа/     # «проверь договор» → фактчек + шаблоны

Почему это хороший устройство skills, даже если вы не юрист:

Одно ядро, спутники без копирования. Фактчек держит алгоритм: отрасль → первоисточник → редакция на дату → смежные нормы → фильтр западных конструкций → формат ответа со ссылкой. Анализ рисков, составление и проверка не дублируют список источников — пишут «проверь нормы по ядру фактчека». Меняется иерархия источников — правите одно место.

Описание = зона ответственности, не красивое имя. У фактчека: «ВСЕГДА когда вопрос про российское законодательство… Не отвечай по памяти — сначала найди и проверь». У проверки документа: «когда просят проверить договор, оферту, согласие…». Пересечения осознанные: риски опираются на фактчек; проверка знает структуры составления.

Формат результата зафиксирован. Риски отдают список с вероятностью, тяжестью и статьёй. Проверка — красный / жёлтый / зелёный плюс «как исправить». Составление — документ с местами для заполнения плюс короткая записка. Модель меньше «творчески» размазывает структуру.

Свежие ориентиры отдельно, с оговоркой «всё равно перепроверь». В ядре — блок «реперные точки актуальности на июнь 2026» (оборотки за утечки персональных данных, раздельные согласия с 1 сентября 2025 и так далее). Это честно: skill не притворяется вечной истиной, он учит процедуре сверки.

Цена без skill. Модель охотно цитирует «статью N» из того, на чём её учили. Для кода это «устаревший способ вызвать сервис». Для права — решение, на котором бизнес подписывает договор. Здесь skill — не удобство, а стоп-кран выдуманного номера статьи.

Связка с другим жанром работы: отдельный выпуск про правовую сборку документов агентами — про конвейер и сверку с продуктом. Здесь — про то, какими файлами вы кодируете юридическую методику, чтобы любой агент в любом чате не импровизировал.

Как собрать свой skill с нуля

Шаг 0. Поймите, что вы упаковываете

Хороший кандидат:

• процедуру вы объясняли агенту дважды и больше;
• ошибка дорогая (рабочая версия, деньги, персональные данные, закон, данные пользователей);
• есть чёткие шаги и/или формат результата;
• объём не влезает в трёхстрочное правило.

Плохой кандидат:

• «будь вежлив» → правило;
• «разбери вот этот разовый вопрос» → просто сессия;
• «сделай всё за меня в изоляции с другим набором инструментов» → вспомогательный агент.

Шаг 1. Напишите описание на витрине раньше тела

Один абзац: что / когда / какая боль. Прогоните мысленно пять фраз человека — skill должен «узнать» минимум четыре. Добавьте две похожие фразы, на которых не должен срабатывать (смежная область).

Шаг 2. Вытащите алгоритм из лучшей сессии

Не сочиняйте с нуля. Откройте чат, где агент уже сделал правильно после ваших правок. Выпишите:

• какие инструменты вызывал;
• какие файлы читал;
• где вы его поправили («нет, сначала вот это»);
• какой вид результата вы приняли.

Это и есть тело skill. Ваши устные «нет, сначала…» — самые ценные строки.

Шаг 3. Разрежьте на уровни подгрузки

• Всё, что нужно всегда при срабатывании → тело.
• Всё, что нужно иногда или больше одного-двух экранов таблицы → справочники.
• Всё, что агент заново пишет кодом каждый раз → скрипты.

Если тело лезет за 400–500 строк — вы уже опоздали с нарезкой. Исключения бывают: один жирный регламент лучше, чем десять недописанных; но тогда внутри обязателен указатель «куда идти дальше».

Шаг 4. Положите в правильный слой

Универсальный тон «как отвечать на возражения» — в общий гид, не в skill проекта. Skill проекта, который копируют во все репозитории руками и забывают обновить, — рассинхрон. Либо общий слой, либо один источник правды и явная синхронизация (у меня skill уборки как раз про выравнивание инфраструктуры двух терминальных агентов).

Шаг 5. Проверьте крючок и вред

Два прогона одной задачей:

1. Со skill (новый чат, та же формулировка).
2. Без skill (контрольный прогон).

Если со skill не лучше — описание не цепляет, тело вода, или это должно быть правило. Если со skill лучше, но агент тащит его в соседние задачи — описание слишком широкое, сузьте.

У крупных поставщиков есть средства прогона проверок и подстройки описания «должен сработать / не должен». Для личного стека часто хватает трёх ручных прогонов. Для skill, от которого зависят деньги или право, формальные проверки окупаются.

Типичные провалы (с ценой)

Мёртвый или устаревший skill (дрейф). Дрейф — это просрочка на полке: ценник всё ещё зовёт, содержимое внутри уже не то. Поддержание десятков skills — отдельная работа, не побочный эффект «написали и забыли». На живом сервере часть пакетов обновляют еженедельно, часть лежит месяцами: инфраструктура уже другая, а инструкция всё ещё учит старому пути.

Устаревший skill часто опаснее его отсутствия. Нет skill — модель импровизирует, лезет в гиды, спрашивает, ошибается «в открытую». Есть skill, который врёт, — модель уверенно идёт по локальной инструкции: старый скрипт выката, старая схема данных, норма закона в редакции прошлого года. Ошибка выглядит как «я сделал по регламенту», а не как «я не знал». Ревизия из раздела с заготовками — не церемония, а стоп-кран: удалить, слить, переписать, либо явно пометить «не использовать, пока не сверили».

Простыня без справочников. 600 строк в теле без карты «когда читать что» — агент прочитает середину и потеряет хвост. Либо указатель плюс справочники, либо режьте.

Описание-загадка. «Утилиты проекта». Не сработает никогда. Или сработает всегда — ещё хуже.

Раздутая витрина. Пятьдесят напористых описаний в одной сессии — уже налог и риск коллизий. См. раздел про налог на витрину: резать слой, сужать крючки, сливать соседей.

Skill вместо правила. «Не пиши в основную ветку» — это постоянное правило или перехватчик, не skill. Skill подключается по задаче; запрет ветки нужен всегда.

Skill вместо вспомогательного агента. «Проверь сорок файлов и не отравь основной контекст» — запуск с изоляцией. Skill в том же контексте просто добавит инструкцию, не очистит историю.

Копирование ядра в каждый спутник. Четыре юридических skill с четырьмя копиями списка источников — через месяц четыре разных правды. Ядро плюс ссылка.

Устаревшие числа в теле без процедуры сверки. Цены моделей, редакции федеральных законов, «лимит N». Либо «перепроверь на дату», либо отдельный skill проверки свежести, либо вынос в справочник с датой. Это частный случай дрейфа — только внутри одного абзаца.

Дубли: оформленный пакет, плоский файл и правило на одну тему. Агент читает противоречия и выбирает наугад. Один источник правды; остальные — ссылки или удаление.

Только витрина готовых плагинов. Плагины закрывают общее. Ваш выкат, ваш биллинг, ваше право из витрины не приедут. Свои skills — это и есть слой операционки, который конкурент не скачает одной кнопкой.

Три заготовки, которые можно отдать агенту

Ниже — рабочие тексты. В копируемых блоках длинные тире заменены на запятые и двоеточия: так удобнее в рабочих файлах.

Собери skill из нашего текущего диалога.

1. Найди процедуру, которую я поправлял или повторял: шаги, инструменты, файлы, формат результата.
2. Предложи:
   - имя (строчные латинские буквы и дефисы, как принято у skills)
   - описание для витрины: что делает + когда подключать (фразы) + какую ошибку предотвращает
   - слой: общий или проектный (и почему)
3. Напиши главный файл skill:
   - зачем (цена ошибки)
   - алгоритм по шагам
   - формат результата
   - что вынести в справочники или скрипты
4. Не пиши воду. Не дублируй то, что уже есть в гидах агента или в правилах, дай ссылку.
5. Покажи дерево файлов пакета и 5 тестовых фраз: 3 должны включать skill, 2 не должны.

Проведи ревизию skills в этом репозитории и (если есть доступ) в общем каталоге skills.

Для каждого skill:
- одна строка: имя, строк в теле, слов в описании на витрине, есть ли справочники и скрипты
- оценка описания: сработает ли на реальной задаче, будет недосрабатывать или пересрабатывать (коллизия с соседом)
- тип: предохранитель / проверка / регламент / кабинет / другое
- дубли и противоречия с правилами и гидами агента
- дрейф: сверь ключевые команды, пути, схемы, версии и запреты с текущим кодом и доками. Если skill учит тому, чего уже нет, пометь: удалить / переписать / не использовать

В конце:
1. топ-5 skills, которые реально спасают от инцидента
2. топ-5 кандидатов на удаление или слияние (включая мёртвые и устаревшие: устаревший опаснее отсутствия)
3. один skill, который стоит разрезать на ядро и справочники
4. оценка налога на витрину: сколько skills реально попадают в одну сессию, какие описания раздуты, где сузить крючки
5. список недостающих: процедуры, которые мы делаем руками, но ещё не упаковали

Спроектируй семейство skills под область: [ОБЛАСТЬ].

Требования:
- одно ядро (источники истины + алгоритм сверки)
- 2-4 skill-спутника с узким описанием на витрине
- спутники не копируют ядро, а ссылаются на него
- у каждого: формат результата и типичные провалы
- постепенная подгрузка: что в главном файле, что в справочниках

Сначала дерево и описания всех skills, потом тексты по одному, начиная с ядра.

Развязка

Skills — это способ не держать всю операционку в голове модели и не пересказывать её в каждом чате. Как в магазине: на виду — витрина (ценники-крючки), по выбору — полка (тело, алгоритм с ценой ошибки), по нужде — склад (справочники). Семейства skills (ядро и спутники) масштабируются лучше, чем один гигантский файл «как делать всё».

Два предела. Перегруженный зал (витрина при десятках skills) сам жрёт внимание и плодит путаницу — режут слоями, сужают крючки, группируют. Просрочка на полке (дрейф) опаснее пустой полки: мёртвый skill подставляет уверенной ошибкой, а отсутствие skill лишь заставляет модель искать заново.

На живом сервере их набралось больше шестидесяти оформленных пакетов не потому, что «так модно», а потому, что каждый вырос из повтора или из инцидента: сломанный выкат, устаревшая норма, «готово» без проверки, рассинхрон двух терминальных агентов. Витрина плагинов закрывает общее. Ваше — пишете вы. И вы же раз в какое-то время выкидываете то, что уже врёт.

Начните с одного skill на самую дорогую повторяющуюся ошибку. Описание напишите так, будто от него зависит, откроет агент инструкцию или снова импровизирует. Обычно импровизация — и есть та ошибка, которую вы уже оплачивали.