Руководства

Skills в Claude Code: как пользоваться и как писать SKILL.md

Опубликовано 30 октября 2026 г. · Проверено 30 октября 2026 г.

Skill — это файл SKILL.md с инструкциями: Claude использует его, когда он уместен, либо вы вызываете его напрямую командой /skill-name. Эта страница разбирает документацию Anthropic Extend Claude with skills: создание первого skill, где живут skills, как писать frontmatter, как управлять тем, кто вызывает skill, и что проверить, если он не срабатывает. Документация проверена 30 октября 2026 г.

Когда писать skill

Критерий из документации: вы снова и снова вставляете в чат одни и те же инструкции, чек-лист или многошаговую процедуру, либо раздел CLAUDE.md превратился в процедуру, а не в факт. В отличие от содержимого CLAUDE.md, тело skill загружается только при использовании, поэтому длинный справочный материал почти ничего не стоит, пока не понадобится. О самом CLAUDE.md см. как написать CLAUDE.md.

В документации также сказано, что пользовательские команды объединены со skills. Файл .claude/commands/deploy.md и skill .claude/skills/deploy/SKILL.md оба создают /deploy и работают одинаково, а существующие файлы .claude/commands/ продолжают работать. Skills добавляют каталог для вспомогательных файлов, frontmatter для управления тем, кто их вызывает — вы или Claude, и возможность для Claude загружать их автоматически, когда они уместны.

Создайте свой первый skill

Этот пример взят из документации: skill, который кратко описывает незакоммиченные изменения в репозитории git и отмечает всё рискованное. Сначала создайте для него каталог в папке личных skills. Личные skills доступны во всех ваших проектах:

mkdir -p ~/.claude/skills/summarize-changes

Во-вторых, напишите SKILL.md. Этот файл нужен каждому skill, и состоит он из двух частей: YAML frontmatter между маркерами ---, который сообщает Claude, когда использовать skill, и содержимое в markdown с инструкциями, которым Claude следует при запуске skill.

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

Имя каталога, или name из frontmatter, если вы его задали, становится командой, которую вы вводите, а description помогает Claude решить, когда загружать skill автоматически. Строка !`git diff HEAD` использует динамическую подстановку контекста: Claude Code выполняет команду и заменяет строку её выводом до того, как Claude увидит содержимое skill, так что инструкции приходят уже с подставленным текущим diff.

В-третьих, проверьте. Откройте проект git, внесите небольшую правку в любой файл и запустите Claude Code командой claude. Подойдёт любой способ:

What did I change?     # matches the description, so Claude can invoke it automatically
/summarize-changes     # or invoke it directly with the skill name

В любом случае Claude должен ответить кратким описанием вашей правки и списком рисков.

Где живут skills

Место, где вы сохраняете skill, определяет, какие сессии его загружают. Сохраните его в домашнем каталоге, чтобы он был в каждом проекте, закоммитьте в репозиторий, чтобы поделиться со всеми, кто там работает, либо распространите через плагин или managed settings, чтобы охватить всю команду.

Когда у двух skills одно имя (выдержка из таблицы документации):

• Одно имя в двух из уровней enterprise, личный и проект: enterprise важнее личного, а личный важнее проектного. Если deploy есть и в ~/.claude/skills/, и в .claude/skills/ проекта, /deploy запускает личный.
• Skill и файл в .claude/commands/: побеждает skill.
• Skill плагина и skill в любом из мест выше: загружаются оба, потому что skills плагинов получают пространство имён /plugin-name:skill-name.

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

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

Самые важные поля frontmatter

Все поля необязательны. Рекомендуется только description. Имя поля должно в точности совпадать с таблицей, включая дефисы: Claude Code игнорирует нераспознанное поле, не сообщая об ошибке. Логические поля принимают yes, no, on, off, 1 и 0 в любом регистре, помимо true и false.

В документации перечислены и другие поля, включая model, effort, agent, background, hooks, shell, metadata, license и compatibility; здесь они не рассматриваются. Одна оговорка: Claude Code читает frontmatter, только когда открывающий --- — первая строка файла. Иначе он считает содержимым skill весь файл, включая маркеры ---.

Вызвать skill самому или позволить Claude выбрать

По умолчанию любой skill могут вызывать и вы, и Claude. Вы вводите /skill-name, чтобы вызвать его напрямую, а Claude может загрузить его автоматически, когда он уместен в вашем разговоре. Два поля frontmatter это ограничивают:

• disable-model-invocation: true: Claude не может вызвать skill сам. Используйте для процессов с побочными эффектами или такими, момент запуска которых вы хотите контролировать, вроде /commit, /deploy или /send-slack-message. Вы не хотите, чтобы Claude решил задеплоить, потому что ваш код выглядит готовым.
• user-invocable: false: skill может вызывать только Claude. Используйте для фоновых знаний, не являющихся действием-командой, например для skill legacy-system-context, объясняющего, как работает старая система.

Пример deploy из документации:

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

Если Claude всё равно попытается, Claude Code блокирует вызов и указывает не воспроизводить шаги деплоя другим способом, так что ждите, что Claude предложит вам самим выполнить /deploy.

