Скилы в Claude Code: что это и как сделать свой

Скил в Claude Code это папка с текстовым файлом SKILL.md. В шапке файла лежит имя и описание, ниже инструкция: что делать, в каком порядке и как выглядит правильный результат. Агент видит описания скилов с самого старта сессии. Полный текст он читает только когда вы набрали /имя-скила или когда задача совпала с описанием. Так одна инструкция живёт в проекте и срабатывает каждый раз, когда нужна, и её не приходится повторять в каждом чате.

Ниже разбор скилов как инструмента. Где их хранить и из каких полей собрана шапка. Чем скил отличается от промпта и от файла правил CLAUDE.md, и когда он лишний. Как собрать и проверить свой за вечер, почему готовый скил вдруг перестаёт срабатывать и как перенести его в Codex. Всё сверено с документацией Claude Code и спецификацией Agent Skills на 19 сентября 2026 года. Если вы ещё не работали с самим инструментом, начните с разбора, что такое Claude Code: там объяснены сессия, права и файл правил.

Где лежат скилы и кто их видит

Claude Code ищет папки со SKILL.md в нескольких местах, и от места зависит, кто получит скил. Я держу два уровня. В домашней папке лежат скилы, которые нужны мне вне репозитория сайта: сверка продаж для клиента, онбординг участников его программы лояльности. Внутри репозитория лежат проектные: публикация статьи, вычитка текста, разбор транскрипции, коммит с деплоем. Они уезжают в git вместе с кодом, поэтому у коллеги или у второй сессии появляются без настройки. В этом репозитории их восемь, от 70 до 336 строк каждый.

Старые слэш-команды из папки .claude/commands/ продолжают работать и понимают ту же шапку. Для нового лучше сразу брать формат скила: это папка, рядом с инструкцией лежат справочники и скрипты, и есть поле paths, которого у команд нет.

Из чего состоит SKILL.md

Файл делится на две части. Шапка в формате YAML между двумя строками ---, она обязана начинаться с первой строки файла. И тело в Markdown, где лежит сама инструкция. Минимальный рабочий скил выглядит так.

Спецификация Agent Skills требует двух полей. name: до 64 знаков, только строчные латинские буквы, цифры и дефис, должно совпадать с именем папки. description: до 1024 знаков, что делает скил и когда его звать. Claude Code мягче: по его документации имя берётся из папки, если поля нет, а описание обрезается на 1536-м знаке. Писать всё равно стоит по спецификации: тот же файл читают Codex и валидатор.

Описание это самое важное поле в файле. Именно по нему агент решает, подключать скил или нет, когда вы не назвали его через слэш. Правила из руководства Anthropic по написанию скилов: третье лицо («проверяет письмо» вместо «я помогу проверить»), сначала что делает, потом когда использовать, и ключевые слова, которыми пользователь опишет задачу своими словами.

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

Остальные поля шапки понадобятся позже, когда скилов станет больше пяти. Их пять, по одному на задачу.

disable-model-invocation: true запрещает агенту запускать скил самому. Документация советует ставить его на деплой и коммит, то есть на всё, что оставляет след снаружи. В моих проектных скилах этого поля пока нет, деплой я запускаю руками по привычке, после этой сверки поле допишу.

user-invocable: false делает обратное: прячет скил из меню слэша, и он остаётся справкой, которую агент подключает сам.

allowed-tools заранее разрешает инструменты на один ход, до вашего следующего сообщения, чтобы не подтверждать каждый вызов git внутри скила.

context: fork запускает скил в отдельном субагенте без истории чата, это удобно для долгих проверок.

paths включает автозапуск только для файлов по маске, например *.md. Аргументы после имени попадают в тело как $ARGUMENTS: /proverka-pisma черновик.md.

Шапка скила для деплоя с двумя такими полями выглядит так.

Скил, промпт и CLAUDE.md: что куда

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

Когда скил не нужен

Перед тем как заводить папку, я задаю три вопроса. Задача повторится? Разовый разбор логов не стоит скила, его проще сделать в чате. Скил окупается со второго повторения, когда вы ловите себя на том, что диктуете те же шаги.

Это процедура или факт? «Мы пишем на TypeScript, тесты через vitest, в прод без бэкапа не ходим» это факты, их место в CLAUDE.md, они нужны всегда. «Как выпустить статью: проверить, собрать, опубликовать, отправить поисковикам» это процедура, её место в скиле.

Правило должно срабатывать всегда, без исключений? Тогда скил слабое место. Агент подключает его по совпадению описания, а совпадение вероятностное. Для жёстких запретов в Claude Code есть хуки (команды, которые инструмент выполняет сам на событиях, до ответа модели) и настройки прав. Документация прямо советует: если скил перестаёт влиять на поведение после первого ответа, перепишите описание точнее или закрепите правило хуком.

