Анатомия скилла для ИИ-агентов: что класть в какую папку
Третий раз за неделю объясняю, как устроен скилл. У Anthropic есть skill-creator skill, но базовые вопросы всё равно всплывают. Рассказываю что есть что, чтобы можно было ИИ-моделям прям к промпту этот пост приложить.
📁 Что такое скилл
Это папка. Внутри всегда обязательно один файл SKILL.md. Рядом — опциональные директории scripts/, references/, assets/. Я добавляю две свои (документация это не запрещает, а агенты радуются): config/ для настроек и авторизации и cache/ для промежуточных данных.
📄 SKILL.md и понятная шапка
Вверху документа всегда frontmatter: блок между двумя --- с полями name и description. Это самая главная часть и причина большинства ошибок.
🚩 Вижу непонятную шапку, всегда запускаю рассказ про анатомию.
Фронтматтер отвечает на два вопроса: что делает скилл и когда его вызывать. Агент решает, грузить ли скилл, по одной этой строчке — она лежит в его системном промпте всегда.
💡 Пишите description языком действий и поведения пользователя. «Когда загрузили шаблон договора» — хорошо. «Реализует entity-модель контракта» — плохо, может не вписаться в сценарий.
Лично я добавляю триггер-слова: «кодекс ревью», «оценка трафика». Повышает стабильность вызова.
📚 References: что выносить из основного файла
Частные сценарии в действиях агента пишите в references/. Пример: в моём https://github.com/artwist-polyakov/polyakov-claude-skills/tree/main/plugins/yandex-wordstat/skills/yandex-wordstat блок про https://github.com/artwist-polyakov/polyakov-claude-skills/tree/main/plugins/yandex-wordstat/skills/yandex-wordstat/references нужен только когда пришла выгрузка из Директа. В каждый вызов скилла грузить описание действий — расточительство.
🧪 Тест на референс: если кусок инструкции работает сам по себе — это отдельный скилл. Если без основного SKILL.md он бессмыслен — это референс.
🚩 Вижу, что в SKILL.md описаны частные случаи работы скилла, рассказываю про references, которые согласно спецификации загружаются по требованию.
🛠 Scripts: чем меньше зависимостей, тем лучше
Тело SKILL.md описывает ход мысли агента. Фрагменты кода туда не пихайте — потратите токены и внимание модели. Код держите в scripts/.
🚩 Вижу, что в SKILL.md у человека фрагменты кода с подстановкой переменных, тут же начинаю рассказывать про внимание и экономию токенов.
Код можно тоже передавать по разному. Моя иерархия реализаций :
🔸 .sh — самое быстрое и переносимое. Большие выводы режутся, поэтому складывайте в cache/tmp/ и читайте другим скриптом.
🔸 uv для Python — меньше задержек при параллельных вызовах, чем у обычного python.
🔸 Go-бинарники — когда важна скорость. Минус: в облачных рантаймах не запустятся.
🔐 Config: токены и ключи
Авторизация для агента (пароли/секреты) кладем в config/. Не в SKILL.md, не в переменных окружения агента. Так скилл легко переносить без утечек секретов в код.
🎨 Assets: шаблоны для красивого вывода
Если на выходе сайт, презентация или дизайн — не давайте агенту каждый раз генерировать стили с нуля. Положите в assets/ готовый шаблон, куда достаточно подставить данные (обычно из JSON). Недельные лимиты будет благодарны.
В комментариях к посту самая популярная презентация от Антропиков по архитектуре скиллов.
---
В следующем посте — когда выбирать скилл, а когда MCP или CLI, и три паттерна.
----
https://t.me/countwithsasha — AI, код и кейсы
