Zilmac блог
← Назад к технической практике

Как создать пользовательские Skills для Claude Code? Полное руководство по написанию SKILL.md, настройке каталогов и фактическому вызову

AIDevelopment ·~1 мин чтения

Два уровня размещения и один обязательный тест

>

В официальной документации Claude Code описаны два уровня размещения Skills — пользовательский и проектный (актуальное руководство по Skills). Поэтому создание пользовательского Skill стоит считать завершённым не после сохранения файла, а после проверки трёх условий: корректный SKILL.md находится в поддерживаемом каталоге, его описание соответствует нужной задаче, а фактический вызов приводит к результату, который соблюдает заданные инструкции.

Этот порядок подходит разработчикам, которые хотят превратить повторяющуюся работу в переиспользуемый процесс, командам, которым важно хранить общие инструкции рядом с проектом, и специалистам, проверяющим сценарии AI Agent. Если пути, поля метаданных или правила вызова менялись, сверяйтесь с текущей документацией Claude Code, а не переносите старые примеры без проверки.

Как выбрать каталог для Claude Code Skills

>

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

Уровень Расположение SKILL.md Подходящий сценарий Что проверить
Проектный .claude/skills/<имя-навыка>/SKILL.md Инструкция предназначена конкретному проекту и должна храниться вместе с его файлами Файл лежит внутри каталога навыка в .claude/skills/ текущего проекта
Пользовательский ~/.claude/skills/<имя-навыка>/SKILL.md Инструкция нужна одному разработчику в разных проектах Используется домашний каталог нужной учётной записи

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

Для первой проверки создайте отдельный каталог с понятным именем и поместите в него файл SKILL.md. Не начинайте с дополнительных вложенных документов и скриптов: пока не подтверждено распознавание основного файла, усложнённая структура затруднит диагностику. Сверьте полный путь с выбранным уровнем. Например, файл непосредственно в .claude/skills/review.md — это не та же структура, что каталог навыка с SKILL.md внутри.

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

Как написать SKILL.md для Claude Code

>

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

В начале файла используется frontmatter в формате YAML. В официальной документации в числе основных полей названы name и description; актуальные требования к ним и дополнительные возможности нужно сверять с описанием формата Skills. После frontmatter размещается текст инструкции. Для начальной версии оставьте только необходимые поля и саму инструкцию: дополнительные параметры стоит добавлять после того, как базовый вариант распознаётся и проходит тест.

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

---
name: review-config-change
description: Проверяет изменения файлов конфигурации проекта. Используйте при запросе на ревью конфигурации; не применяйте для исправления исходного кода или запуска миграций.
---

# Проверка изменений конфигурации

## Когда применять
Применяйте инструкцию, если задача касается изменённого файла конфигурации.
Если запрос не относится к конфигурации, сообщите, что этот Skill не подходит.

## Порядок работы
1. Найдите изменённые файлы конфигурации и просмотрите diff.
2. Проверьте, какие значения добавлены, удалены или переименованы.
3. Укажите конкретные возможные проблемы, ссылаясь на файл и фрагмент изменения.
4. Если проблем не найдено, перечислите проверенные файлы и границы проведённой проверки.

## Ограничения
Не изменяйте файлы и не запускайте команды, которые меняют состояние проекта.
Не утверждайте, что проверены файлы, которые не были просмотрены.

Описание в примере задаёт конкретную область работы и исключает задачи, для которых Skill не предназначен. Текст инструкции разбивает абстрактную просьбу «провести ревью» на наблюдаемые действия, а ограничения помогают проверить, не вышла ли модель за заданные границы. Это полезно и при явном вызове, и при автоматическом выборе по описанию. Пример официальной структуры можно также посмотреть в Skill для создания навыков.

Проверьте синтаксис до запуска. Разделители frontmatter должны стоять на отдельных строках; YAML должен корректно разбираться; после метаданных должен идти текст инструкции. Не добавляйте команды, которые меняют состояние проекта, если ожидается только анализ. Если Skill должен использовать дополнительные материалы, сначала подтвердите работу минимального файла, а потом добавляйте эти материалы по одному и проверяйте пути к ним.

Шаг настройки: имя, метаданные и область действия

>

После подготовки содержимого проверьте, как именно Skill должен вызываться. Документация описывает явный вызов по имени и автоматический выбор в зависимости от соответствия задачи описанию навыка. Это разные сценарии: удачная ручная команда подтверждает, что Skill доступен по имени, но не доказывает, что он автоматически выберется для обычного запроса.

