Здарова, работяги!

В прошлый раз разобрались, чем отличаются memory bank, rules, MCP и skills, и сошлись на том, что основной фокус сейчас — связка rules + skills. Сегодня — как я пишу скилы: что стоит оформлять, что нет, и на что обращать внимание.

Коротко напомню разницу

Rules — правила, которые агент держит в контексте всегда и применяет на каждой задаче.
Skills — переиспользуемые сценарии. Агент знает, что они есть и когда их доставать, но не держит целиком в контексте.

Две главные мысли

Первая: если проблему можно решить не скилами и не рулами — решаем не скилами и не рулами.
Линтеры, форматтеры, тайпчек, скрипты, кодгены — надёжнее и дешевле любого guidance. Не забывают, не жгут токены, не интерпретируют инструкцию творчески. Скилы и рулы — это то, к чему приходим, когда автоматикой уже не получается.

Вторая: скилы не пишем впрок.
Отношусь к ним как к коду — пишу по мере необходимости. Со временем набирается своя база, и появляется чувство:
• какие скилы я всегда тащу в новый проект, потому что они проверены опытом;
• какие подключаю ситуативно — например, для React-проекта имеет смысл взять скилы Vercel про React(но не все);
• какие пишу с нуля под конкретные грабли, которые увидел в работе агента.

Скилл «на будущее» обычно не попадает в реальные сценарии и просто висит балластом. А если их много, агент хуже выбирает нужный и описания начинают конфликтовать. Поэтому: увидел поведение, которое не устраивает → если ответ «скилл», только тогда написал.

Алгоритм: что делать, когда хочется добавить guidance

1. Это уже покрыто? Существующий skill, rules, системный промпт, линтер. Если да — обновляю существующее, а не плодю новое.
2. Можно ли решить тулзами? Линтер, тайпчек, скрипт, кодген. Если правило детерминированное — заводим автоматику. Скилл тогда максимум объясняет, что делать поверх тулзы.
3. Это всегда или ситуативно? Всегда и на каждой задаче — rule. Под конкретный тип задач (ревью, новый пакет и тд) — skill.

Как писать сам скилл

Description — самое важное. Агент видит только description в списке доступных скилов и по нему решает, доставать его или нет. Должно быть два блока:
• WHAT: что скилл делает.
• WHEN: триггеры — слова, контексты, типы задач.
Плохо: «помогает с тестами».
Хорошо: «как писать тесты в проекте. Используй при написании, добавлении или рефакторинге test-файлов. Триггеры: ‘написать тест’, ‘покрыть тестами’, ‘тесты падают’».
SKILL.md держу коротким. Ориентир — до 100 строк. Что не влезает — выношу в отдельные файлы и линкую из основного. Глубже одного уровня ссылок не делаю — агент может просто не дочитать.
Прогрессивное раскрытие. В SKILL.md — то, что нужно в 80% случаев. Детали и редкие сценарии — в отдельные файлы.
Один путь, а не пять вариантов. Если в скиле «можно вот так, или вот так» — агент каждый раз выбирает заново и каждый раз по-разному. Даю дефолт и явный запасной вариант для редких случаев.
Конкретные примеры. «Вот вход, вот выход» работает в разы лучше, чем абзац объяснений.
Скрипты вместо генерации. Детерминированную операцию лучше положить готовым скриптом и вызвать, чем описывать «сгенерируй такой-то код». Скрипт надёжнее и не жрёт токены на генерацию.

Резюме
• Сначала пробуем тулзы, потом скилы, в последнюю очередь — rules.
• Скилы не пишем впрок, только по факту.
• В самом скиле: подробное description с WHAT и WHEN, короткий SKILL.md, один путь, конкретные примеры, скрипты для детерминированных операций.

Скилы — это не документация на все случаи жизни. Это набор маленьких заточенных инструментов под сценарии, которые ты уже видел в работе.

В следующий раз могу показать свою личную подборку скилов — глобальные и те, что чаще всего беру в новые проекты. Интересно?