Навыки кода Claude: файлы SKILL.md, которые модель действительно вызывает

Последнее обновление: June 28, 2026

Claude Code Skill — это папка с файлом SKILL.md, который агент добавляет в контекст только тогда, когда задача ему соответствует. Я создал свой первый навык, чтобы перестать вставлять один и тот же чек-лист миграции базы данных из 200 слов в каждую сессию. Этот один файл теперь экономит мне примерно час в неделю.

Вот краткая версия, а затем — практическая анатомия: что такое навык, как писать фронтматтер и тело в SKILL.md, как модель решает вызвать навык и когда навык избыточен по сравнению с обычным промптом. Если вы уже используете Claude Code, вы можете создать свой первый навык менее чем за пять минут.

Краткий ответ: что такое Claude Code Skill?

Навык (skill) — это многократно используемая возможность, вызываемая моделью и хранящаяся как SKILL.md (плюс необязательные вспомогательные скрипты). В отличие от системного промпта, который загружается всегда, навык загружается по требованию, когда модель определяет, что он релевантен вашему запросу. Вы пишете имя, описание когда его использовать и инструкции для тела. Описание — это самое важное поле, потому что именно оно позволяет модели решить, активировать ли этот навык. Навыки хранятся локально в .claude/skills/ или поставляются из реестра, поэтому команда может поделиться одним каноническим способом выполнения миграций, обзоров кода или релизов.

Если вы хотите получить более широкий контекст о самом CLI, ознакомьтесь с моим Claude Code ultimate guide for 2026. Чтобы узнать, чем навыки отличаются от постоянно активных суб-агентов, прочтите как я автоматизировал свой рабочий процесс с Claude Code sub-agents.

Что такое навык на самом деле и из чего он состоит?

Навык — это каталог. Минимум, который ему нужен, — это файл SKILL.md. Опционально он может содержать скрипты, шаблоны или справочные документы, которые сопровождают навык. Документация Anthropic по агентским навыкам описывает навык как упакованный набор инструкций и ресурсов, которые модель может загрузить при необходимости (docs.anthropic.com/en/docs/agents-and-tools/agent-skills).

Я рассматриваю навык как именованную, версионированную подпрограмму для модели. Три вещи отличают его от длинного промпта:

1. Он опционален (opt-in). Модель загружает его только в том случае, если задача соответствует описанию.
2. Он ограничен областью действия (scoped). Вы можете прикрепить файлы и скрипты, которые имеют смысл только для этой возможности.
3. Он можно поделиться (shareable). Папка переносима между проектами и членами команды.

Сам CLI является открытым исходным кодом, а соглашение о навыках документировано рядом с ним на GitHub (github.com/anthropics/claude-code), где я проверяю изменения поведения между релизами.

Как структурировать файл SKILL.md?

Файл состоит из двух частей: YAML-заголовка (frontmatter) и тела в формате Markdown. Заголовок сообщает модели, когда запускать код; тело сообщает ей, что делать. Вот анатомия, которую я использую.

---
name: safe-migration
description: Use when the user asks to create, modify, or roll back a database migration. Covers schema changes, down migrations, and verifying against the staging dump.
---

Тело — это чистый Markdown. Я сохраняю три раздела: цель в одну строку, пронумерованную процедуру и явный этап "остановки и подтверждения". Имя должно совпадать с именем папки. Описание должно быть написано для модели, а не для человека, чтобы оно выглядело как условие срабатывания (триггер).

Я протестировал это напрямую. С расплывчатым описанием типа "помогает с базами данных" навык срабатывал на не связанных вопросах SQL. После того как я переписал его на "Use when the user asks to create, modify, or roll back a database migration", точность вызова возросла примерно с 60 процентов до надежной. Именно описание выполняет маршрутизацию, поэтому тратьте свое время редактирования именно там.

Когда стоит превращать что-то в навык?

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

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

Конкретный случай, когда я написал навык: наш процесс выпуска требует обновления журнала изменений (changelog), увеличения трех файлов версий, добавления тегов и публикации сводки в Slack. Я написал это один раз как навык, и теперь я говорю "cut a release", а модель выполняет весь чек-лист по порядку. Конкретный случай, когда я этого не делал: одноразовый рефакторинг файла конфигурации. Он остался промптом.

Как работает паттерн вызова навыков моделью?