В документации также описаны поля disable-model-invocation и user-invocable. Они позволяют управлять автоматическим выбором модели и доступностью явного вызова пользователем. Не добавляйте их без понимания требуемого поведения: если автоматический вызов отключён, не следует ожидать, что модель выберет этот Skill из обычной формулировки задачи. И наоборот, если явный вызов ограничен настройкой, отсутствие навыка в ожидаемом пользовательском списке не обязательно означает ошибку пути. Сверяйте значения и ограничения полей с актуальным официальным описанием метаданных Skills.

Для первого теста оставьте только имя, точное описание и инструкцию. Сначала проверьте явный вызов; затем решите, нужно ли автоматическое применение или специальные ограничения. Такой порядок позволяет отличить ошибку формата от неверной настройки поведения. Не меняйте одновременно путь, описание и параметры вызова: иначе при успешном результате будет неясно, какая именно правка помогла.

Как Claude Code распознаёт и вызывает пользовательские Skills

>

Для явной проверки используйте команду, соответствующую имени навыка, например /review-config-change, и передайте небольшой запрос на ревью конкретного изменения. Имя вызова должно соответствовать имени Skill. Актуальный синтаксис и условия использования проверяйте в официальном руководстве по Skills, особенно если тестируете другую версию Claude Code или используете настройки, влияющие на доступность навыка.

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

Если автоматический выбор не срабатывает, сравните формулировку запроса с description. Запрос о форматировании исходного кода не должен совпадать с узкой инструкцией по анализу конфигурации. При расплывчатом описании сначала уточните назначение и границы Skill, а не добавляйте посторонние шаги. Для контекста проекта существует отдельный механизм инструкций и памяти; не смешивайте его с каталогом Skills и при необходимости сверяйте официальную документацию по памяти проекта.

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

Запишите, какой запрос был отправлен, какой вариант вызова использовался и какие критерии выполнены. Это не формальность: без одинакового тестового задания сравнить две редакции инструкции трудно. При командной проверке участникам полезно повторить один и тот же сценарий из репозитория, а не ограничиваться сообщением автора о том, что Skill «работает». Так становится видно, связано ли различие с содержимым файла, путём или конкретной средой.

Если Skill не обнаружен или срабатывает неверно

>

Если команда не появляется или навык не выбирается, проверяйте причины последовательно — сначала расположение, затем метаданные и поведение.

  1. Путь. Убедитесь, что выбран каталог, предусмотренный актуальной документацией, и что SKILL.md находится внутри отдельной папки навыка.
  2. Имя файла. Проверьте написание SKILL.md, регистр букв и расширение. Файл с похожим названием не заменяет ожидаемую структуру.
  3. Frontmatter. Проверьте разделители YAML, поле name и описание. Если не уверены в синтаксисе, временно уберите необязательные поля и протестируйте минимальный вариант.
  4. Уровень размещения. Уточните, не хранится ли Skill только в пользовательском каталоге, когда тест проводится в другой учётной записи или среде, и не проверяется ли другой проект.
  5. Способ вызова. Сверьте настройки автоматического и явного вызова с тем сценарием, который используете. Эти режимы проверяются отдельно.
  6. Соответствие запроса. Если явная команда работает, а автоматический выбор — нет, пересмотрите описание и формулировку тестового запроса. Они должны относиться к одной и той же задаче.

Если Skill распознан, но ответ отклоняется от инструкции, исправляйте не каталог, а формулировки и критерии. Уточните порядок действий, удалите противоречивые указания и сформулируйте ожидаемый результат так, чтобы его можно было проверить. Вместо «проверь тщательно» укажите, какие файлы анализировать, что включать в ответ и какие действия запрещены. После этого повторите прежний тест, меняя только одну часть инструкции за раз.

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

Выбор места для Skill и переход к рабочему использованию

>

Результат теста подсказывает следующий шаг:

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

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

Запустите рабочие процессы разработки на удалённом Mac

Zilmac предоставляет выделенный Mac mini M4 с полной macOS для разработки, сборок и тестирования.

Подключайтесь к удалённой машине через SSH или VNC и работайте с привычной средой macOS. — Посмотреть варианты плана

Ограниченное предложение

Zilmac

Zilmac предоставляет выделенный Mac mini M4 с полной macOS для разработки, сборок и тестирования.

Вернуться домой
Ограниченное предложение Посмотреть планы