Скиллы в Claude Code: из чего состоят и как работают

Последнее время про скиллы говорят все. Ютуб завален туториалами: как сделать скилл, как скачать скилл, «10 скиллов, которые приносят мне три миллиона в минуту». Нельзяграм страшно открывать.

И почти везде скилл подают как волшебство: подключил — и агент пишет код без ошибок, воду превращает в вино. А вот как эта штука устроена внутри — почему-то никто не объясняет. Хотя именно от этого зависит, будет твой скилл работать или молча отвалится.

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

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

Делать скиллы руками, кстати, необязательно: есть

от Anthropic и

от Superpowers — навыки, которые пишут другие навыки. Но чтобы проверить, что они там наделали, и починить, когда не работает, всё равно надо понимать, как оно устроено. Ради этого и статья.

Начнём с вопроса, который возникает первым: чем скилл отличается от обычного промпта.

Аналогия. Если модель — это мозг агента, RAG и memory bank — долгосрочная память, контекст — краткосрочная, а MCP — руки-базуки (в смысле, и руки, и инструменты сразу), то скилл — это средне-специальное образование агента. Диплом ПТУ. Твой Клод не просто прочитал в интернете инструкцию, как пользоваться сварочным аппаратом, — он его купил, отучился на сварщика и ждёт заказы.

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

И тут легко заметить: это же промпт. Задаёшь роль, даёшь чёткие инструкции и примеры — получаешь то же самое.

Отчасти так и есть. Но с важной оговоркой, которую хорошо показывает один эксперимент.

Vercel — те самые, кто сделал Next.js, самый модный способ собирать сайты. Они сравнили два подхода к тому, как скормить агенту документацию по Next.js: специальный скилл с этой документацией и обычный файл

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

Результаты по прохождению их тестов:

Скилл сам по себе не дал ничего — те же 53%, что и без него. Причина: в 56% случаев агент просто не догадался его открыть. А

открывать не надо — он всегда в контексте, проигнорировать нельзя.

Вывод из этого не «промпты лучше скиллов». Вывод точнее: скилл силён не содержанием, а тем, вызовется он или нет. Можно написать гениальную инструкцию, но если агент до неё не дошёл — толку ноль. Дальше половина статьи будет про то, как повысить шанс вызова.

Проблему «где хранить промпты и как их не копипастить руками» Claude Code решил ещё до скиллов — через команды. Жмёшь косую черту, выбираешь из списка готовых действий. Под капотом никакой магии: команда — это просто заранее написанный промпт, который подставляется в диалог.

Скиллы выросли отсюда напрямую. Сегодня в Claude Code команды и скиллы фактически слились в одну сущность. Команды ещё можно создавать, но нужды в этом почти нет. Полезная деталь на будущее: если команда и скилл называются одинаково, приоритет у скилла.

Причём самый важный.

(у остальных инструментов —

, разница только в названии) попадает в контекст в момент запуска агента и висит там всю сессию. Именно с ним, а не с чем-то экзотическим, конкурирует скилл.

Документация даёт простое правило, когда что использовать:

Выноси инструкцию в скилл, когда секция

выросла из «факта» в «процедуру».

Пара строк про стиль кода — пусть живут в

. Многошаговый процесс, длинный чек-лист, сложная последовательность — в отдельный скилл. Смысл ровно в управлении контекстом:

занимает место всегда, а скилл подгружается только когда реально нужен.

держим компактным, тяжёлое прячем в скиллы и достаём по требованию.

Вот тут и проступает стержень. Скилл выигрывает у промпта не «мощностью инструкции». Он выигрывает тем, что не засоряет контекст, пока не понадобится. А не отупевшая от переполненной памяти нейронка работает заметно лучше. Это и есть весь секрет — не магия, а гигиена контекста.

С точки зрения назначения Anthropic делит скиллы на три типа:

И отдельная категория поверх этой — мета-скиллы, то есть скиллы для работы с другими скиллами. Из тех, что не страшно рекомендовать:

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

Технически скилл — это папка на диске. Внутри обязателен один файл,

(именно так, капсом), — инструкция для агента. Опционально рядом лежат ещё три папки:

(документация),

(исполняемые скрипты) и