Чтобы запустить skill напрямую, поставьте его имя в начале сообщения: /deploy staging запускает skill напрямую. После простого текста, как в go ahead and /deploy to staging, напрямую ничего не запускается. Имя считается вашим разрешением для этого сообщения: Claude может запустить skill, пока отвечает, и по формулировке судит, просили ли вы об этом. Чтобы написать о skill, не разрешая запуск, опустите косую черту.

Аргументы и вспомогательные файлы

Аргументы при вызове skill могут передавать и вы, и Claude. Аргументы доступны через заполнитель $ARGUMENTS, который заменяется всем, что следует за именем skill:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

Когда вы выполняете /fix-issue 123, Claude получает «Fix GitHub issue 123 following our coding standards...». Чтобы обращаться к отдельным аргументам по позиции, используйте $ARGUMENTS[N] или более короткое $N. Если вы вызываете skill с аргументами, но ни один заполнитель в содержимом skill их не получает, Claude Code добавляет ARGUMENTS: <your input> в конец содержимого skill, чтобы Claude всё равно видел то, что вы набрали.

В каталоге skill может быть несколько файлов. Так SKILL.md остаётся сосредоточенным на главном, а Claude читает подробный справочный материал только при необходимости:

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

Ссылайтесь на вспомогательные файлы из SKILL.md, чтобы Claude знал, что в каждом файле и когда его загружать:

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

Совет из документации: держите SKILL.md короче 500 строк, а подробный справочный материал выносите в отдельные файлы.

Как написать хорошее описание

• Используйте ключевые слова, которые пользователи говорят естественно. Первый пункт в списке устранения неполадок документации — проверить, что описание их содержит. Пример выше прямо называет триггер: «Use when the user asks what changed, wants a commit message, or asks to review their diff.»
• Главный сценарий ставьте первым. Объединённый текст description и when_to_use усекается на 1 536 символах в списке skills.
• Сделайте описание конкретнее, если оно срабатывает слишком часто. Это первая рекомендация документации, когда skill срабатывает там, где не нужно.
• Угловые скобки экранируются. < и > в description и when_to_use отображаются как < и >. Чтобы показать заполнитель вроде <branch>, используйте квадратные скобки, [branch], или вынесите его в отдельную строку argument-hint.
• Держите тело коротким. После загрузки skill его содержимое остаётся в контексте на протяжении ходов, так что каждая строка — повторяющаяся стоимость в токенах. Пишите, что делать, а не рассказывайте, как и почему.

Устранение неполадок

Skill не срабатывает

• Проверьте, что описание содержит ключевые слова, которые пользователи говорят естественно.
• Убедитесь, что skill появляется в ответе на What skills are available?
• Попробуйте переформулировать запрос так, чтобы он ближе соответствовал описанию.
• Вызовите его напрямую через /skill-name, если skill допускает вызов пользователем.
• Если /skill-name тоже не распознаётся, проверьте, не отклонил ли Claude Code имя skill (это вызывают такие символы, как пробел нулевой ширины, управляющий символ, < или >).
• Если skill задаёт paths, проверьте, что файлы, которые Claude читает, правит или пишет, находятся внутри текущего рабочего каталога Claude. Для файлов вне него skill не активируется, например для файлов в соседнем рабочем дереве git, даже если вы добавили его через /add-dir.

Если YAML frontmatter написан с ошибками, Claude Code загружает тело skill с пустыми метаданными, поэтому /skill-name всё ещё работает, но Claude не может сопоставлять запросы с вашим description. Запустите с --debug, чтобы увидеть ошибку разбора. Чтобы найти файлы SKILL.md, frontmatter которых не разбирается, выполните claude plugin validate для каталога skills, например claude plugin validate .claude/skills или claude plugin validate ~/.claude/skills. Нужен Claude Code v2.1.233 или новее.

Skill срабатывает слишком часто

Сделайте описание конкретнее. Добавьте disable-model-invocation: true, если нужен только ручной вызов.

Claude перестаёт следовать skill

Когда skill вызван, Claude Code добавляет его содержимое в разговор и не перечитывает файл в следующих ходах, поэтому указание, относящееся ко всей задаче, формулируйте как «Run the tests after every edit», а не «Run the tests». После сжатия Claude Code может сохранить только начало вызванного skill, поэтому самые важные инструкции помещайте ближе к началу SKILL.md и вызовите skill снова, чтобы восстановить его полное содержимое. Для правила, которое должно соблюдаться каждый раз, документация рекомендует вместо этого hook.

Описания обрезаются

При большом числе skills Claude Code отбрасывает часть описаний, чтобы уложиться в бюджет символов списка, а это убирает ключевые слова, нужные Claude для сопоставления с вашим запросом. Бюджет масштабируется как 1% контекстного окна модели, а описания отбрасываются начиная с тех skills, которые вы вызываете реже всего. Выполните /doctor, чтобы получить оценку стоимости списка в контексте и его самых крупных составляющих.

FAQ

Источники

• Claude Code: Extend Claude with skills (расположение skills, совпадения имён, поля frontmatter, управление вызовом, аргументы, вспомогательные файлы, устранение неполадок)