Skills в Claude Code: что это и как написать свой навык агента

Если вы вставляете в чат с Claude Code один и тот же чек-лист или порядок действий по три раза в неделю, пора превращать его в skill. Skill — это папка с файлом SKILL.md: короткое описание сообщает агенту, когда навык нужен, а подробная инструкция читается только в момент вызова. Ниже разберём, что такое claude code skills, чем они отличаются от CLAUDE.md, слэш-команд, субагентов и хуков, и напишем собственный навык на простом примере. Описание опирается на документацию Claude Code (раздел про skills) на октябрь 2026; версии и названия параметров могут измениться, поэтому сверяйтесь с ней.

Claude Code skills: что это такое

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

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

Важная деталь: пользовательские команды из .claude/commands/ теперь объединены с навыками. Файл .claude/commands/deploy.md и навык .claude/skills/deploy/SKILL.md создают одну и ту же команду /deploy и работают одинаково. Старые файлы продолжают работать, но для нового лучше использовать навыки: у них есть папка для вспомогательных файлов и управление тем, кто может вызывать навык.

Чем skill отличается от CLAUDE.md, команды, субагента и хука

Из таблицы следует практический критерий. Если правило нельзя нарушать никогда, делайте хук: Claude Code исполняет его каждый раз, а навык — это инструкция, которую модель может не выполнить. Если нужен постоянный контекст, берите CLAUDE.md. Если нужна процедура по требованию, берите skill. Для тяжёлого исследования, которое забьёт контекст, подойдёт субагент; навык при этом может сам запускаться в субагенте через context: fork. Подробнее о смежных механизмах — в статьях про CLAUDE.md↗ и хуки↗.

Как написать свой skill: пример

Сделаем навык, который готовит запись в CHANGELOG.md по последним коммитам. Навыки, доступные во всех проектах, лежат в ~/.claude/skills/<имя>/SKILL.md, а навыки одного репозитория — в .claude/skills/<имя>/SKILL.md.

mkdir -p ~/.claude/skills/changelog-entry

Файл ~/.claude/skills/changelog-entry/SKILL.md:

---
name: changelog-entry
description: Готовит запись для CHANGELOG.md по последним коммитам. Используй, когда просят релизные заметки, changelog или список изменений.
disable-model-invocation: true
argument-hint: [версия]
---

## Последние коммиты

!`git log --oneline -20`

## Что сделать

1. Версия релиза: $ARGUMENTS. Если она не указана, спроси.
2. Сгруппируй изменения в разделы Added, Changed, Fixed.
3. Одна строка на изменение, без хешей коммитов, на языке существующего CHANGELOG.md.
4. Покажи результат и предложи вставить его в начало CHANGELOG.md. Файл без моего согласия не меняй.

Что здесь важно:

• Блок между --- в самом начале файла — frontmatter. Claude Code читает его, только если открывающие --- стоят в первой строке. Если YAML между маркерами не разбирается, навык всё равно загрузится, но без заданных полей, поэтому после правки frontmatter проверяйте, что навык работает как задумано.
• description — главное поле. Именно по нему агент решает, подгружать ли навык. Пишите в нём то, что пользователь скажет на самом деле: «релизные заметки», «changelog».
• disable-model-invocation: true запрещает агенту вызывать навык самостоятельно. Документация советует так делать для действий с побочными эффектами, например /commit или /deploy. Навык запускается только вашей командой.
• Строка с восклицательным знаком и обратными кавычками — динамическая подстановка: Claude Code сам выполнит git log, и инструкция дойдёт до модели уже с готовым списком коммитов.
• $ARGUMENTS подставит то, что вы напишете после имени команды.

Запуск: откройте claude в репозитории и введите /changelog-entry 1.4.0.

Какие ещё поля пригодятся

• user-invocable: false скрывает навык из меню /, так что его применяет только агент; подходит для фоновых знаний вроде описания устаревшей системы.
• allowed-tools разрешает перечисленные инструменты без запроса подтверждения на тот ход, в котором навык вызван.
• context: fork запускает навык в отдельном субагенте, чтобы не засорять основной контекст.
• paths ограничивает автоматическую загрузку навыка файлами, подходящими под шаблон.