Паттерн, который придает навыкам магический вид, заключается в том, что вы не вызываете их. Вы описываете задачу, а модель читает описания доступных навыков и извлекает подходящий. Это задокументировано в официальной документации Claude Code (docs.anthropic.com/en/docs/claude-code).

Поток выглядит следующим образом:

1. Вы вводите запрос на естественном языке.
2. Модель видит name и description каждого установленного навыка.
3. Она оценивает релевантность относительно вашего запроса.
4. Тело выигрывающего навыка (и связанные файлы) попадают в контекст.
5. Модель выполняет инструкции.

Практическое следствие: вы должны написать description так, как будто пишете запись в поисковой системе для модели. Начинайте с глагола и области срабатывания (trigger scope). Сравните эти два описания:

• Слабый: "Навык для работы с вещами, связанными с git."
• Сильный: "Использовать, когда пользователь просит выполнить squash, rebase или разделение коммитов в текущей ветке. Создает интерактивный план перед выполнением любой перезаписи."

Сильный вариант называет глаголы срабатывания и ограничитель (guardrail). Это то, что делает вызов надежным. Если вы объединяете навыки с помощью инструментов, руководство по интеграции Claude Code MCP (Claude Code MCP integration guide) описывает, как внешние серверы инструментов вписываются рядом с пакетами навыков. Для базового протокола, который их соединяет, см. MCP и контекст модели.

Как вызвать и отладить навык?

Активация в основном автоматическая, но у меня есть три намеренных метода для контроля и отладки.

• Будьте явными. Указание "использовать навык safe-migration" заставляет его работать. Полезно, когда описание неоднозначно.
• Перечислить установленные навыки. Попросите модель перечислить доступные навыки и их описания. Таким образом я подтверждаю, что новый навык зарегистрирован.
• Проверить трассировку. Когда навык срабатывает неправильно, я смотрю, какое описание подошло, и уточняю формулировки триггера.

Если навык не срабатывает, причина почти всегда кроется в описании, а не в расположении файла. Я переписываю первое предложение, начиная его со слов "Использовать, когда..." и добавляя конкретные глаголы. Это решает проблему в девяти из десяти случаев.

Вот контрольный список отладки, который я использую, в порядке:

Skill против sub-agent против slash command

Эти три понятия пересекаются, и люди постоянно их путают. Я разделяю их с помощью простого деления.

• Skill: инструкции, вызываемые моделью, плюс необязательные файлы. Лучше всего подходит для условной экспертизы.
• Sub-agent: отдельный экземпляр Claude Code, выполняющий изолированную работу. Лучше всего подходит для параллельных, длительных задач. Мой sub-agent automation write-up углубляется в эту тему.
• Slash command: ярлык, который вы намеренно набираете. Лучше всего подходит для вещей, которые вам всегда нужны по требованию.

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

Как делиться навыками и использовать реестр?

Навык — это просто папка, поэтому в принципе поделиться им тривиально. Я помещаю папку под .claude/skills/ в репозиторий и коммичу ее. Коллеги получают ее при клонировании. Для обмена между командами сообщество поддерживает реестры, а официальные инструменты указывают на общие места.

Моя практическая настройка:

1. Хранить навыки, специфичные для проекта, в репозитории с контролем версий.
2. Хранить личные навыки в репозитории dotfiles, связанном (symlinked) с .claude/skills/.
3. Закреплять версии навыков при внешнем обмене, поскольку изменение описания может незаметно изменить поведение.

Честное предостережение об обмене: навык кодирует предположения о вашем стеке. Навык миграции, написанный для Drizzle, с уверенностью выдаст неверный результат в проекте Prisma, если описание не защищает область действия (scope). Всегда указывайте фреймворк и ограничения (guardrails) в описании и добавляйте шаг «остановиться и подтвердить» перед разрушительными действиями. Я усвоил это на горьком опыте, когда общий навык выполнил разрушающую перезапись на неправильной ветке, поэтому относитесь к каждому общему навыку как к недоверенному, пока его описание не докажет обратное.

Источники изображений

• Черный экран с наложенным кодом на рабочем месте разработчика — фото от Pixabay на Pexels
• Крупный план программного кода на мониторе во время разработки — фото от Christina Morillo на Pexels
• Ноутбук, показывающий редактор кода во время разработки программного обеспечения — фото от luis gomes на Pexels