SKILL.md без магии: собираем свой скилл Claude Code по инженерным паттернам

Коротко (TL;DR)

Скилл (skill) в Claude Code — это папка с файлом SKILL.md, в котором лежит процедура: как выполнять конкретный тип задачи. Claude подхватывает её сам, когда задача подходит под описание. Это не плагин и не магия, а инженерная дисциплина: у скилла есть предсказуемая анатомия, лимиты и повторяемые паттерны организации.

Что вы получите из этого гайда:

• Анатомию SKILL.md — из чего он состоит и почему тело держат под 500 строк.
• 5 именованных паттернов организации скилла, которые реально работают: высокоуровневый гид с вынесенными деталями, доменная нарезка, условные ветки, workflow с чек-листом и скрипты вместо генерации кода.
• Два способа собрать свой скилл — через официальный плагин Skill Creator с измеримым eval-циклом и вручную, пошагово.
• Дерево решений «скилл против субагента против slash-команды против CLAUDE.md» — чтобы не тащить в скилл то, чему там не место.
• Честный разбор self-improving skills: что из этого заявленное видение Anthropic, а что — уже работающие самоделки сообщества.

Уровень материала — продвинутый: предполагается, что вы уже ставили готовые скиллы и теперь хотите писать свои. Если ещё нет — сначала стоит разобраться с установкой, а сюда вернуться за устройством и паттернами. Все версии команд и лимиты приведены по состоянию на июль 2026 года; экосистема Claude Code меняется быстро, и часть цифр (номера версий, названия флагов) устареет первой — сверяйтесь с официальными доками на дату чтения.

Зачем вообще писать свои скиллы

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

SpaceX · xStockSpaceX — частная компания. Торгуй её токеном на Bybit за крипту.Торговать SpaceX →

Здесь важно различать два типа пользы, потому что их часто путают.

Хуки Claude Code: как автоматизировать действия агента и не подорваться на своих же настройках

MCP в Claude Code: как подключить серверы, не сжечь контекст и когда он не нужен

Плагины в Claude Code: как установить, создать свой маркетплейс и не поймать вредоносный

Agent Skills в Claude Code: как работают, где взять и как не поставить вредоносный скилл

Память Claude Code: Auto Memory, /memory и почему агент забывает

• Capability uplift (прирост способности). Скилл даёт модели то, чего у неё не было: доменную процедуру, редкий формат, специфический API. Это главная причина писать скиллы — и именно она поддаётся измерению.
• Encoded preference (зафиксированное предпочтение). Скилл просто повторяет то, что модель и так умеет, но вашим способом («пиши коммиты вот так»). Польза есть, но она про удобство, а не про новые возможности.

Что это даёт в цифрах. Независимый бенчмарк SkillsBench (arXiv 2602.12670, февраль 2026) прогнал 87 задач в 8 доменах на 18 конфигурациях «модель + харнесс». Курируемые, хорошо структурированные скиллы подняли средний pass rate с 33,9% до 50,5% — на +16,6 процентного пункта. Но разброс большой: по разным конфигурациям прирост колебался от +4,1 до +25,7 п.п., а на 13 задачах из 87 дельта оказалась отрицательной — скилл мешал. Вывод простой: скилл окупается там, где он несёт настоящую доменную процедуру, и вредит, когда навязывает лишнюю ветку рассуждений.

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

Анатомия SKILL.md: из чего реально состоит скилл

Скилл — это директория, а не один файл. Минимум внутри — SKILL.md с YAML-шапкой (frontmatter) и телом в Markdown. Рядом могут лежать вынесенные файлы-справочники и исполняемые скрипты. Claude Code читает скиллы из четырёх мест с чётким приоритетом: enterprise (управляемые настройки) перекрывает personal (~/.claude/skills/), personal перекрывает project (.claude/skills/), а plugin-скиллы (<plugin>/skills/) идут отдельно. При совпадении имён побеждает более высокий уровень.

Ключевой механизм, который надо понять до написания первой строки, — прогрессивное раскрытие (progressive disclosure). Контекст загружается в три уровня, и это прямо влияет на то, как вы раскладываете материал:

