Claude Code Skills: как сохранить повторяемый рабочий приём

Claude Code Skills помогают сохранить рабочий приём в файле SKILL.md. Это удобно, когда задача повторяется: проверить безопасность перед выкладкой, подготовить карточку объявления, принять сайт у клиента.

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

Сведения о расположении и вызове навыков ниже сверены с официальной документацией Claude Code 25.10.2026. Интерфейс и встроенные возможности меняются; перед внедрением проверьте документацию для своей версии. Официально Россия не в списке поддерживаемых стран; как это решают на практике, разбираю на встрече по обучению.

Перед тем как писать навык:

• Назовите повторяющуюся ситуацию.
• Запишите входные файлы и ожидаемый результат.
• Отделите постоянный порядок от данных проекта.
• Выберите одну задачу для проверки.

Когда задача достойна отдельного навыка

Хороший кандидат повторяется в нескольких проектах, имеет понятный вход и требует последовательной проверки. Например, перед правкой сайта сначала читать контекст, затем смотреть затрагиваемые файлы, затем менять код и проверять сборку. Если задача состоит из одной короткой команды, отдельный навык может добавить лишний слой. Если каждая ситуация уникальна, лучше хранить общие принципы и решать детали по месту.

Начните с одной фразы: «Когда происходит X, делай Y и проверь Z». Это определяет момент применения. Затем перечислите источники фактов, ограничения и готовый результат. Навык должен помогать принять решение по ситуации. Длинный список без развилки «если источник отсутствует» часто приводит к тому, что исполнитель додумывает данные.

Куда положить SKILL.md

Для навыка одного репозитория используйте .claude/skills/<имя>/SKILL.md. Личный вариант находится в ~/.claude/skills/<имя>/SKILL.md и доступен вашим локальным проектам. Проектный навык можно хранить вместе с кодом и менять через обычный просмотр diff. По официальной документации Claude Code ищет проектные навыки в папке запуска и родительских каталогах до корня репозитория. Если запускаете сессию в необычной папке, проверьте область поиска.

Создайте небольшую заготовку. Команды ниже работают в копии вашего проекта; имя навыка и содержание замените под свою задачу. Файл здесь содержит только общие действия и не хранит пароли. Перед добавлением в Git просмотрите его целиком.

mkdir -p .claude/skills/check-delivery
cat > .claude/skills/check-delivery/SKILL.md <<'SKILL'
---
name: check-delivery
description: Проверяй сборку и доставку сайта, когда изменения не видны пользователю.
---

# Проверка доставки

1. Определи ожидаемое изменение и файл-источник.
2. Проверь локальную сборку и её ошибки.
3. Сверь опубликованную версию с серверной.
4. Проверь HTML и кеш на телефоне и компьютере.
5. Назови подтверждённое место, где цепочка оборвалась.
SKILL

Это пример структуры. Он не выполняет выкладку. У реального навыка надо указать команды конкретного проекта и критерии проверки. Если они различаются между сайтами, храните в навыке порядок поиска проектной инструкции. Копии deploy.sh быстро расходятся.

Как избежать копий одной правды

В навыке не должно быть постоянной копии прайса, даты акции, номера счётчика или адреса сервера. Эти сведения изменятся, а навык останется прежним. Вместо них укажите файл или системный источник, который нужно читать перед действием. Если навык пишет тексты для клиентов, правила тона можно хранить в нём; актуальный оффер всё равно читается из материала проекта.

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

Проверяйте навык по делу:

• Дайте ему конкретный проект и задачу.
• Посмотрите, какие файлы он прочитал.
• Сверьте выполненные проверки.
• Исправьте инструкцию там, где агент пропустил шаг.

В своих проектах я веду общий список технических ошибок и способов их проверки. Например, если клиент не видит изменения на сайте, порядок начинается со сборки и проверки ответа сервера. Этот метод можно оформить навыком и применять к разным сайтам. Конкретный адрес сервера читается из контекста текущего проекта. Deyvo показывает собственный программный продукт, но его экраны не служат доказательством работы Skills. Для организации проектных правил есть статья о базе знаний для ИИ.

Как проверить навык на настоящей задаче

После создания попросите Claude Code применить навык к небольшой безопасной задаче и наблюдайте, какие файлы он открыл, какие шаги выполнил и какой результат показал. Затем дайте похожую задачу, где один источник отсутствует. Хорошая инструкция заставляет назвать недостающий факт и продолжить независимую часть работы без выдуманных значений. Отдельно проверьте задачу вне области навыка: он не должен навязывать лишние действия.

Для проверки файла до запуска полезны обычные команды Git. Они показывают, что именно попало в инструкцию, и помогают заметить случайно вставленный доступ. Не сохраняйте в навыке .env или токен только потому, что пример работал локально.

git diff -- .claude/skills/check-delivery/SKILL.md
rg -n 'пароль|TOKEN|API_KEY|secret' .claude/skills/check-delivery/SKILL.md

Когда нужен следующий уровень

Когда инструкция стабильно работает, можно добавить поддерживающие файлы: образец отчёта, список команд или примеры допустимых ответов. Держите входной SKILL.md коротким, чтобы в начале задачи были видны условия применения и порядок действий. Дополнительный материал открывайте по необходимости. Если навык привязан к сервису, который часто обновляется, укажите официальный источник проверки и дату последней сверки.

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

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

Чем Skill отличается от CLAUDE.md?

CLAUDE.md даёт постоянный контекст проекта. Skill загружается для подходящей задачи и описывает отдельный рабочий приём.

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

Да. Папка .claude/skills/<имя>/ внутри проекта предназначена именно для этого. Личный навык лежит в домашней папке пользователя.

Что писать в описании навыка?

Конкретную ситуацию применения и ожидаемую пользу. Слишком широкое описание приводит к вызову на неподходящих задачах.

Можно ли хранить API‑ключ в SKILL.md?

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

Как понять, что навык помогает?

Повторите похожие задачи с обычным и ошибочным входом. Проверьте, что порядок соблюдён, источник фактов прочитан и результат проверен.