Лучшие практики написания скилов✦
Контекст✦
Источник — онбординг-доклад Сергея Будяева (Яндекс, продуктовое развитие кодинговых агентов) с конференции про AI-first разработку. Коллега, поделившийся ссылкой, отметил: «Отличный онбординг-доклад про скиллы с богатым опытом докладчика». Ниже — практики, которые докладчик сформировал за время работы со скилами. Важно: это первичный, операционный набор советов из нашего источника; официальная документация Anthropic приводится как подтверждающий фон.
Практики из доклада✦
- Двигаться от задачи. Скилизовать стоит то, что вы и так часто делаете руками или с агентом и от чего «устали», а не оборачивать всё подряд ради самого факта. Хороший кандидат — ваша рутина или экспертиза.
- Итеративность. С первого раза хорошо не выйдет. Докладчик приводит пример инженера (из Supabase), который доводил один скил около двух месяцев, отлавливая корнер-кейсы и работая с фидбеком — это нормально.
- Не пихать всё в
SKILL.md. Держать его примерно до 5000 токенов (а описание — до ~100 токенов), остальное выносить в референсы и скрипты в папке скила: благодаря progressive disclosure они подгружаются по необходимости. - Просить скил валидировать собственную работу — прямо в инструкции закладывать алгоритм самопроверки (например, «проверь, создал ли ты евалы»).
- Вкладываться в
description. Именно описание отвечает за автовызов скила. Не ждите идеала сразу — нормально, что агент не всегда зовёт скил; описание тоже нужно евалить, подбирая формулировки. - Не включать общеизвестную информацию, которую сильная модель и так знает.
- Не полагаться на полную автогенерацию. Автогенерация допустима, но
результат обязательно нужно вычитывать — иначе скил распухает «булшетом»,
как это было с автогенерируемыми
AGENTS.md/CLAUDE.md. - Евалы упрощают оценку качества: это JSON-кейсы (задача + ассерты), которые прогоняются дважды — со скилом и без. В демо это дало 100% прохождение со скилом против ~42% без него и сразу показывает, какая информация лишняя.
Подтверждение во внешних источниках✦
Официальный гайд Anthropic совпадает с опытом докладчика: «Concise is key»,
презумпция «Claude is already very smart» (добавлять только то, чего модель не
знает), SKILL.md под 500 строк / 5000 токенов, progressive disclosure через
референсы и скрипты, критичность description для обнаружения, разработка
от евалов («Build evaluations first») и итеративная доводка. Каталоги вроде
skills.sh и фреймворк Superpowers — места, где можно искать
и подсматривать готовые скилы.