Хватит копировать длинные промпты: собираем первый skill

Skill в Claude Code — это папка с файлом SKILL.md, где хранится повторяемая инструкция. Создадим безопасный пример review-diff: он читает текущий git diff, кратко описывает изменения и указывает риски. Для проверки понадобятся проект с незакоммиченным изменением и запущенный Claude Code. В конце skill должен сработать по обычной фразе и по команде /review-diff.

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

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

Разовое требование оставляйте в текущем prompt. Факты и правила, которые действуют для всего репозитория, храните в CLAUDE.md. В skill имеет смысл выносить повторяемую последовательность действий или проверок.

Личный skill доступен во всех ваших проектах. Официальный путь выглядит так:

«~/.claude/skills/review-diff/SKILL.md»

Skill только для одного репозитория хранится здесь:

«.claude/skills/review-diff/SKILL.md»

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

«mkdir -p ~/.claude/skills/review-diff»

Имя каталога становится именем команды, поэтому этот skill будет вызываться как /review-diff. Для каталога удобно использовать lowercase kebab-case.

Сохраните следующий текст в ~/.claude/skills/review-diff/SKILL.md:

«— name: review-diff description: >- Review the current git diff, summarize uncommitted changes, and flag risks. Use when the user asks what changed, requests a review of uncommitted work, or wants help preparing a commit. —

Review diff

Instructions

Use Bash to run git diff HEAD. Summarize the changes in two or three points. Then flag missing error handling, hardcoded values, compatibility risks, and tests that may need updating. If the diff is empty, say that there are no uncommitted changes.»

У SKILL.md есть YAML frontmatter между разделителями — и основная инструкция в Markdown. В актуальной документации Claude Code все поля frontmatter считаются необязательными, а description рекомендуется для автоматического выбора. Поле name оставлено в примере для читаемости; команда /review-diff всё равно получает имя от каталога.

Инструкция просит Claude выполнить через Bash команду git diff HEAD, которая только читает изменения. В зависимости от ваших настроек Claude Code может запросить разрешение перед запуском. Для первого skill это полезная проверка: не добавляйте широкие allowed-tools только ради того, чтобы убрать одно подтверждение.

Откройте git-проект, измените любой файл и запустите Claude Code. Затем напишите обычную фразу:

«Проверь мои незакоммиченные изменения: кратко объясни, что поменялось, и укажи риски.»

Фраза близка к description: в ней есть незакоммиченные изменения, проверка и риски. Успешный ответ должен ссылаться на конкретные строки или файлы из текущего diff. Общий список советов без связи с изменениями не считается успешной проверкой.

Теперь вызовите тот же skill вручную:

«/review-diff»

Оба способа должны привести к одному типу результата: краткое описание изменений и список рисков. Если slash-команда работает, а обычная фраза нет, файл уже найден — исправлять нужно прежде всего description.

Prompt описывает текущую задачу: какой файл посмотреть, что сегодня не менять, в каком виде вернуть ответ. После завершения диалога эти условия могут стать неактуальными.

CLAUDE.md хранит постоянный контекст репозитория: стек, соглашения, команды тестов, запрет на изменение сгенерированных файлов. Claude Code читает этот контекст в каждой сессии проекта.

Skill хранит процедуру: сначала получить diff, затем проверить несколько классов риска и подготовить итог в заданной форме. Он появляется в контексте, когда задача подходит под description или пользователь вызывает команду.

Полезный тест простой. Если меняется цель конкретного запроса, пишите prompt. Если это стабильный факт о проекте, используйте CLAUDE.md. Если повторяется порядок действий, делайте skill.

Проверьте путь и точное имя файла SKILL.md. На системах с чувствительностью к регистру skill.md — другой файл. Также убедитесь, что архив не создал лишний уровень вроде review-diff/review-diff/SKILL.md.

Claude Code отслеживает изменения в уже существующих папках ~/.claude/skills/ и .claude/skills/ прямо во время сессии. Если верхней папки skills не было при запуске и вы создали её впервые, перезапустите Claude Code. После этого изменения самого SKILL.md обычно подхватываются без рестарта.

Можно задать Claude вопрос: «Какие skills сейчас доступны?» В списке должен появиться review-diff. Если его нет, дальнейшая настройка description пока не поможет — сначала исправьте обнаружение файла.

Claude выбирает skill по description. Формулировка «Полезный инструмент для кода» почти ничего не сообщает о моменте вызова. Укажите действие и фразы, которыми пользователь реально описывает задачу: проверить git diff, просмотреть незакоммиченные изменения, подготовить commit.

Не делайте descriptions нескольких skills почти одинаковыми. Один может отвечать за ревью diff, другой — за формирование commit message, третий — за запуск тестов. Пересекающиеся описания усложняют выбор.

После правки повторите одну и ту же пару тестов: обычную просьбу и /review-diff. Так можно отделить ошибку маршрутизации от ошибки в самой инструкции.

Сломанный YAML оставляет Claude без нормального description. Частые причины — неверные отступы, лишний двоеточие в однострочном значении и забытый разделитель —. Slash-команда при этом иногда остаётся доступной, но автоматическое совпадение перестаёт работать.

Запустите Claude Code с диагностикой:

«claude —debug»

Найдите сообщение об ошибке разбора SKILL.md. Сам frontmatter можно отдельно проверить любым YAML-парсером. После исправления снова выполните обе проверки вызова.

Идеи и примеры можно искать в каталогах ComposioHQ/awesome-claude-skills и hesreallyhim/awesome-claude-code. Это сторонние коллекции, а не гарантия качества от Claude Code.

До копирования проверьте четыре вещи.

— Лицензия разрешает нужное использование.

— В SKILL.md нет требования загружать локальные файлы или секреты во внешний сервис.

— Frontmatter не выдаёт лишние разрешения инструментам.

— В scripts нет непонятных сетевых запросов, установочных команд и операций записи.

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

Минимальный review-diff готов, если выполнены четыре условия.

— SKILL.md лежит в правильном каталоге.

— Команда /review-diff доступна и запускается.

— Обычная фраза про незакоммиченные изменения вызывает тот же skill.

— Ответ опирается на текущий diff, а не на общие советы.

Только после этого стоит добавлять references, шаблоны или scripts. Сначала добейтесь короткого проверяемого цикла: файл, вызов, фактический вход, ожидаемый ответ.

Claude Code, Extend Claude with skills — https://code.claude.com/docs/en/skills

ComposioHQ, awesome-claude-skills — https://github.com/ComposioHQ/awesome-claude-skills

Awesome Claude Code — https://github.com/hesreallyhim/awesome-claude-code