1. Метаданные (name + description) — всегда в контексте, примерно сотня слов на скилл. По ним модель решает, брать скилл или нет.
2. Тело SKILL.md — грузится целиком, когда скилл сработал. Отсюда лимит: держите его короче 500 строк.
3. Связанные файлы и скрипты — подтягиваются только по мере надобности. Скрипт при этом выполняется без загрузки своего текста в контекст: в диалог попадает лишь его вывод.

Смысл этой трёхуровневости — экономия контекста. Метаданные всех скиллов висят в памяти постоянно, поэтому они должны быть крошечными. Всё тяжёлое (примеры, таблицы, редкие ветки) уезжает на уровни 2 и 3 и грузится, только когда действительно нужно. Хорошо написанный скилл — это не «большой файл со всем сразу», а тонкий вход с указателями вглубь.

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

SpaceX · xStockSpaceX — частная компания. Торгуй её токеном на Bybit за крипту.Торговать SpaceX →

Синтаксис frontmatter, который решает

Frontmatter — это YAML-шапка SKILL.md. Большинство полей опциональны, но несколько определяют, сработает скилл или нет и как именно он выполнится. Разберём те, что важны на практике.

Пара нюансов, на которых спотыкаются.

Лимит description — это про Platform API, а не про листинг Claude Code. В загружаемых пакетах Platform/API поле description ограничено 1024 символами. Внутри самого Claude Code механика другая: связка description + when_to_use обрезается на 1536 символах в листинге, а общий бюджет на перечень всех скиллов — 1% контекстного окна модели (настраивается). Это разные продукты и разные лимиты — не смешивайте их в одну цифру.

name в Claude Code можно не писать. Команда скилла определяется расположением файла: скилл в .claude/skills/deploy/SKILL.md даёт /deploy независимо от содержимого frontmatter. Более того, кастомные команды слиты со скиллами: файл .claude/commands/deploy.md и скилл .claude/skills/deploy/SKILL.md создают одну и ту же /deploy и работают одинаково. Старый путь commands/ жив как legacy, но канонический теперь — skills/.

description пишут в третьем лице и намеренно «настойчиво». Официальная инструкция самого Skill Creator прямо предупреждает: у модели есть тенденция недотриггеривать скиллы — не использовать их там, где они были бы полезны. Лекарство — явно перечислять в описании контексты срабатывания, даже если пользователь не называет скилл прямо. Формулировка вроде «Use when the user asks about X, mentions Y, or needs Z» надёжнее, чем сухое «Handles X».

5 паттернов организации скилла

Дальше — ядро гайда: пять воспроизводимых способов разложить скилл. Это не взаимоисключающие варианты — в одном скилле их обычно комбинируют. Все примеры опираются на официальные best practices и на исходники skill-creator.

Паттерн 1. Высокоуровневый гид + вынесенные references

Базовый паттерн прогрессивного раскрытия. В SKILL.md остаётся только карта процесса и решения «когда что», а тяжёлые детали (полные спецификации, длинные таблицы, справочники API) переезжают в отдельные файлы рядом. Тело держат под 500 строк; при приближении к лимиту официальный совет — не ужимать текст, а добавить ещё один уровень иерархии, то есть вынести кусок в новый файл-справочник.

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

Паттерн 2. Доменная организация

Когда скилл обслуживает несколько независимых поддоменов (например, три разных формата отчётов или три подсистемы), их разносят по отдельным reference-файлам, а в SKILL.md оставляют диспетчер: «работаешь с A — открой a.md, с B — b.md». Так контекст не раздувается суммой всех доменов сразу — грузится только релевантный.

Ключевое ограничение здесь — глубина ссылок. Держите вынесенные файлы на один уровень от SKILL.md. Если файл ссылается на файл, который ссылается на третий, Claude может прочитать промежуточные лишь частично (вплоть до head -100), и часть инструкций потеряется.

Паттерн 3. Условные детали (ветки по задаче)

