Анатомия скилла для ИИ-агентов: что класть в какую папку

Третий раз за неделю объясняю, как устроен скилл. У Anthropic есть skill-creator skill, но базовые вопросы всё равно всплывают. Рассказываю что есть что, чтобы можно было ИИ-моделям прям к промпту этот пост приложить.

📁 Что такое скилл

Это папка. Внутри всегда обязательно один файл SKILL.md. Рядом — опциональные директории scripts/, references/, assets/. Я добавляю две свои (документация это не запрещает, а агенты радуются): config/ для настроек и авторизации и cache/ для промежуточных данных.

📄 SKILL.md и понятная шапка

Вверху документа всегда frontmatter: блок между двумя --- с полями name и description. Это самая главная часть и причина большинства ошибок.

🚩 Вижу непонятную шапку, всегда запускаю рассказ про анатомию.

Фронтматтер отвечает на два вопроса: что делает скилл и когда его вызывать. Агент решает, грузить ли скилл, по одной этой строчке — она лежит в его системном промпте всегда.

💡 Пишите description языком действий и поведения пользователя. «Когда загрузили шаблон договора» — хорошо. «Реализует entity-модель контракта» — плохо, может не вписаться в сценарий.

Лично я добавляю триггер-слова: «кодекс ревью», «оценка трафика». Повышает стабильность вызова.

📚 References: что выносить из основного файла

Частные сценарии в действиях агента пишите в references/. Пример: в моём Wordstat-скилле блок про упущенный спрос нужен только когда пришла выгрузка из Директа. В каждый вызов скилла грузить описание действий — расточительство.

🧪 Тест на референс: если кусок инструкции работает сам по себе — это отдельный скилл. Если без основного 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, и три паттерна.

----

Поляков считает — AI, код и кейсы