Как собрать свой скил за вечер

Порядок, который советует руководство Anthropic и который я бы взял за основу, начинается с провала, текст потом. Шаг 1: дайте агенту задачу без скила и запишите, где он ошибся или чего не знал. Это будущее содержание. Руководство Anthropic называет это «сначала проверки, потом документация»: три сценария, на которых агент без скила даёт слабый результат.

Шаг 2: напишите описание раньше тела. Что делает, когда звать, какими словами пользователь это попросит. Если описание не помещается в два предложения, скил пытается делать две работы, разделите.

Шаг 3: тело. Шаги по порядку, у каждого шага пример правильного результата на одну-три строки. Насколько жёстко писать, зависит от цены ошибки: для миграции базы одна точная команда и запрет менять флаги, для ревью кода четыре ориентира и свобода. Термины одни и те же по всему файлу: если назвали «черновик», не переходите на «текст» и «документ».

Шаг 4: проверка в свежей сессии. Сначала через слэш, потом фразой без имени скила, той, которой вы описали бы задачу коллеге. Подключение видно в ленте сессии как вызов инструмента Skill с именем скила. Если во втором случае его нет, виновато описание. Если подключился, но результат мимо, виновато тело: дописываете шаг и прогоняете снова. Руководство советует проверять на всех моделях, которыми пользуетесь: инструкций, которых хватает старшей модели, младшей может быть мало.

Шаг 5: через неделю посмотреть, какие файлы папки агент открывал и какие ни разу. Неоткрытый справочник либо не нужен, либо плохо назван в SKILL.md.

Есть и короткий путь к первому черновику: решить задачу в чате до хорошего результата и попросить агента описать пройденный процесс в формате скила. Этот приём с готовой фразой-ключом разобран в статье про реверсивный скил. Плагин skill-creator из официального каталога делает похожее и умеет прогонять проверки со скилом и без него. На выходе в любом случае читайте файл сами и убирайте объяснения того, что модель и так знает.

Почему скил не срабатывает

Пять причин, которые закрывают почти все случаи.

Шапка не с первой строки. Пустая строка или комментарий перед первым ---, и Claude Code считает весь файл телом без описания. Валидатор спецификации такой файл не принимает.

Имя нарушает правила. Заглавные буквы, пробел, подчёркивание, два дефиса подряд, имя не совпадает с папкой. Claude Code часть этого прощает, валидатор спецификации нет.

Описание расплывчатое или в первом лице. «Помогает с документами» не совпадёт ни с одним запросом. Агент выбирает из десятков описаний, ему нужны слова задачи.

Автозапуск выключен намеренно. disable-model-invocation: true означает, что скил подключается только через слэш; paths ограничивает его файлами по маске. Оба поля легко забыть через месяц.

Скил сработал один раз и «забылся». Тело остаётся в окне до конца сессии, но при сжатии контекста, по документации Claude Code, от каждого скила сохраняются первые 5000 токенов, а все повторно подключённые скилы делят 25 000. Длинный скил с главным правилом в конце теряет именно его. Главное ставьте в начало тела, длинное выносите в соседние файлы.

Перенос между Claude Code и Codex

Когда скил заработал у вас, следующий вопрос обычно про коллегу, который сидит в другом агенте. Формат SKILL.md открытый, его описывает спецификация Agent Skills, и Codex читает тот же файл. Различаются три вещи: папка, знак вызова и набор необязательных полей.

Codex ищет скилы в .agents/skills/ внутри репозитория, в ~/.agents/skills/ для пользователя и в /etc/codex/skills/ для машины. Вызов через $имя-скила или список по /skills, автоматический подбор по описанию работает так же. У Codex есть встроенные $skill-creator для сборки и $skill-installer для установки из репозитория. Чужой скил из репозитория перед установкой читайте сами: SKILL.md может запускать команды до того, как агент увидит текст, а готовая фраза для проверки в свежей сессии есть в статье про реверсивный скил.

Поля context, paths, hooks, disable-model-invocation описаны в документации Claude Code, в документации Codex их нет, рассчитывать на них при переносе не стоит. У Codex рядом со SKILL.md живёт свой файл настроек agents/openai.yaml, его смотрите в документации Codex. Переносимый скил стоит писать так, чтобы тело работало без особых полей: если нужен запрет на автозапуск, продублируйте его первой строкой инструкции словами. Копия внутри одного репозитория со временем разойдётся с оригиналом: правьте одну папку и после правок копируйте заново. Валидатор skills-ref из репозитория спецификации проверяет шапку по общим правилам, команда ниже.

Что сделать сегодня

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

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

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