Claude Code skills: что это, как устроены и зачем нужны

Есть один паттерн, который появляется у каждого, кто работает с Claude Code больше нескольких дней: один и тот же промпт, который кочует из заметки в буфер обмена и обратно. «Сделай ревью по нашему чек-листу». «Напиши commit в стиле Conventional Commits». «Сгенерируй CRUD-модуль по нашим конвенциям». Если вы узнали себя — это и есть сигнал, что пора переходить к Claude Code skills.

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

Чем skill отличается от промпта и от CLAUDE.md

Три инструмента управления поведением агента, которые легко перепутать:

Промпт в заметках — вы доставляете вручную при каждом запросе. Работает, но требует усилий и теряется при смене устройства.
CLAUDE.md — всегда в контексте, читается на каждом запросе. Это «конституция проекта»: соглашения, стиль, правила, которые нужны агенту постоянно.
Skill — подгружается по требованию: только когда запрос семантически совпадает с описанием навыка. Лежит тихо, контекст не занимает, пока не нужен.

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

Подробнее о CLAUDE.md и настройке контекста проекта — в статье CLAUDE.md: настройка и конвенции.

Анатомия SKILL.md: три слоя

Минимальный skill — это папка с одним файлом SKILL.md. Никаких специальных расширений и зависимостей.

commit-msg/
└── SKILL.md

При необходимости папка расширяется ресурсами:

skill-name/
├── SKILL.md              (обязательный)
├── references/           (документация, подгружается в контекст по требованию)
├── scripts/              (исполняемый код — Python, Bash)
└── assets/               (шаблоны, файлы результата)

Сам файл SKILL.md состоит из двух частей.

Frontmatter

---
name: commit-msg
description: This skill should be used when the user asks to "напиши commit message",
  "сформулируй коммит", "сделай commit по диффу", or mentions Conventional Commits.
---

Два обязательных поля:

name — идентификатор навыка.
description — описание-триггер. Запомните эту формулировку: description — это не документация, а триггер. По нему агент решает, доставать skill или нет.

Тело

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

Как работает триггер

Это смысловое ядро всей механики.

При старте сессии Claude Code сканирует папки skills и загружает в контекст только метаданные каждого навыка — name и description. Это дёшево: ~100 слов на skill, можно держать десяток навыков и почти не тратить контекст.

Когда вы пишете запрос, агент семантически сопоставляет его с description всех известных skills. Если запрос совпадает — подгружается тело SKILL.md, агент работает по нему. Нет совпадения — skill спит.

Аналогия, которая хорошо закрепляется: агент всегда видит вывеску магазина (description), но заходит внутрь (тело) только если ему туда нужно.

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

Размытый description = несрабатывающий skill. Если написать «этот навык помогает с разработкой» — он будет срабатывать слишком часто или не срабатывать вообще. Description должен описывать конкретный класс запросов.
Срабатывание по смыслу, не по ключевому слову. Агент не ищет точное совпадение фразы, он оценивает семантическое соответствие. Поэтому в description полезно перечислять реальные фразы, которыми вы формулируете задачу.

Это тот же принцип progressive disclosure, который работает в контексте в целом — подробнее о нём в статье Progressive disclosure и контекст.

Где хранятся skills

Три места с разной областью видимости:

Расположение	Видимость
`~/.claude/skills/`	Личные — доступны во всех проектах
`.claude/skills/`	Проектные — едут с репозиторием, общие для команды
`skills/` внутри плагина	Плагинные — тема отдельного разговора

Синтаксис SKILL.md одинаков во всех трёх случаях. Меняется только место и область видимости.

Пример: skill commit-msg для CoffeeCRM

Разберём на конкретном примере из нашего сквозного проекта — fullstack-приложения CoffeeCRM на Next.js и NestJS.

Шаг 1. Создать папку для личного навыка:

mkdir -p ~/.claude/skills/commit-msg

Шаг 2. Создать файл ~/.claude/skills/commit-msg/SKILL.md:

---
name: commit-msg
description: This skill should be used when the user asks to "напиши commit message",
  "сформулируй коммит", "сделай commit по диффу", or mentions Conventional Commits.
  Генерирует сообщение коммита по staged-диффу в формате Conventional Commits.
---

# Генератор commit message

Когда нужно сформулировать сообщение коммита:

1. Получить staged-изменения командой git diff --staged.
2. Определить тип: feat, fix, refactor, docs, test, chore.
3. Сформировать заголовок: <type>(<scope>): <краткое описание>.
4. Заголовок — не длиннее 72 символов, без точки в конце.
5. При нетривиальных изменениях добавить тело: что и зачем.
6. Вывести сообщение в блоке кода, не делать commit без подтверждения.

Шаг 3. Начать новую сессию Claude Code. Метаданные подхватываются при старте — после создания skill нужен новый разговор.

Шаг 4. Проверить срабатывание:

сформулируй commit по staged-диффу

Агент запустит git diff --staged и выдаст готовое сообщение по вашим правилам — без того, чтобы вы вставляли промпт вручную.

Шаг 5. Проверить изоляцию. Задайте нерелевантный вопрос:

объясни, как работает useEffect в React

Skill не должен сработать. Хороший навык молчит, когда его не звали — это такой же критерий качества, как и правильное срабатывание.

Как написать description, который работает

Описание-триггер — это самое важное поле в skill. Несколько практических правил:

Перечисляйте конкретные фразы в кавычках: «напиши commit», «сформулируй коммит», «сделай commit по диффу». Агент увидит реальный язык ваших запросов.
Используйте конструкцию «This skill should be used when…» — это устойчивый шаблон, который хорошо распознаётся семантически.
Описывайте результат, а не процесс: «генерирует сообщение коммита по staged-диффу» точнее, чем «помогает с git».
Избегайте избыточной широты: навык для генерации commit message не должен срабатывать на вопросы о git в целом.

Чем точнее description соответствует реальным формулировкам ваших запросов, тем предсказуемее поведение агента.

Итог

Skills — это способ превратить повторяемые промпты в переносимые навыки, которые агент достаёт сам. Анатомия простая: папка, SKILL.md, frontmatter с name и description, тело с инструкциями. Главное — в description: это триггер семантического совпадения, по которому агент и находит нужный навык.

Начать проще, чем кажется: найдите промпт, который чаще всего копируете из заметок — и превратите его в первый личный skill. Это займёт 10 минут и сразу покажет разницу.

Если хотите разобрать skills, MCP и всё остальное системно — от пустого репозитория до деплоя на реальном проекте — посмотрите полный курс по Claude Code.