(шаблоны). Без них скилл работать будет; без

— нет.

Сама папка скилла лежит внутри папки

, а та — внутри папки

.

Папка

появляется в домашней директории сразу после установки Claude Code, даже если ты его ни разу не запускал. Точка в начале имени означает «скрытая»: через Finder или Проводник её не видно. Чтобы заглянуть — либо терминал, либо редактор кода (IDE). Самый распространённый бесплатный вариант — VS Code.

От того, где лежит папка

, зависит область действия скилла и его приоритет при совпадении имён. Уровней четыре.

Enterprise. Для компаний. Такие скиллы спускают сверху администраторы, и у них наивысший приоритет для всех сотрудников. Физически они не в

, а подгружаются через корпоративный аккаунт в облаке Anthropic. Смысл — держать всех на утверждённых процессах: чтобы не тащили скиллы откуда попало и не занесли заразу. Можно, например, вовсе запретить выполнение команд в терминале из скиллов или принудительно включать и выключать конкретные навыки.

Personal. Скиллы в

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

и проектный

— Клод возьмёт персональный.

Персональные скиллы Claude Code видит в реальном времени: правишь тело или файлы скилла прямо во время сессии — изменения применяются сразу, перезапуск не нужен. Исключение — если во время сессии создать новую папку с новым скиллом: вот тут сессию придётся перезапустить.

Project. Скиллы конкретного проекта. Самый низкий приоритет: видны только внутри проекта и любую коллизию с персональными или Enterprise проигрывают. Их смысл — общий доступ команды, поэтому обычно их коммитят в Git вместе с кодом.

Важная тонкость: проектные скиллы загружаются не только из текущей папки, но и из всех родительских — вплоть до корня Git-репозитория. Запустил Клода в подпапке — он сначала посмотрит скиллы рядом с собой, потом поднимется уровнем выше, потом ещё, до самого корня. На практике: у всего сайта есть общий набор скиллов (правила кода, деплой), а у отдельного сложного компонента — скажем, биллинга — свой. Запускаешь Клода внутри биллинга — он видит и локальные скиллы биллинга, и общие скиллы всего проекта.

Plugin. Особняком. Плагинные скиллы в игры с коллизиями имён не играют, потому что вызываются с префиксом:

— например,

. Лежат они тоже в

, но обособленно — внутри директорий своих плагинов, а те — внутри своих маркетплейсов. Путь к официальному скиллу Anthropic

выглядит так:

Уровни у самих плагинов почти те же — Enterprise, Personal, Project, — но, в отличие от скиллов, плагин ещё прописывается в конфиге проекта. Конфигов два:

(общий, его коммитят в Git) и

(личный, коммитить не принято).

Файл

состоит из двух частей: шапки (frontmatter) в формате YAML и тела — самой инструкции.

YAML — это способ записать настройки в виде «ключ: значение», удобный и человеку, и программе. Frontmatter — блок метаданных в начале файла: он говорит агенту, какие скиллы у него вообще есть, когда их применять и как выполнять.

Стандартов оформления скилла сегодня три:

Минимальные требования у Claude Code предельно мягкие: папка в нужном месте + файл

+ хоть какая-то инструкция внутри. Обязательных полей в шапке нет вообще. А вот у стандарта Agent Skills два поля обязательны —

и

.

Дальше пойдём по полям. Сначала — список всех полей и их поддержки по стандартам, потом разбор каждого поля по группам.

Это самые важные поля. Помните вывод из эксперимента Vercel — скилл бесполезен, если агент его не открыл? За открытие отвечают ровно эти три поля.

name. У Claude Code необязательно: если не задать, именем станет имя папки. Ограничение — не больше 64 символов (в обоих стандартах); длиннее — ошибка, скилл не заработает. Имя папки должно совпадать с именем скилла. Рекомендуемый стиль —

: нижний регистр и дефисы.

description. Формально для Claude Code лишь рекомендуется, но по факту это фундамент: именно по описанию агент решает, открывать скилл или нет. Нет описания — сам он скилл никогда не вызовет (останется только ручной вызов через слэш-команду).

Как писать описание — три правила, каждое неочевидное:

Идеальное описание получается примерно таким: «Используй этот скилл для генерации картинки. Этот скилл использует Nano Banana».