Список полей и условия по версиям Claude Code приведены в документации; не копируйте параметры из чужих примеров без проверки.

Вспомогательные файлы

Навык может включать несколько файлов: SKILL.md с обзором и навигацией и рядом reference.md, examples.md или папку scripts/. Укажите в SKILL.md, когда какой файл читать. Документация советует держать SKILL.md короче 500 строк, а подробности выносить в соседние файлы.

Как делиться: GitHub, плагины и другие инструменты

Навык проекта хранится в .claude/skills/ внутри репозитория: закоммитьте папку, и его получит вся команда. Поэтому по запросу «claude code skills github» обычно находят именно такие репозитории с папками навыков. Через плагины навыки распространяются шире: навык плагина вызывается как /имя-плагина:имя-навыка, а каталог плагинов (claude code plugins) описан в разделе плагинов документации. Чужие навыки читайте перед установкой так же внимательно, как чужой скрипт: они управляют поведением агента на вашем компьютере.

Формат навыков документация относит к открытому стандарту Agent Skills, который, по её словам, используют несколько ИИ-инструментов. Поддерживает ли такой формат Codex и в каком виде, смотрите в документации самого Codex: правила Claude Code мы на него не переносим. Для Codex похожую роль играет файл с инструкциями, о нём — в статье про AGENTS.md↗.

Сколько навыки стоят в токенах

Список навыков с описаниями загружается в контекст, причём документация ограничивает связку description и when_to_use 1 536 символами на навык, а при большом числе навыков часть описаний обрезается. Само тело навыка остаётся в разговоре после вызова и отправляется заново на каждом следующем шаге. При сжатии контекста Claude Code сохраняет начало каждого вызванного навыка (по документации, первые 5 000 токенов, а общий бюджет на все навыки — 25 000), поэтому самое важное пишите в начале файла.

Пример расчёта. Навык на 2 000 токенов вызван на 5-м шаге из 25, то есть остаётся в контексте ещё на 20 шагов. Claude Code ходит в Anthropic-формате, где виден кэш. На claude-sonnet-5-5 (запись 0.5, чтение 0.05, вход 0.4, $ за 1M токенов, на 18 октября 2026) при попадании в кэш: запись 2 000 × 0.5 / 1 000 000 = $0.001 и чтения 20 × 2 000 × 0.05 / 1 000 000 = $0.002, всего около $0.003. Без кэша те же 20 шагов стоили бы 20 × 2 000 × 0.4 / 1 000 000 = $0.016. В деньгах разница копеечная; настоящий выигрыш навыков в том, что тяжёлая инструкция не лежит в контексте, пока не нужна.

Если вы ещё не подключили Claude Code к шлюзу, настройка описана в инструкции↗: адрес https://api.zukko.pro без /v1 и ключ из кабинета↗.

Если навык не срабатывает

Документация предлагает проверить по порядку: есть ли в описании слова, которые пользователь произносит на самом деле; виден ли навык в ответе на вопрос «What skills are available?»; не помогает ли более близкая формулировка запроса; работает ли прямой вызов /имя-навыка. Если frontmatter содержит ошибку YAML, навык загрузится без метаданных: прямая команда сработает, а автоподбор по описанию нет. Для диагностики запустите Claude Code с --debug. Если навык срабатывает слишком часто, уточните описание или добавьте disable-model-invocation: true.

Частые вопросы

Чем skill лучше длинного CLAUDE.md?

Содержимое CLAUDE.md загружается всегда, а тело навыка только при вызове. Для процедур, нужных изредка, это экономит контекст.

Нужно ли перезапускать Claude Code после правки навыка?

В документации сказано, что Claude Code следит за папками навыков, и правки подхватываются в той же сессии без перезапуска. Если папки ~/.claude/skills/ не было на старте сессии, выполните /reload-skills.

Можно ли запретить агенту вызывать навык?

Да, через disable-model-invocation: true в frontmatter или правила разрешений Claude Code для навыков. Тогда навык запускается только вашей командой.

Будут ли навыки работать, если Claude Code подключён к Zukko?

Навыки хранятся и применяются на стороне клиента, а модель вызывается по тому адресу, который вы указали. Цена определяется токенами модели.