Claude Skills: как написать навык SKILL.md для Claude Code

Что такое Claude Skills

В октябре 2025 года Anthropic показала навыки — Agent Skills, а 18 декабря того же года опубликовала формат как открытый стандарт. Его поддерживают не только Claude Code и приложения Claude: OpenAI пишет, что навыки ChatGPT и Codex построены на том же стандарте, Gemini CLI определяет навык по нему же, а GitHub Copilot читает навыки проекта в том числе из папки .claude/skills.

Навык загружается в три приёма. Имя и описание каждого установленного навыка модель видит с самого начала сессии. Тело SKILL.md читается, когда модель решает, что навык относится к задаче. Дополнительные файлы — только если инструкция на них сошлётся; скрипт при этом исполняется, и в контекст попадает только его вывод.

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

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

• name — до 64 знаков: строчные латинские буквы, цифры и дефисы.
• description — до 1024 знаков: что навык делает и когда его применять.
• Тело — шаги, проверки и запреты; рекомендация стандарта и производителя — короче 500 строк и меньше 5000 токенов.
• Рядом — справочные файлы, шаблоны и папка scripts/ с кодом для однозначных операций.

Сначала проверьте, нужен ли навык вообще

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

Навык — и не место для фактов. Если модели не хватает прайс-листа или справки по внутреннему API, это данные, а не процедура: в размеченных траекториях навык работал как поставщик недостающих фактов лишь в 4,5 % случаев, а как «якорь процедуры» — в 65,7 %. Инструкция, нужная в каждом сообщении, — тоже не навык, а постоянное правило вроде CLAUDE.md.

Правило 1. Описание пишут для модели, а не для человека

До загрузки модель видит у навыка только имя и описание. В одном опыте Claude Opus 4.6 в Claude Code, которому велели загрузить все нужные навыки, решил 55,4 % задач, а с правом выбирать самому — 51,2 %: все нужные навыки загрузили лишь 49 % траекторий. Агенту трудно узнать нужный навык по двум строкам.

Поэтому в description — что делает навык и когда его применять, главный случай — первым, словами, которыми задачу сформулирует пользователь. В Claude Code описание вместе с полем when_to_use обрезается на 1536 знаках, а когда навыков много, описания укорачиваются ещё. Руководство Anthropic советует писать описание в третьем лице.

Правило 2. Порядок действий и запреты, а не справочник

Самое сильное основание здесь — опыт с файлами правил: из 679 публичных файлов CLAUDE.md и родственных собрали 25 532 правила и прогнали больше пяти тысяч сессий Claude Code. В поштучной проверке восемнадцати правил каждое полезное само по себе оказалось запретом, каждое вредное — предписанием вроде «следуй стилю кода».

Тело навыка — последовательность шагов с проверками по дороге и отдельный список того, чего делать нельзя. Абзацы «Что такое X» и пересказ документации, которую модель знает сама, — вырезать.

Правило 3. Короткое тело, важное — в начале

Тело SKILL.md, раз загрузившись, остаётся в разговоре, а при сжатии контекста в Claude Code возвращается урезанным: по первым 5000 токенов каждого навыка, всего не больше 25 000. То, что стоит дальше, может просто исчезнуть.

В SkillsBench компактные и стандартные навыки дали прирост +19,0 и +21,5 пункта, подробные — +14,5, «исчерпывающие» — +0,7. Группы разные, так что это направление, а не порог. Его подтверждает опыт с сокращением тех же навыков: описания сжали на 48 %, тела — на 39 %, и качество на 600 навыках выросло на 2,8 %.

Правило 4. Справочное — в файлы на один уровень ниже

Если у навыка есть справочник, нужный не в каждой задаче, вынесите его в отдельный файл и сошлитесь прямо из SKILL.md с условием, когда его открывать. Когда один и тот же текст подали плоским файлом и разложенным по файлам, агенты чаще открывали нужное и на 17 из 410 прогонов чаще решали задачу.

Цепочка SKILL.md → reference.md → details.md не помогла ни разу: встретив вложенную ссылку, Claude может прочитать только начало файла.

Правило 5. Пометьте, где пример, а где требование

Из 125 сбоев, вызванных навыками, навык не по теме дал всего два. 86 — ошибки при уместном навыке, и во многих из них агент принимал пример или шаблон за требование задачи. Пометьте в теле, что обязательно, что — пример и что — по желанию, и добавьте строку «когда навык не нужен» с коротким путём для простых задач.

Правило 6. Однозначное — в скрипт

Среди десяти задач SkillsBench с наибольшим выигрышем от навыков первым из повторяющихся приёмов оказался исполняемый скрипт с подобранными значениями по умолчанию вместо описания алгоритма словами. Разбор файла, преобразование формата, расчёт — кладите в scripts/ и прямо пишите в SKILL.md, запускать скрипт или читать.

Обратная сторона: скрипт — главный путь атаки через чужой навык. Среди 31 132 навыков из двух маркетплейсов хотя бы один шаблон уязвимости нашёлся у 26,1 %. Чужой навык, код которого некому прочитать, лучше не ставить.

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

Две ошибки встречаются чаще других и обе выглядят как забота о качестве.

• Не держите навык в контексте всегда: SKILL.md в промпте с первого сообщения у всех четырёх проверенных моделей понизил результат и поднял расход токенов на 72–394 %.
• Не отдавайте модели писать навык без проверки: навыки, которые модель написала себе сама, опустили результат ниже, чем без навыков вовсе.

Где прочитать подробнее

Пятнадцать шагов — от замера без навыка до проверки чужого навыка перед установкой — с числами, постановкой каждого опыта и признаком, что шаг выполнен, собраны в выпуске «Навыки Claude». Почти вся база — свежие препринты, и в выпуске это сказано рядом с каждым числом.

Ещё больше полезных руководств

PDF-гайд

Навыки Claude

49 стр.|2026Новинка

PDF-гайд

MCP: обещано и измерено

40 стр.|2026Новинка