И бонус, подтверждённый экспериментом на 650 вызовах: если начать не с «используй этот скилл», а с «ВСЕГДА используй этот скилл», шанс вызова растёт в 20,6 раза (разбор с цифрами).

when_to_use. Список конкретных триггеров — слов и фраз, при которых скилл должен подхватываться: «сгенерируй картинку», «нарисуй картинку» и так далее.

Про лимиты этих двух полей отдельно, потому что о них легко споткнуться. В стандарте Agent Skills на описание — 1024 символа. У Claude Code — 1536, но это лимит на

и

вместе: при наличии второго поля они склеиваются и грузятся в контекст одним куском. Превысил лимит — Claude Code молча обрежет хвост. А так как обрезается конец, первыми под нож идут именно триггеры (

стоит после описания). Мораль: самое важное — в начало описания.

context. Одно осмысленное значение —

, и это едва ли не самое мощное поле во всей шапке.

Без него тело скилла просто вливается в текущий контекст: та же модель, тот же диалог, вся история на месте — Клод берёт и делает то, что написано.

С

Claude Code поднимает отдельного свежего субагента с чистым контекстным окном. Тело скилла становится для него промптом, историю основного диалога он не видит, а по завершении возвращает в главный диалог только сводку о проделанной работе. Это разгружает основной контекст и позволяет запускать тяжёлые многошаговые процессы, не засоряя главную сессию.

Покажу на своём примере — так понятнее. У меня есть большой скилл, который пишет учебные задачи для практикума по n8n. В главной сессии сидит оркестратор. Я пишу ему: «собери модуль по Data Tables». Модуль к этому моменту уже спроектирован (ресёрчи, консультации с методистами и экспертами по n8n — всё это тоже агенты), материалы для сборки готовы.

Оркестратор берёт план и форкает скилл написания задачи. Внутри форка раннер:

Раннер возвращается к оркестратору с отчётом, тот записывает прогресс и дёргает раннер под следующую задачу. На выходе — 10–15 готовых задач за прогон.

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

agent. Работает в связке с

: указывает, какому агенту отдать форкнутый скилл. Можно своего, можно один из трёх встроенных:

allowed-tools. Белый список инструментов, которые скилл вызывает без дополнительного подтверждения:

Тонкость с доверием: персональные скиллы — доверенные, разрешённый инструмент вызывается без вопросов. Проектные — нет: даже с этим списком Клод всё равно переспросит, можно ли ему запустить Python. Логика понятна — проектный скилл мог прийти от кого угодно из команды.

disallowed-tools. Зеркало предыдущего — чёрный список: что скиллу запрещено во время выполнения.

model. Модель, на которой выполняется скилл.

effort. Глубина размышлений при выполнении:

/

/

/

. Чем выше — тем вдумчивее модель и тем больше токенов и времени тратит. (В обычной сессии градаций больше, в скилле набор урезан.)

disable-model-invocation. Если

, Клод перестаёт видеть скилл как инструмент — вызвать его сможешь только ты, вручную через слэш-команду. По умолчанию

.

user-invocable. Наоборот: если

, слэш-командой скилл не вызвать, только модель сама. По умолчанию

.

arguments и argument-hint. Аргументы скилла и подсказки к ним при вызове. Например, скилл

объявляет два аргумента —

(подсказка «номер issue») и

(подсказка «приоритет»). При наборе

в интерфейсе появятся плейсхолдеры

; подставишь

и

— внутрь скилла они встанут на места

и

, и модель получит уже собранный текст.

paths. Условие автозагрузки. Скилл с

подтягивается сам, только когда в работе есть файл, подходящий под шаблон (вручную через слэш-команду его всё равно можно вызвать всегда). Формат — glob-шаблоны, где

значит «что угодно»:

*.md

— все файлы с расширением

;

— все

внутри

и любых вложенных папок.

shell. Выбор интерпретатора для инъекций вида

(о них — следующий раздел). Значения —

или

. Mac и Linux —

, Windows —

.

Поле

тянет за собой отдельную важную тему. В тело скилла через восклицательный знак можно вписать команду, и Claude Code выполнит её, подставив вместо строки её вывод ещё до того, как агент увидит содержимое скилла. Это и есть динамическая инъекция контекста — штука полезная.

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