Разновидность, где SKILL.md содержит дерево условий: «если задача такая — сделай так; если нет данных — вот запасной путь; для редкого случая X — смотри edge-cases.md». Частые ветки описаны прямо в теле, редкие вынесены. Это тот же принцип экономии контекста, но применённый к логике, а не к справочным данным: обычный путь читается всегда, экзотика подгружается по требованию.

Паттерн 4. Workflow с чек-листом и петлёй обратной связи

Для многошаговых процессов скилл задаёт явную последовательность с проверкой на выходе: собрать → выполнить → свериться с чек-листом → при провале вернуться и починить. Петля обратной связи (feedback loop) — то, что отличает надёжный workflow-скилл от простой инструкции: он не просто перечисляет шаги, а требует подтверждения результата перед завершением.

Этот паттерн особенно уместен там, где ошибку легко не заметить: генерация по строгому формату, миграции, публикация. Чек-лист в конце скилла работает как гейт — модель обязана пройтись по нему, а не отрапортовать «готово» на глаз.

Паттерн 5. Скрипты вместо генерации кода

Самый недооценённый паттерн. Если операция детерминированная (распарсить PDF, посчитать метрику, переформатировать данные) — не просите Claude писать код заново каждый раз. Положите готовый скрипт в scripts/ и в теле скилла скажите модели его запустить.

Выигрыш двойной. Во-первых, экономия контекста: скрипт исполняется через bash, его исходник не грузится в диалог — токены тратит только вывод. Во-вторых, детерминированность: код даёт один и тот же результат каждый раз, а генерация кода на лету — нет. Официальный пример Anthropic — извлечение данных из PDF: скилл запускает скрипт, не загружая ни его текст, ни сам PDF в контекст.

Как создать скилл: Skill Creator и вручную

Есть два пути. Официальный — через плагин, который автоматизирует не только черновик, но и проверку, что скилл вообще помогает. Ручной — когда нужно полное понимание или скилл совсем маленький.

Путь 1. Skill Creator (официальный плагин)

Skill Creator — это официальный мета-скилл Anthropic: скилл, который создаёт скиллы. Ставится из официального маркетплейса:

/plugin install skill-creator@claude-plugins-official

Он ведёт вас по циклу draft → test → eval → iterate и — это главное — автоматизирует сравнение с baseline. Схематично шаги такие:

1. Интервью. Плагин расспрашивает, что за задачу решает скилл и в каких контекстах должен срабатывать.
2. Черновик. Генерирует SKILL.md с frontmatter и телом, разложенный по паттернам выше.
3. Тест-кейсы. Составляет набор запросов, на которых скилл должен помогать.
4. Eval-loop. Прогоняет эти запросы с включённым скиллом и без него — и сравнивает результат. Это ответ на вопрос, который большинство авторов вообще не задают: «а мой скилл реально что-то улучшает?»
5. Оптимизация description. Если скилл недотриггеривается, плагин докручивает описание, чтобы модель брала его в нужных случаях.

Именно этот измеримый цикл, а не «просто напишите SKILL.md руками», — то, что превращает написание скилла из гадания в инженерию. Для сравнения: экосистема Claude — это уже семейство продуктов и поверхностей, от ассистента в Slack до Claude Code; скиллы переносят вашу процедуру между ними, но только если процедура действительно проверена.

Путь 2. Вручную, по шагам

Если хотите собрать скилл сами, минимальный маршрут такой:

1. Создайте папку — .claude/skills/<имя>/ в проекте (общий для команды) или ~/.claude/skills/<имя>/ (личный).
2. Напишите frontmatter — как минимум внятное description в третьем лице с перечнем триггеров. Имя команды придёт из имени папки.
3. Тело — тонкий гид. Изложите процедуру шагами. Всё тяжёлое сразу выносите в reference-файлы рядом (паттерн 1), держитесь под 500 строк.
4. Детерминированное — в скрипты (паттерн 5), редкое — в условные ветки (паттерн 3).
5. Протестируйте на свежем экземпляре. Контринтуитивный, но официальный совет: скилл, написанный в одной сессии Claude, проверяйте в другой, чистой сессии. Автор-инстанс уже «знает» контекст и триггернёт скилл даже по кривому описанию — свежий инстанс покажет, сработает ли он у реального пользователя.

