Создаём первый навык

Теория из прошлого урока сводится к одному файлу. В этом уроке мы его напишем: навык, который собирает релиз-ноты по шаблону команды. По дороге разберём, как формулировать описание, как передавать аргументы и как убедиться, что навык срабатывает, когда нужно.

Шаг 1. Договоримся, что навык должен делать

Прежде чем писать файл, сформулируйте задачу так, как поставили бы её коллеге. Для релиз-нот в нашей команде это выглядит так:

• Вход: номер версии.
• Источник: коммиты с последнего тега и номера задач в них.
• Выход: markdown по шаблону — заголовок с версией и датой, разделы «Новое», «Исправлено», «Изменено», в каждом пункте ссылка на задачу.
• Ограничения: служебные коммиты не включать; не выдумывать изменения, которых нет в коммитах.

Если вы не можете описать задачу в пять строк, навык получится расплывчатым. Лучше сузить.

Шаг 2. Создаём папку и файл

Навык для команды кладём в проект:

mkdir -p .claude/skills/release-notes

Имя папки — это имя команды: навык будет вызываться как /release-notes. Строчные буквы и дефисы. Внутри — файл SKILL.md, именно с таким именем и в таком регистре.

Можно попросить Claude Code создать навык: «Создай в .claude/skills/ навык release-notes, который…» — он знает формат. Но для первого раза полезно написать руками, чтобы увидеть, из чего файл состоит.

Шаг 3. Пишем SKILL.md

---
name: release-notes
description: Собирает релиз-ноты по шаблону команды из коммитов и задач. Используй, когда просят подготовить релиз-ноты, changelog, описание релиза или список изменений для версии.
argument-hint: [версия]
---

Подготовь релиз-ноты для версии $ARGUMENTS.

## Источник данных
1. Найди последний тег: `git describe --tags --abbrev=0`.
2. Возьми коммиты от него до HEAD: `git log <тег>..HEAD --oneline`.
3. Из каждого сообщения вытащи номер задачи вида PROJ-123, если есть.

## Правила
- Пропускай служебные коммиты: merge, bump version, lint, formatting.
- Одно изменение — одна строка в прошедшем времени, без технических
  деталей реализации.
- Не добавляй изменений, которых нет в коммитах. Если коммитов
  с прошлого тега нет — так и напиши, релиз-ноты не выдумывай.
- Если номер версии не передан, спроси его, а не угадывай.

## Шаблон
# Версия $ARGUMENTS — {дата в формате ДД.ММ.ГГГГ}

## Новое
- {описание} ([PROJ-123](https://tracker.example/browse/PROJ-123))

## Исправлено
- …

## Изменено
- …

Пустые разделы удаляй. Разделов, которых нет в шаблоне, не добавляй.

Разберём, что здесь и почему.

Первая строка файла — ---. Это обязательно. Если перед шапкой окажется пустая строка или комментарий, Claude Code прочитает весь файл как тело без метаданных: команда /release-notes будет работать, а автоматически навык не сработает никогда, потому что описания у него нет.

Description — условие срабатывания. Первая половина говорит, что навык делает, вторая — при каких словах его звать. Мы перечислили формулировки, которыми в команде реально просят: «релиз-ноты», «changelog», «описание релиза», «список изменений». Чем ближе описание к живой речи, тем надёжнее срабатывание. Слишком общее описание — «работа с релизами» — будет цеплять и просьбы «выкати релиз», для которых навык не предназначен.

$ARGUMENTS. Всё, что вы напишете после /release-notes, подставится вместо этого слова. Есть и позиционные аргументы: $0, $1, а в шапке можно объявить именованные через поле arguments. Для одного аргумента хватает $ARGUMENTS. Если аргументы переданы, а плейсхолдера в теле нет, Claude Code допишет их в конец текста — вы их не потеряете.

argument-hint. Подсказка, которая покажется в автодополнении при наборе /release-notes. Необязательно, но помогает коллегам.

Правила против выдумывания. Строки «не добавляй изменений, которых нет в коммитах» и «если версия не передана — спроси» кажутся лишними, но именно они отличают навык, которому доверяют, от навыка, за которым надо перепроверять. Модель охотно заполняет пробелы правдоподобным текстом; инструкция должна это прямо запрещать.

Шаг 4. Проверяем, что навык виден

Спросите Claude Code: «Какие навыки тебе доступны?» В ответе должен быть release-notes с вашим описанием. Если описание пустое — скорее всего, сломана шапка: проверьте, что --- стоит в первой строке и что в YAML нет незакрытых кавычек.

Начните набирать /rel — в автодополнении появится навык с подсказкой [версия].

Шаг 5. Проверяем оба способа вызова

Сначала ручной: /release-notes 2.4. Claude должен выполнить git describe, git log, собрать список и выдать markdown по шаблону. Посмотрите на результат критично: есть ли лишние разделы, попали ли служебные коммиты, все ли ссылки на задачи корректны.

Потом автоматический. В новой сессии напишите обычной фразой: «Подготовь описание релиза для 2.4». Если Claude загрузил навык — вы увидите тот же шаблон. Если нет — попробуйте перефразировать ближе к описанию («подготовь релиз-ноты 2.4»). Сработало во втором случае, но не в первом? Добавьте формулировку из первого в описание. Это нормальный цикл: описание дорабатывается по реальным просьбам.

Шаг 6. Дорабатываем по результату

Первая версия навыка почти никогда не окончательная. Типичные правки после первых прогонов:

• Claude включил коммит «update deps» — добавьте его в список служебных.
• Claude написал «исправлена критическая ошибка» там, где в коммите было «fix typo» — уточните правило «без преувеличений».
• Ссылки на задачи ведут не туда — вынесите адрес трекера в отдельную строку и проверьте.

Файл подхватывается при следующем вызове, перезапускать Claude Code не нужно. Для проектного навыка изменения проходят через обычный merge request — как код.

Второй пример для тренировки

Тот же подход годится для навыка проверки доступности вёрстки: описание «проверяет доступность разметки по WCAG; используй, когда просят проверить a11y, доступность, контраст, клавиатурную навигацию или подписи у полей», в теле — чек-лист и формат отчёта. У него нет аргумента-версии, зато есть длинный справочник критериев, который лучше вынести в отдельный файл. Как это сделать — в следующем уроке.