SKILL.md с инструкциями, и Claude добавит его в свой набор инструментов. Claude использует skills при необходимости, или вы можете вызвать один напрямую с помощью /skill-name.
Создайте skill, когда вы постоянно вставляете один и тот же сценарий, контрольный список или многошаговую процедуру в чат, или когда раздел CLAUDE.md превратился в процедуру, а не в факт. В отличие от содержимого CLAUDE.md, тело skill загружается только при его использовании, поэтому большой справочный материал стоит почти ничего, пока вам он не понадобится.
Для встроенных команд, таких как
/help и /compact, и встроенных skills, таких как /debug и /code-review, см. справочник команд.Пользовательские команды были объединены с skills. Файл в .claude/commands/deploy.md и skill в .claude/skills/deploy/SKILL.md оба создают /deploy и работают одинаково. Ваши существующие файлы .claude/commands/ продолжают работать. Skills добавляют дополнительные функции: каталог для вспомогательных файлов, frontmatter для управления тем, кто вызывает skill, и возможность для Claude загружать их автоматически при необходимости.Встроенные skills
Claude Code включает набор встроенных skills, которые доступны в каждой сессии, если они не отключены с помощью параметраdisableBundledSkills, включая /code-review, /batch, /debug, /loop и /claude-api. В отличие от большинства встроенных команд, которые выполняют фиксированную логику напрямую, встроенные skills основаны на подсказках: они дают Claude подробные инструкции и позволяют ему организовать работу, используя свои инструменты. Вы вызываете их так же, как любой другой skill, введя / и затем имя skill.
Встроенные skills перечислены вместе со встроенными командами в справочнике команд, отмечены как Skill в столбце Purpose.
Запуск и проверка вашего приложения
Три встроенных skills работают вместе, чтобы запустить ваше приложение и подтвердить изменения в работающем приложении вместо простого тестирования:| Skill | Назначение |
|---|---|
/run | Запустите и управляйте вашим приложением, чтобы увидеть работающее изменение |
/verify | Соберите и запустите ваше приложение, чтобы подтвердить, что изменение кода делает то, что должно, без возврата к тестам или проверкам типов |
/run-skill-generator | Научите /run и /verify собирать и запускать ваш проект |
/run и /verify работают без настройки. Они определяют запуск на основе типа вашего проекта (CLI, сервер, TUI, управляемый браузером) и того, что находится в вашем README, package.json или Makefile. Это определение становится ненадежным для проектов, которым требуется что-то большее, чем стандартный запуск: база данных, файл env, графический сеанс, многоэтапная сборка.
/run-skill-generator вместо этого записывает рецепт. Он запускает ваше приложение из чистой среды, фиксирует то, что сработало (команды установки, переменные окружения, скрипт запуска), и фиксирует это как skill для каждого проекта в .claude/skills/run-<name>/. После этого /run, /verify и любой другой агент в репозитории следуют записанному рецепту вместо его переоткрытия. Запустите /run-skill-generator один раз для каждого проекта и снова, если процесс сборки или запуска изменится.
Начало работы
Создайте свой первый skill
Этот пример создаёт skill, который суммирует незафиксированные изменения в вашем git-репозитории и отмечает всё рискованное. Он загружает живой diff в подсказку перед тем, как Claude его прочитает, поэтому ответ основан на вашем фактическом рабочем дереве, а не на том, что Claude может угадать из открытых файлов. Claude загружает skill автоматически, когда вы спрашиваете об изменениях, или вы можете вызвать его напрямую с помощью/summarize-changes.
Создайте каталог skill
Создайте каталог для skill в папке личных skills. Личные skills доступны во всех ваших проектах.
Напишите SKILL.md
Каждому skill нужен файл Строка
SKILL.md с двумя частями: YAML frontmatter между маркерами ---, который говорит Claude, когда использовать skill, и содержимое markdown с инструкциями, которые Claude следует при запуске skill. Имя каталога становится командой, которую вы вводите, а description помогает Claude решить, когда загружать skill автоматически.Сохраните это в ~/.claude/skills/summarize-changes/SKILL.md:!`git diff HEAD` использует динамическое внедрение контекста: Claude Code запускает команду и заменяет строку её выходом перед тем, как Claude увидит содержимое skill, поэтому инструкции приходят с текущим diff уже встроенным.Протестируйте skill
Откройте git-проект, внесите небольшое изменение в любой файл и запустите Claude Code, выполнив Или вызовите его напрямую с именем skill:В любом случае Claude должен ответить с кратким резюме вашего редактирования и списком рисков.
claude. Вы можете протестировать skill двумя способами.Позвольте Claude вызвать его автоматически, задав вопрос, который соответствует описанию:Где находятся skills
Место, где вы сохраняете skill, определяет, кто может его использовать:| Местоположение | Путь | Применяется к |
|---|---|---|
| Enterprise | См. управляемые параметры | Все пользователи в вашей организации |
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | Все ваши проекты |
| Project | .claude/skills/<skill-name>/SKILL.md | Только этот проект |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md | Где включен плагин |
code-review в папке .claude/skills/ вашего проекта заменяет встроенный /code-review. Plugin skills используют пространство имён plugin-name:skill-name, поэтому они не могут конфликтовать с другими уровнями. Если у вас есть файлы в .claude/commands/, они работают так же, но если skill и команда имеют одинаковое имя, skill имеет приоритет.
Skills также загружаются из вложенных каталогов .claude/skills/ ниже вашего рабочего каталога. Когда Claude читает или редактирует файл в подкаталоге, skills из .claude/skills/ этого подкаталога становятся доступными. Это позволяет пакету monorepo предоставлять свои собственные skills, которые применяются при работе с этим пакетом, даже если сессия началась в корне репозитория.
Если вложенный skill имеет одинаковое имя с другим skill, оба остаются доступными. Например, с skill deploy в корне проекта и другим в apps/web/.claude/skills/:
- Вложенный появляется под квалифицированным именем каталога,
apps/web:deploy. - Его описание говорит, к какому каталогу он применяется.
- Claude выбирает вариант, который соответствует файлам, с которыми он работает.
/deploy запускает skill корня проекта. Введите квалифицированное имя /apps/web:deploy, чтобы запустить вложенный вариант явно.
Запись <skill-name> в местоположениях enterprise, personal или project может быть символической ссылкой на каталог в другом месте на диске. Claude Code следует символической ссылке и читает SKILL.md из целевого каталога, и если один и тот же целевой каталог доступен из более чем одного местоположения, Claude Code загружает skill один раз. Plugin skills обрабатывают символические ссылки иначе; см. Совместное использование файлов в marketplace с помощью символических ссылок.
Добавьте
.claude-plugin/plugin.json в папку skill, и она загружается как плагин с именем <name>@skills-dir, поэтому он может объединять agents, hooks и MCP servers. В .claude/skills/ проекта это требует предварительного принятия диалога доверия рабочей области.Обнаружение живых изменений
Claude Code следит за каталогами skills на предмет изменений файлов. Добавление, редактирование или удаление skill в~/.claude/skills/, в проекте .claude/skills/ или в .claude/skills/ внутри каталога --add-dir вступает в силу в текущей сессии без перезагрузки. Создание каталога skills верхнего уровня, который не существовал при запуске сессии, требует перезагрузки Claude Code, чтобы новый каталог можно было отслеживать.
Обнаружение живых изменений охватывает только текст
SKILL.md. Для папки skill, которая также является плагином, изменения в hooks/, .mcp.json, agents/ и output-styles/ требуют /reload-plugins для вступления в силу.Автоматическое обнаружение из родительских и вложенных каталогов
Project skills загружаются из.claude/skills/ в вашем начальном каталоге и в каждом родительском каталоге вплоть до корня репозитория, поэтому запуск Claude в подкаталоге по-прежнему подхватывает skills, определённые в корне. Когда вы работаете с файлами в подкаталогах ниже вашего начального каталога, Claude Code также обнаруживает skills из вложенных каталогов .claude/skills/ по требованию. Например, если вы редактируете файл в packages/frontend/, Claude Code также ищет skills в packages/frontend/.claude/skills/. Это поддерживает настройки monorepo, где пакеты имеют свои собственные skills.
Каждый skill — это каталог с SKILL.md в качестве точки входа:
SKILL.md содержит основные инструкции и является обязательным. Другие файлы необязательны и позволяют вам создавать более мощные skills: шаблоны для заполнения Claude, примеры выходных данных, показывающие ожидаемый формат, скрипты, которые Claude может выполнять, или подробную справочную документацию. Ссылайтесь на эти файлы из вашего SKILL.md, чтобы Claude знал, что они содержат и когда их загружать. См. Добавьте вспомогательные файлы для получения дополнительной информации.
Файлы в
.claude/commands/ по-прежнему работают и поддерживают тот же frontmatter. Skills рекомендуются, так как они поддерживают дополнительные функции, такие как вспомогательные файлы.Skills из дополнительных каталогов
Флаг--add-dir и команда /add-dir предоставляют доступ к файлам скорее, чем конфигурацию обнаружения, но skills — это исключение: .claude/skills/ в добавленном каталоге загружается автоматически. Это исключение применяется только к --add-dir и /add-dir. Параметр permissions.additionalDirectories в settings.json предоставляет доступ к файлам только и не загружает skills. См. Обнаружение живых изменений для того, как правки подхватываются во время сессии.
Другая конфигурация .claude/, такая как commands и output styles, не загружается из дополнительных каталогов. См. таблицу исключений для полного списка того, что загружается и что не загружается, и рекомендуемые способы совместного использования конфигурации между проектами.
Файлы CLAUDE.md из каталогов
--add-dir не загружаются по умолчанию. Чтобы загружать их, установите CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. См. Загрузка из дополнительных каталогов.Настройка skills
Skills настраиваются через YAML frontmatter в верхней частиSKILL.md и содержимое markdown, которое следует.
Типы содержимого skill
Файлы skill могут содержать любые инструкции, но размышление о том, как вы хотите их вызывать, помогает направить, что включить: Справочное содержимое добавляет знания, которые Claude применяет к вашей текущей работе. Соглашения, паттерны, руководства по стилю, знания предметной области. Это содержимое выполняется встроенно, поэтому Claude может использовать его вместе с контекстом вашего разговора./skill-name, а не позволять Claude решать, когда их запускать. Добавьте disable-model-invocation: true, чтобы предотвратить автоматическое срабатывание Claude.
SKILL.md может содержать что угодно, но размышление о том, как вы хотите вызывать skill (вы, Claude или оба) и где вы хотите его запускать (встроенно или в subagent), помогает направить, что включить. Для сложных skills вы также можете добавить вспомогательные файлы, чтобы сохранить основной skill сосредоточенным.
Сохраняйте само тело кратким. После загрузки skill его содержимое остаётся в контексте на протяжении ходов, поэтому каждая строка — это повторяющаяся стоимость токенов. Указывайте, что делать, а не рассказывайте, как или почему, и применяйте тот же тест краткости, который вы бы применили к содержимому CLAUDE.md.
Справочник frontmatter
Помимо содержимого markdown, вы можете настроить поведение skill, используя поля YAML frontmatter между маркерами--- в верхней части вашего файла SKILL.md:
description рекомендуется, чтобы Claude знал, когда использовать skill.
| Поле | Обязательно | Описание |
|---|---|---|
name | Нет | Отображаемое имя, показываемое в списках skills. По умолчанию используется имя каталога. См. Как skill получает имя команды, чтобы узнать, чем это отличается от имени, которое вы вводите для вызова skill. |
description | Рекомендуется | Что делает skill и когда его использовать. Claude использует это, чтобы решить, когда применять skill. Если опущено, использует первый абзац содержимого markdown. Поместите основной вариант использования в первую очередь: комбинированный текст description и when_to_use усекается на 1 536 символах в списке skills для уменьшения использования контекста. |
when_to_use | Нет | Дополнительный контекст для того, когда Claude должен вызвать skill, такой как фразы-триггеры или примеры запросов. Добавляется к description в списке skills и учитывается в лимите 1 536 символов. |
argument-hint | Нет | Подсказка, показываемая при автодополнении, чтобы указать ожидаемые аргументы. Пример: [issue-number] или [filename] [format]. |
arguments | Нет | Именованные позиционные аргументы для подстановки $name в содержимом skill. Принимает строку, разделённую пробелами, или список YAML. Имена соответствуют позициям аргументов по порядку. |
disable-model-invocation | Нет | Установите на true, чтобы предотвратить автоматическую загрузку этого skill Claude. Используйте для рабочих процессов, которые вы хотите запустить вручную с помощью /name. Также предотвращает предварительную загрузку skill в subagents. Начиная с версии 2.1.196, также предотвращает запуск skill при срабатывании запланированной задачи с skill в качестве подсказки. По умолчанию: false. |
user-invocable | Нет | Установите на false, чтобы скрыть из меню /. Используйте для фоновых знаний, которые пользователи не должны вызывать напрямую. По умолчанию: true. |
allowed-tools | Нет | Инструменты, которые Claude может использовать без запроса разрешения, когда этот skill активен. Принимает строку, разделённую пробелами или запятыми, или список YAML. |
disallowed-tools | Нет | Инструменты, удалённые из доступного пула Claude, пока этот skill активен. Используйте для автономных skills, которые никогда не должны вызывать определённые инструменты, такие как AskUserQuestion для фонового цикла. Принимает строку, разделённую пробелами или запятыми, или список YAML. Ограничение очищается при отправке вашего следующего сообщения. |
model | Нет | Модель для использования, когда этот skill активен. Переопределение применяется для остальной части текущего хода и не сохраняется в параметры; модель сессии возобновляется при вашем следующем запросе. Принимает те же значения, что и /model, или inherit, чтобы сохранить активную модель. Значение, исключённое списком разрешений availableModels вашей организации, не используется, и сессия сохраняет свою текущую модель. |
effort | Нет | Уровень усилий при активном этом skill. Переопределяет уровень усилий сессии. По умолчанию: наследует из сессии. Опции: low, medium, high, xhigh, max; доступные уровни зависят от модели. |
context | Нет | Установите на fork, чтобы запустить в контексте forked subagent. |
agent | Нет | Какой тип subagent использовать, когда установлен context: fork. |
hooks | Нет | Hooks, ограниченные жизненным циклом этого skill. См. Hooks в skills и agents для формата конфигурации. |
paths | Нет | Glob паттерны, которые ограничивают, когда этот skill активируется. Принимает строку, разделённую запятыми, или список YAML. Когда установлено, Claude загружает skill автоматически только при работе с файлами, соответствующими паттернам. Использует тот же формат, что и правила, специфичные для пути. |
shell | Нет | Shell для использования в блоках !`command` и ```! в этом skill. Принимает bash (по умолчанию) или powershell. Установка powershell запускает встроенные команды shell через PowerShell на Windows. Требует CLAUDE_CODE_USE_POWERSHELL_TOOL=1. |
Как skill получает имя команды
Команда, которую вы вводите для вызова skill, зависит от того, где находится файл skill. Поле frontmattername устанавливает отображаемый ярлык, показываемый в списках skills и, за исключением корневого SKILL.md плагина, не изменяет то, что вы вводите после /.
Таблица ниже показывает, откуда берётся имя команды для каждого макета:
| Расположение skill | Источник имени команды | Пример |
|---|---|---|
Каталог skill в ~/.claude/skills/ или .claude/skills/ | Имя каталога | .claude/skills/deploy-staging/SKILL.md → /deploy-staging |
Вложенный каталог .claude/skills/, когда имя конфликтует с другим skill | Путь подкаталога относительно рабочего каталога, затем имя каталога skill | apps/web/.claude/skills/deploy/SKILL.md → /apps/web:deploy |
Файл в .claude/commands/ | Имя файла без расширения | .claude/commands/deploy.md → /deploy |
Подкаталог skills/ плагина | Имя каталога, с пространством имён по плагину | my-plugin/skills/review/SKILL.md → /my-plugin:review |
Корневой SKILL.md плагина | Frontmatter name, с именем каталога плагина в качестве резервного варианта | my-plugin/SKILL.md с name: review → /my-plugin:review. См. Правила поведения пути |
name устанавливает имя команды, потому что нет каталога skill, чтобы взять его оттуда. Если name не установлен в frontmatter, вместо этого используется имя каталога плагина.
Доступные подстановки строк
Skills поддерживают подстановку строк для динамических значений в содержимом skill:| Переменная | Описание |
|---|---|
$ARGUMENTS | Все аргументы, переданные при вызове skill. Если $ARGUMENTS отсутствует в содержимом, аргументы добавляются как ARGUMENTS: <value>. |
$ARGUMENTS[N] | Доступ к конкретному аргументу по индексу на основе 0, например $ARGUMENTS[0] для первого аргумента. |
$N | Сокращение для $ARGUMENTS[N], например $0 для первого аргумента или $1 для второго. |
$name | Именованный аргумент, объявленный в списке frontmatter arguments. Имена соответствуют позициям по порядку, поэтому с arguments: [issue, branch] заполнитель $issue расширяется до первого аргумента и $branch ко второму. |
${CLAUDE_SESSION_ID} | Текущий ID сессии. Полезно для логирования, создания файлов, специфичных для сессии, или корреляции выходных данных skill с сессиями. |
${CLAUDE_EFFORT} | Текущий уровень усилий: low, medium, high, xhigh или max. Ultracode не является отдельным уровнем и сообщается как xhigh. Используйте это, чтобы адаптировать инструкции skill к активному параметру усилий. |
${CLAUDE_SKILL_DIR} | Каталог, содержащий файл SKILL.md skill. Для plugin skills это подкаталог skill в плагине, а не корень плагина. Используйте это в командах bash injection для ссылки на скрипты или файлы, поставляемые с skill, независимо от текущего рабочего каталога. |
${CLAUDE_PROJECT_DIR} | Каталог корня проекта. Это тот же путь, который hooks и MCP серверы получают как CLAUDE_PROJECT_DIR. Используйте это для ссылки на скрипты или файлы, специфичные для проекта, такие как ${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh, независимо от того, где установлен skill. |
${CLAUDE_PROJECT_DIR} требует Claude Code версии 2.1.196 или позже. Она применяется как к телу skill, так и к frontmatter allowed-tools, поэтому правило разрешения, такое как Bash(${CLAUDE_PROJECT_DIR}/scripts/lint.sh *), разрешается в тот же путь, который использует тело skill.
Индексированные аргументы используют кавычки в стиле shell, поэтому оборачивайте многословные значения в кавычки, чтобы передать их как один аргумент. Например, /my-skill "hello world" second заменяет $0 на hello world и $1 на second. Заполнитель $ARGUMENTS всегда расширяется до полной строки аргумента в том виде, в котором она была введена.
Чтобы включить литеральный $ перед цифрой, ARGUMENTS или объявленным именем аргумента, например $1.00 в прозе, экранируйте его обратной косой чертой: \$1.00. Обратная косая черта перед любым другим $ остаётся неизменной. Только одна обратная косая черта непосредственно перед токеном экранирует его. Удвоенная обратная косая черта, такая как \\$1, оставляет обе обратные косые черты на месте, и $1 всё ещё расширяется до значения аргумента.
Пример использования подстановок:
Добавьте вспомогательные файлы
Skills могут включать несколько файлов в их каталоге. Это сохраняетSKILL.md сосредоточенным на основном, позволяя Claude получать доступ к подробному справочному материалу только при необходимости. Большие справочные документы, спецификации API или коллекции примеров не нужно загружать в контекст каждый раз, когда запускается skill.
SKILL.md, чтобы Claude знал, что содержит каждый файл и когда его загружать:
Управляйте тем, кто вызывает skill
По умолчанию как вы, так и Claude можете вызывать любой skill. Вы можете ввести/skill-name, чтобы вызвать его напрямую, и Claude может загружать его автоматически при необходимости для вашего разговора. Два поля frontmatter позволяют вам ограничить это:
-
disable-model-invocation: true: Только вы можете вызвать skill. Используйте это для рабочих процессов с побочными эффектами или которые вы хотите контролировать по времени, такие как/commit,/deployили/send-slack-message. Вы не хотите, чтобы Claude решил развернуть, потому что ваш код выглядит готовым. -
user-invocable: false: Только Claude может вызвать skill. Используйте это для фоновых знаний, которые не являются действенными как команда. Skilllegacy-system-contextобъясняет, как работает старая система. Claude должен знать это при необходимости, но/legacy-system-contextне является значимым действием для пользователей.
disable-model-invocation: true предотвращает автоматическое запуск Claude:
| Frontmatter | Вы можете вызвать | Claude может вызвать | Когда загружается в контекст |
|---|---|---|---|
| (по умолчанию) | Да | Да | Описание всегда в контексте, полный skill загружается при вызове |
disable-model-invocation: true | Да | Нет | Описание не в контексте, полный skill загружается при вашем вызове |
user-invocable: false | Нет | Да | Описание всегда в контексте, полный skill загружается при вызове |
В обычной сессии описания skills загружаются в контекст, чтобы Claude знал, что доступно, но полное содержимое skill загружается только при вызове. Subagents с предварительно загруженными skills работают иначе: полное содержимое skill внедряется при запуске.
Жизненный цикл содержимого skill
Когда вы или Claude вызываете skill, отрендеренное содержимоеSKILL.md входит в разговор как одно сообщение и остаётся там для остальной части сессии. Claude Code не перечитывает файл skill при последующих ходах, поэтому пишите рекомендации, которые должны применяться на протяжении всей задачи, как постоянные инструкции, а не одноразовые шаги.
Auto-compact переносит вызванные skills в рамках бюджета токенов. Когда разговор суммируется для освобождения контекста, Claude Code повторно прикрепляет самый последний вызов каждого skill после сводки, сохраняя первые 5 000 токенов каждого. Повторно прикреплённые skills делят объединённый бюджет в 25 000 токенов. Claude Code заполняет этот бюджет, начиная с самого недавно вызванного skill, поэтому более старые skills могут быть полностью удалены после компактирования, если вы вызвали много в одной сессии.
Если skill кажется перестаёт влиять на поведение после первого ответа, содержимое обычно всё ещё присутствует, и модель выбирает другие инструменты или подходы. Усильте описание skill и инструкции, чтобы модель продолжала его предпочитать, или используйте hooks для детерминированного обеспечения поведения. Если skill большой или вы вызвали несколько других после него, повторно вызовите его после компактирования, чтобы восстановить полное содержимое.
Предварительно одобрите инструменты для skill
Полеallowed-tools предоставляет разрешение для перечисленных инструментов, пока skill активен, поэтому Claude может использовать их без запроса вашего одобрения. Это не ограничивает, какие инструменты доступны: каждый инструмент остаётся вызываемым, и ваши параметры разрешений по-прежнему управляют инструментами, которые не указаны.
Для skills, проверенных в каталоге .claude/skills/ проекта, allowed-tools вступает в силу после того, как вы примете диалог доверия рабочей области для этой папки, так же как правила разрешений в .claude/settings.json. Проверьте skills проекта перед доверием к репозиторию, так как skill может предоставить себе широкий доступ к инструментам.
Этот skill позволяет Claude запускать команды git без одобрения за использование, когда вы вызываете его:
disallowed-tools в frontmatter skill. Ограничение очищается при отправке вашего следующего сообщения. Чтобы заблокировать инструменты во всех skills и подсказках, добавьте правила отказа в ваши параметры разрешений.
Передайте аргументы в skills
Как вы, так и Claude можете передавать аргументы при вызове skill. Аргументы доступны через заполнитель$ARGUMENTS.
Этот skill исправляет проблему GitHub по номеру. Заполнитель $ARGUMENTS заменяется на всё, что следует за именем skill:
/fix-issue 123, Claude получает “Fix GitHub issue 123 following our coding standards…”
Если вы вызываете skill с аргументами, но skill не включает $ARGUMENTS, Claude Code добавляет ARGUMENTS: <your input> в конец содержимого skill, чтобы Claude всё ещё видел, что вы ввели.
Для доступа к отдельным аргументам по позиции используйте $ARGUMENTS[N] или более короткий $N:
/migrate-component SearchBar React Vue заменяет $ARGUMENTS[0] на SearchBar, $ARGUMENTS[1] на React и $ARGUMENTS[2] на Vue. Тот же skill, используя сокращение $N:
Продвинутые паттерны
Внедрите динамический контекст
Синтаксис!`<command>` запускает команды оболочки перед отправкой содержимого skill Claude. Выходные данные команды заменяют заполнитель, поэтому Claude получает фактические данные, а не саму команду.
Этот skill суммирует pull request, получая живые данные PR с помощью GitHub CLI. Команды !`gh pr diff` и другие запускаются первыми, и их выходные данные вставляются в подсказку:
- Каждый
!`<command>`выполняется немедленно (перед тем, как Claude что-либо увидит) - Выходные данные заменяют заполнитель в содержимом skill
- Claude получает полностью отрендеренную подсказку с фактическими данными PR
!`<command>` заполнителей, поэтому команда не может выдать заполнитель для последующего прохода для расширения.
Встроенная форма распознаётся только тогда, когда ! появляется в начале строки или сразу после пробела. Если ! следует за другим символом, как в KEY=!`cmd`, заполнитель остаётся буквальным текстом и команда не запускается.
Для многострочных команд используйте блок кода, открытый с ```! вместо встроенной формы:
"disableSkillShellExecution": true в параметры. Каждая команда заменяется на [shell command execution disabled by policy] вместо запуска. Встроенные и управляемые skills не затронуты. Этот параметр наиболее полезен в управляемых параметрах, где пользователи не могут его переопределить.
Запустите skills в subagent
Добавьтеcontext: fork в ваш frontmatter, когда вы хотите, чтобы skill запускался в изоляции. Содержимое skill становится подсказкой, которая управляет subagent. Он не будет иметь доступ к истории вашего разговора.
Skills и subagents работают вместе в двух направлениях:
| Подход | Системная подсказка | Задача | Также загружает |
|---|---|---|---|
Skill с context: fork | От типа агента | Содержимое SKILL.md | CLAUDE.md, кроме случаев, когда агент является Explore или Plan |
Subagent с полем skills | Тело markdown subagent | Сообщение делегирования Claude | Предварительно загруженные skills + CLAUDE.md |
context: fork вы пишете задачу в своём skill и выбираете тип агента для её выполнения. Встроенные агенты Explore и Plan пропускают CLAUDE.md и git status, чтобы сохранить их контекст небольшим, поэтому forked skill, использующий agent: Explore, видит только содержимое SKILL.md и собственную системную подсказку агента. Для обратного случая, где вы определяете пользовательский subagent, который использует skills как справочный материал, см. Subagents.
Пример: Research skill, используя Explore agent
Этот skill запускает исследование в forked Explore agent. Содержимое skill становится задачей, и агент предоставляет инструменты только для чтения, оптимизированные для исследования кодовой базы:- Создаётся новый изолированный контекст
- Subagent получает содержимое skill в качестве своей подсказки (“Research $ARGUMENTS thoroughly…”)
- Поле
agentопределяет среду выполнения (модель, инструменты и разрешения) - Результаты суммируются и возвращаются в ваш основной разговор
agent указывает, какую конфигурацию subagent использовать. Опции включают встроенные агенты (Explore, Plan, general-purpose) или любой пользовательский subagent из .claude/agents/. Если опущено, использует general-purpose.
Ограничьте доступ Claude к skills
По умолчанию Claude может вызывать любой skill, у которого не установленdisable-model-invocation: true. Skills, которые определяют allowed-tools, предоставляют Claude доступ к этим инструментам без одобрения за использование, когда skill активен. Ваши параметры разрешений по-прежнему управляют поведением одобрения базовой линии для всех остальных инструментов. Несколько встроенных команд также доступны через инструмент Skill, включая /init, /review и /security-review. Другие встроенные команды, такие как /compact, недоступны.
Три способа управления, какие skills может вызывать Claude:
Отключите все skills, отказав в инструменте Skill в /permissions:
Skill(name) для точного совпадения, Skill(name *) для совпадения префикса с любыми аргументами.
Скройте отдельные skills, добавив disable-model-invocation: true в их frontmatter. Это полностью удаляет skill из контекста Claude.
Поле
user-invocable управляет только видимостью меню, а не доступом инструмента Skill. Используйте disable-model-invocation: true, чтобы заблокировать программный вызов.Переопределите видимость skill из параметров
ПараметрskillOverrides управляет видимостью skill из ваших параметров вместо frontmatter самого skill. Используйте его для skills, чей SKILL.md вы не хотите редактировать, например для тех, которые проверены в общем репозитории проекта или предоставлены MCP сервером. Меню /skills пишет его для вас: выделите skill и нажмите Space для циклического переключения состояний, затем Enter для сохранения в .claude/settings.local.json.
Каждый ключ — это имя skill, и каждое значение — одно из четырёх состояний:
| Значение | Указано Claude | В меню / |
|---|---|---|
"on" | Имя и описание | Да |
"name-only" | Только имя | Да |
"user-invocable-only" | Скрыто | Да |
"off" | Скрыто | Скрыто |
skillOverrides, рассматривается как "on". Пример ниже сворачивает один skill до его имени и полностью отключает другой:
skillOverrides. Управляйте ими через /plugin вместо этого.
Оцените и улучшайте skill
Видение того, что skill срабатывает, говорит вам, что Claude его нашёл, а не то, что он делал то, что вы предполагали. Чтобы знать, что skill работает, измеряйте две вещи отдельно: срабатывает ли Claude на подсказки, которые он должен, и соответствует ли выходной сигнал тому, что вы ожидаете, когда он это делает. Проверка обоих — это сравнение базовой линии. Соберите несколько реалистичных подсказок, запустите каждую в свежей сессии с доступным skill и снова с ним отключённым, и сравните результаты. Свежая сессия важна, потому что оставшийся контекст от авторства skill будет скрывать пробелы в написанных инструкциях.Запустите evals с skill-creator
Плагинskill-creator автоматизирует цикл сравнения внутри Claude Code. Установите его из официального marketplace:
/plugin marketplace update claude-plugins-official для его обновления, или /plugin marketplace add anthropics/claude-plugins-official, если вы его ещё не добавили. Затем повторите попытку установки.
После установки запустите /reload-plugins, чтобы сделать skills плагина доступными в текущей сессии. Затем попросите Claude оценить существующий skill, например evaluate my summarize-changes skill with skill-creator. Плагин проведёт вас через написание тестовых случаев и запустит цикл:
- Тестовые случаи: сохраняет подсказки, входные файлы и ожидаемое поведение в
evals/evals.jsonвнутри каталога skill - Изолированные запуски: порождает subagent для каждого тестового случая, чтобы каждый запуск начинался с чистого контекста, и записывает количество токенов и продолжительность
- Оценка: проверяет каждое утверждение против выходного сигнала и пишет pass или fail с доказательством в
grading.json - Benchmark: агрегирует процент успеха, время и токены для с-skill против без-skill в
benchmark.json, чтобы вы могли сравнить улучшение процента успеха с накладными расходами на токены и время - Сравнение версий: запускает слепой A/B между двумя версиями skill, чтобы вы могли подтвердить, что правка — это улучшение перед фиксацией
- Настройка описания: генерирует подсказки should-trigger и should-not-trigger, измеряет процент попаданий и предлагает правки описания, когда skill активируется на неправильных запросах
- Средство просмотра отзывов: открывает HTML отчёт, где вы проверяете каждый выходной сигнал и записываете качественный отзыв, который следующая итерация читает
Делитесь skills
Skills могут распространяться на разных уровнях в зависимости от вашей аудитории:- Project skills: Зафиксируйте
.claude/skills/в контроле версий - Plugins: Создайте каталог
skills/в вашем плагине - Managed: Развёртывайте организацию-широко через управляемые параметры
Генерируйте визуальный выходной сигнал
Skills могут объединять и запускать скрипты на любом языке, давая Claude возможности, выходящие за рамки того, что возможно в одной подсказке. Один мощный паттерн — генерирование визуального выходного сигнала: интерактивные HTML файлы, которые открываются в вашем браузере для исследования данных, отладки или создания отчётов. Этот пример создаёт обозреватель кодовой базы: интерактивное древовидное представление, где вы можете развёртывать и свёртывать каталоги, видеть размеры файлов с первого взгляда и определять типы файлов по цвету. Создайте каталог Skill:~/.claude/skills/codebase-visualizer/SKILL.md. Описание говорит Claude, когда активировать этот Skill, а инструкции говорят Claude запустить поставляемый скрипт. Путь скрипта использует ${CLAUDE_SKILL_DIR}, поэтому он разрешается правильно независимо от того, установлен ли skill на личном, проектном или плагин-уровне:
~/.claude/skills/codebase-visualizer/scripts/visualize.py. Этот скрипт сканирует дерево каталогов и генерирует самодостаточный HTML файл с:
- Боковой панелью сводки, показывающей количество файлов, количество каталогов, общий размер и количество типов файлов
- Столбчатой диаграммой, разбивающей кодовую базу по типу файла (топ 8 по размеру)
- Свёртываемым деревом, где вы можете развёртывать и свёртывать каталоги, с цветовыми индикаторами типов файлов
codebase-map.html и открывает его в вашем браузере.
Этот паттерн работает для любого визуального выходного сигнала: графики зависимостей, отчёты о покрытии тестами, документация API или визуализации схемы базы данных. Поставляемый скрипт выполняет тяжёлую работу, пока Claude обрабатывает оркестрацию.
Устранение неполадок
Skill не срабатывает
Если Claude не использует ваш skill при необходимости:- Проверьте, что описание включает ключевые слова, которые пользователи естественно скажут
- Убедитесь, что skill появляется в
What skills are available? - Попробуйте переформулировать ваш запрос, чтобы лучше соответствовать описанию
- Вызовите его напрямую с помощью
/skill-name, если skill может быть вызван пользователем
/skill-name все еще работает, но Claude не имеет description для сопоставления. Запустите с флагом --debug, чтобы увидеть ошибку парсинга.
Skill срабатывает слишком часто
Если Claude использует ваш skill, когда вы этого не хотите:- Сделайте описание более конкретным
- Добавьте
disable-model-invocation: true, если вы хотите только ручной вызов
Описания skills обрезаны
Описания skills загружаются в контекст, чтобы Claude знал, что доступно. Все имена skills всегда включены, но если у вас много skills, описания сокращаются, чтобы соответствовать бюджету символов, что может удалить ключевые слова, которые Claude нужны для совпадения с вашим запросом. Бюджет масштабируется на 1% контекстного окна модели. Когда он переполняется, описания для skills, которые вы вызываете реже всего, удаляются в первую очередь, поэтому skills, которые вы фактически используете, сохраняют полный текст. Запустите/doctor, чтобы увидеть, сколько описаний skills сокращаются или удаляются и какие skills затронуты.
Начиная с версии 2.1.196, строка Skills в /context отображает размер списка после применения бюджета, поэтому он соответствует тому, что получает модель. В более ранних версиях подсчитывался полный текст каждого описания, поэтому строка могла показывать значение в несколько раз больше, чем бюджет, который сообщает /doctor.
Чтобы повысить бюджет, установите параметр skillListingBudgetFraction (например, 0.02 = 2%) или переменную окружения SLASH_COMMAND_TOOL_CHAR_BUDGET на фиксированное количество символов. Чтобы освободить бюджет для других skills, установите записи с низким приоритетом на "name-only" в skillOverrides, чтобы они отображались без описания. Вы также можете обрезать текст description и when_to_use в источнике: поместите ключевой вариант использования в начало, так как комбинированный текст каждой записи ограничен 1 536 символами независимо от бюджета. Лимит настраивается с помощью skillListingMaxDescChars.
Связанные ресурсы
- Отладка вашей конфигурации: диагностируйте, почему skill не появляется или не срабатывает
- Evaluating skill output quality: формат файла eval и рабочий процесс итерации на agentskills.io
- Skill authoring best practices: рекомендации по написанию, которые применяются во всех продуктах Claude
- Subagents: делегируйте задачи специализированным агентам
- Plugins: упакуйте и распространяйте skills с другими расширениями
- Hooks: автоматизируйте рабочие процессы вокруг событий инструментов
- Memory: управляйте файлами CLAUDE.md для постоянного контекста
- Commands: справочник для встроенных команд и встроенных skills
- Permissions: управляйте доступом к инструментам и skills
- Claude Tag skills: skills проекта, зафиксированные в репозитории, также загружаются при использовании этого репозитория в канале Claude Tag