Ручной путь дешевле по установке, но лишает вас eval-петли. Как показал SkillsBench, «на глаз» скилл может казаться полезным и при этом не давать прироста. Поэтому даже при ручной сборке имеет смысл прогнать хотя бы пару задач с скиллом и без.

Self-improving skills: видение и реальность

Тема «самоулучшающихся скиллов» звучит громко, поэтому разложим её на заявленное Anthropic и реально отгруженное сообществом.

Что говорит Anthropic. В статье-анонсе Agent Skills (октябрь 2025) сформулировано так: «мы надеемся дать агентам возможность самим создавать, редактировать и оценивать скиллы». Ключевое слово — надеемся. Это форвард-лукинг видение, цель на будущее, а не текущая функция. На июль 2026 года встроенной автономной фичи, в которой Claude Code сам без человека генерирует и внедряет себе скиллы, в официальной документации нет. Skill Creator — инструмент с человеком в цикле: он ассистирует, но не действует автономно.

Что реально существует. «Self-improving skills», о которых пишут в блогах, — это самодельные пайплайны сообщества поверх обычных механизмов. Показательный разбор (dev.to, автор Lily, 10 июля 2026) описывает рабочую систему из трёх частей:

• Генерация в сессии — скилл, который по нескольким триггерам предлагает оформить новую процедуру.
• Ночной сбор — headless-прогон (claude -p) по логам за день, который вытаскивает повторяющиеся паттерны.
• Еженедельный Curator — и вот это самое важное: он не удаляет скиллы. Неиспользуемые 30 дней помечаются как stale, 90 дней — уезжают в .archive/. За несколько месяцев так накопилось 64 авто-скилла в изолированном пространстве ~/.claude/skills/auto/.

Что этот паттерн независимо воспроизведён в нескольких GitHub-репозиториях, говорит о том, что подход рабочий. Но подавать его как «фичу Claude Code» нельзя — это инженерное решение конкретных людей, собранное из обычных кирпичей: skill-creator, headless-режим и планировщик.

И главная отрезвляющая деталь. Тот же SkillsBench показал: скиллы, которые модель сгенерировала себе сама, в среднем работают хуже, чем вообще без скиллов (на всех трёх проверенных связках модель+харнесс дельта была отрицательной). Модель надёжно пользуется готовым процедурным знанием, но надёжно писать его себе — пока не умеет. Отсюда правило для любого self-improving пайплайна: автогенерация без внешней оценки — это накопление шума. Нужен eval, а не ощущение прогресса.

Что выбрать: скилл, субагент, slash-команда или CLAUDE.md

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

Как читать эту таблицу на практике:

• Нужно постоянное правило («всегда пиши на русском», «не трогай прод») — это CLAUDE.md, а не скилл. Скилл грузится по ситуации, а CLAUDE.md — всегда.
• Нужна процедура по требованию — скилл. Если он должен срабатывать сам — обычный; если только по вашей команде — добавьте disable-model-invocation: true.
• Задача тяжёлая и автономная, её не надо тащить в основной диалог — субагент или скилл с context: fork. Разница: субагента Claude выбирает как отдельного исполнителя, а context: fork — это способ изолировать сам скилл.

Ошибка выбора дорого стоит: постоянное правило, засунутое в скилл, не сработает, когда нужно; а тяжёлый ресёрч без изоляции забьёт контекст и уронит качество остального диалога. Хороший пример границы автономности — личные ИИ-агенты вроде OpenClaw: там видно, насколько быстро неизолированная автономная работа съедает и бюджет, и внимание.

Антипаттерны, которые убивают скилл

Систематизированного списка ошибок по-русски почти нет, поэтому соберём главные. Все — из официальных best practices.

Зарезервированные слова тоже сюда: имена вроде anthropic-helper или claude-tools запрещены правилами поля name.

Работают ли скиллы вообще: данные, а не вера

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

Первый вывод мы уже привели: курируемые скиллы дают +16,6 п.п. pass rate, а сгенерированные моделью — ниже уровня «вообще без скиллов» (SkillsBench, февраль 2026). То есть ценность не в самом факте скилла, а в качестве процедуры внутри.