А агент увидит уже результат выполнения

на месте команды:

Удобно. Но именно здесь — главная дыра безопасности скиллов. Это shell, и подставить туда можно что угодно, дотянувшись до всего, до чего дотягиваешься ты сам: украсть ключи и токены, перезаписать или удалить файлы, поставить бэкдор. А злоумышленники выкладывают такие скиллы в открытый доступ. Так что правило простое: скачал скилл из интернета — прежде чем запускать, прочитай, что у него в теле, особенно инъекции.

compatibility (до 500 символов). Перечисляет зависимости, которые должны стоять на машине, — например, что нужен Python. Поле чисто информационное: Claude Code не блокирует запуск, если условия не выполнены, ответственность остаётся на нас с моделью.

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

,

,

(

,

,

…),

,

(какие MCP-серверы нужны),

/

(ссылки),

(контакты).

license. Тип лицензии, как у кода. Открытый и бесплатный скилл —

или

; закрытый — подбираешь под свои условия.

Всё выше было про шапку. Теперь — тело скилла и то, как оно попадает в контекст. Это ключ к пониманию, почему скилл вообще экономит контекст: работает механизм прогрессивного раскрытия — в три уровня.

При запуске сессии Claude Code (программа, не модель) рекурсивно обходит все известные папки

, находит все

, отрезает у них шапки и раскладывает по подсистемам. Склейка

+

+

уходит в служебный каталог

, который подкладывается в запрос к модели — чтобы она со старта знала, какие навыки у неё есть и когда их звать.

Тел скиллов на этом этапе в контекст не грузится — только короткие описания. Поэтому на один скилл уходит совсем мало токенов. Но и этот каталог ограничен: по умолчанию он не может занимать больше 1% контекстного окна модели.

И вот тут — коварная деталь, на которой я обжигался лично. Когда описаний становится слишком много и они не влезают в 1%, лишние молча выкидываются, и скилл перестаёт вызываться. Никакой ошибки, никакого предупреждения — просто агент «не видит» навык и делает вид, что всё нормально.

Ловится это командой

. В её выводе появляется что-то вроде «список навыков будет сокращён; N описаний превышают лимит; M описаний удалено (для часто используемых сохранятся)». Без неё понять, что скилл отвалился из-за лимита, почти невозможно.

Как чинить:

И ещё: лимит считается от окна текущей модели. Сидел на Opus с миллионом токенов — всё влезало; переключился на Sonnet с 200 тысячами — часть каталога молча выпала. И, как мы выяснили, ты об этом даже не узнаешь, пока не запустишь

.

Скилл активируется — сам (модель решила, что он релевантен) или вручную слэш-командой. В этот момент

препроцессится:

Больше на этом уровне не грузится ничего — только тело

. Отсюда рекомендация: держать инструкцию в пределах 500 строк или 5000 токенов. Если какой-то кусок разрастается за ~100 строк — выносим его в папку

, отдельным файлом с внятным именем (одна документация — один файл), а в

даём относительный путь:

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

Файлы из

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

Здесь же в дело идут

. Но с ними Клод работает иначе, чем с документацией: файлы скриптов он никогда не читает — он их запускает и берёт результат. Предпочтительные языки — три: Python и JS (если не хватит библиотеки, модель доустановит её сама) и Bash (там доп. библиотек и нет, поэтому проблем не возникает). Чтобы вызвать скрипт независимо от рабочей директории, используем

— Claude Code подставит абсолютный путь:

Деталь для тех, кто на Windows: в путях всё равно пишем прямые слэши (

), а не обратные (

).

Третья папка этого уровня —

: статические шаблоны, не текст и не скрипты. Договоры, коммерческие предложения, таблицы, схемы, картинки, шрифты. Обращаемся к ним из инструкции так же, как к

:

.

Компакт — это сжатие предыдущего диалога, когда у модели кончается контекстное окно. Со скиллами он обходится так:

Практический вывод из этого один и тот же: чем тоньше тело скилла и чем больше тяжёлого вынесено в

и

, тем меньше проблем и на старте, и после компакта.

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