Второй вывод жёстче. Работа «How Well Do Agentic Skills Work in the Wild» (arXiv 2604.04323, апрель 2026) проверила, что будет, когда скилл нужно найти среди большой коллекции — 34 тысячи реальных скиллов, — а не подставить вручную идеальный под задачу. Результат: по мере приближения условий к реалистичным выигрыш деградирует почти до уровня без скиллов вообще. Спасает не количество, а стратегия: связка «поиск + доработка» (retrieval + refinement) частично восстанавливает результат — например, на Terminal-Bench 2.0 подняла pass rate Claude Opus 4.6 с 57,7% до 65,5%.

Практический смысл для вас как автора: «накопить побольше скиллов» — не стратегия. Десять точных, проверенных, хорошо описанных скиллов полезнее сотни сгенерированных «на всякий случай», потому что вторые модель либо не найдёт, либо возьмёт не те. Это ровно та развилка, где self-improving пайплайн без Curator и eval превращается из помощника в свалку.

Риски и безопасность: скилл — это исполняемый код

Скилл из чужого репозитория содержит инструкции, а часто и скрипты, которые Claude выполнит в вашем окружении. Это вектор атаки, и Anthropic говорит об этом прямо (предупреждение от 16 октября 2025): вредоносный скилл может внести уязвимости или направить Claude на кражу данных и нежелательные действия. Официальная рекомендация — ставить скиллы только из доверенных источников и просматривать код и скрипты перед включением непроверенного. Не хардкодьте в скилл секреты (API-ключи, пароли) — они утекут вместе со скиллом.

Что это не абстракция, видно по свежему фону вокруг доверия к агентам. В начале июля 2026 года прошла новость о том, что Alibaba ограничивает использование Claude Code на рабочих местах из-за предполагаемых рисков (3 июля 2026), а на Hacker News собрал крупное обсуждение тред о недекларируемом поведении агента. Тема доверия к тому, что агент делает под капотом, — горячая, и на скиллы из непроверенных источников она распространяется напрямую. Правило простое: относитесь к установке скилла как к запуску чужого скрипта с вашими правами, потому что это ровно оно и есть.

FAQ

Чем скилл отличается от CLAUDE.md? CLAUDE.md всегда в контексте — это постоянные правила проекта, которые нужны в каждом ответе. Скилл грузится по ситуации, когда задача подходит под его description. Постоянное правило в скилле не сработает в нужный момент, а разовую процедуру нет смысла держать в CLAUDE.md постоянно.

Обязательно ли поле name в SKILL.md? В Claude Code — нет: имя команды берётся из имени папки скилла. В загружаемых пакетах Platform/API name обязателен и подчиняется правилам: до 64 символов, только строчные буквы, цифры и дефисы, без слов anthropic и claude.

Почему мой скилл не срабатывает? Чаще всего дело в description — модель склонна недотриггеривать скиллы. Перепишите описание в третьем лице, явно перечислив контексты срабатывания, и сделайте его намеренно «настойчивым». Официальный Skill Creator умеет оптимизировать описание автоматически через eval-петлю.

Существует ли встроенная функция self-improving skills? На июль 2026 года — нет. Anthropic формулирует это как видение на будущее («надеемся дать агентам возможность самим создавать и оценивать скиллы»). То, что называют self-improving skills сегодня, — самодельные пайплайны сообщества поверх обычного Skill Creator, headless-режима и планировщика.

Сколько скиллов стоит держать? Немного, но точных. Независимые бенчмарки показывают, что при поиске из большой коллекции польза скиллов падает почти до нуля, а сгенерированные моделью скиллы в среднем не помогают. Лучше десять проверенных с понятными описаниями, чем сотня «на всякий случай».

Когда вместо скилла нужен субагент? Когда подзадача тяжёлая и автономная (объёмный ресёрч, ревью) и её не надо тащить в основной контекст. Субагент имеет своё контекстное окно и инструменты. Если хочется изолировать именно скилл, есть промежуточный вариант — context: fork, который исполняет скилл в форкнутом субагенте.