Расширение Claude с помощью skills

Создавайте, управляйте и делитесь skills для расширения возможностей Claude в Claude Code. Включает пользовательские команды и встроенные skills.

Skills расширяют возможности Claude. Создайте файл SKILL.md с инструкциями, и Claude добавит его в свой набор инструментов. Claude использует skills при необходимости, или вы можете вызвать один напрямую с помощью /skill-name.

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

[!NOTE]

Для встроенных команд, таких как /help и /compact, и встроенных skills, таких как /debug и /code-review, см. справочник команд.

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

Skills Claude Code следуют открытому стандарту Agent Skills, который работает с несколькими инструментами AI. Claude Code расширяет стандарт дополнительными функциями, такими как управление вызовом, выполнение в подагенте и динамическое внедрение контекста. См. Использование frontmatter skill вне Claude Code для информации о том, какие поля frontmatter являются частью стандарта, а какие — расширениями Claude Code.

Встроенные skills

Claude Code включает набор встроенных skills, таких как /doctor, /code-review, /batch, /debug, /loop и /claude-api. Встроенные skills основаны на промптах: они дают Claude подробные инструкции и позволяют ему организовать работу, используя его инструменты. Большинство встроенных команд вместо этого выполняют фиксированную логику напрямую.

Вы вызываете встроенный skill так же, как любой другой skill, введя / и затем имя skill. Claude автоматически вызывает некоторые встроенные skills, когда это уместно; другие, включая /verify, запускаются только при вашем вызове, что позволяет вам контролировать, когда эти более длительные проверки тратят время и токены.

Большинство встроенных skills доступны в каждой сессии. Несколько зависят от конкретной функции: /workflow-authoring, например, доступен только когда динамические workflows включены.

Чтобы отключить встроенные skills, используйте параметр disableBundledSkills.

[!NOTE]

Проверка настройки /doctor остается доступной для ввода, когда disableBundledSkills включен. Чтобы скрыть её, установите переменную окружения DISABLE_DOCTOR_COMMAND или запись skillOverrides "doctor": "off".

Встроенные skills перечислены вместе со встроенными командами в справочнике команд, отмечены как Skill в столбце Purpose.

Проверка настройки с помощью /doctor

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

• Состояние установки: дублирующиеся или оставшиеся установки, проблемы с PATH, файлы настроек, которые не удается разобрать, а также наличие более новой версии в вашем канале выпусков
• Расширения: неиспользуемые skills, MCP-серверы и плагины в сравнении с их затратами контекста, а также медленные хуки
• Файлы CLAUDE.md: локальные файлы CLAUDE.md, дублирующие файлы из репозитория, содержимое CLAUDE.md в репозитории, которое Claude мог бы вывести из кодовой базы, а также оставшиеся всегда загружаемые указания, которые Claude предлагает перенести в skills и вложенные файлы CLAUDE.md, загружаемые по требованию
• Разрешения: предложение сделать авторежим вашим режимом разрешений по умолчанию и заранее одобрить команды только для чтения, которые вы часто отклоняете
• Использование: на тарифах Pro, Max, Ultra, Team или Enterprise — изменения, которые рекомендует /usage, чтобы снизить использование вашего тарифа, измеренное за последние 7 дней. Claude предлагает изменения, которые может внести сам, а остальное сообщает в виде советов, например команды, которую нужно выполнить вам. Проверка использования требует Claude Code v2.1.305 или позже, и /doctor пропускает её, пока подключен Remote Control.

Для диагностики установки только для чтения без запуска сессии выполните вместо этого claude doctor в терминале.

Чтобы проверить ваши инструкции, а не настройку, запустите /doctor prompt-audit в промпте Claude Code. Вместо проверки настройки Claude проверяет ваши файлы CLAUDE.md, skills и другую конфигурацию на наличие устаревших или противоречащих друг другу инструкций. Подкоманда prompt-audit требует Claude Code v2.1.283 или позже.

Запуск и проверка вашего приложения

Три встроенных skills работают вместе, чтобы запустить ваше приложение и подтвердить изменения в работающем приложении вместо просто тестов:

/run и /verify работают без настройки. Они определяют запуск из типа вашего проекта (CLI, сервер, TUI, управляемый браузером) и из того, что находится в вашем README, package.json или Makefile. Это определение становится ненадежным для проектов, которым нужно что-то большее, чем стандартный запуск: база данных, файл env, графический сеанс, многошаговая сборка.

/run-skill-generator вместо этого записывает рецепт. Он запускает ваше приложение из чистой среды, захватывает то, что сработало (команды установки, переменные env, скрипт запуска), и фиксирует это как skill для каждого проекта в .claude/skills/run-<name>/. После этого /run, /verify и любой другой агент в репозитории следуют записанному рецепту вместо его переоткрытия. Запустите /run-skill-generator один раз на проект, и снова, если процесс сборки или запуска изменится.

/verify также может записать свой собственный рецепт. Когда ему нужно собрать и управлять вашим приложением без записанного рецепта, он записывает то, что сработало, в .claude/skills/verify/SKILL.md в корне репозитория, или в затронутом каталоге пакета в монорепозитории, чтобы более поздние запуски и другие агенты следовали тем же шагам. В корне репозитория записанный скилл заменяет встроенный /verify.

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

Запуск проверок перед каждым коммитом

Когда сессия начинается при наличии skill с именем verify или simplify, инструкции Claude Code по коммитам указывают Claude запускать его непосредственно перед каждым коммитом, за исключением изменений в документации или тестах. Это требует Claude Code v2.1.286 или позже. Claude получает эту инструкцию, когда в начале сессии выполняются следующие условия:

• Расположение: skill загружается из корпоративного, личного, проектного или дополнительного каталога расположения, либо из файла .claude/commands/ с таким именем. Рецепт, который /verify записывает в корне вашего репозитория, является проектным skill, поэтому он учитывается. Встроенные /verify и /simplify, skills плагинов и skills из вашей учетной записи claude.ai не учитываются.
• Вызов: Claude может вызвать skill. Если вы запретили Claude вызывать его, например с помощью disable-model-invocation: true, Claude не получает эту инструкцию.
• Инструкции Git: вы не отключили includeGitInstructions. Его отключение удаляет эту инструкцию вместе с остальными встроенными инструкциями по коммитам и PR.

Работа с проектами Claude API

Встроенный skill /claude-api загружает справочный материал Claude API и Managed Agents для языка вашего проекта. Claude также активирует его автоматически, когда ваш код импортирует anthropic или @anthropic-ai/sdk.

Чтобы запустить один из рабочих процессов skill, введите подкоманду после имени skill в приглашении Claude Code, например /claude-api migrate. Таблица перечисляет, что делает каждая подкоманда, и самую раннюю версию Claude Code, которая её включает. migrate и managed-agents-onboard предшествуют v2.1.221, самой старой версии, которую отслеживает таблица.

Начало работы

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

Этот пример создает skill, который суммирует незафиксированные изменения в вашем git-репозитории и отмечает все рискованные моменты. Он загружает живой diff в подсказку перед тем, как Claude его прочитает, поэтому ответ основан на вашем фактическом рабочем дереве, а не на том, что Claude может предположить из открытых файлов. Claude автоматически загружает skill, когда вы спрашиваете об изменениях, или вы можете вызвать его напрямую с помощью /summarize-changes.

1. Создайте директорию skill

Создайте директорию для skill в папке ваших личных skills. Личные skills доступны во всех ваших проектах.

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

2. Напишите SKILL.md

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

Сохраните это в ~/.claude/skills/summarize-changes/SKILL.md:

---
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.

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

3. Протестируйте skill

Откройте git-проект, внесите небольшое изменение в любой файл и запустите Claude Code, выполнив claude. Вы можете протестировать skill двумя способами.

Позвольте Claude вызвать его автоматически, задав вопрос, который соответствует описанию:

What did I change?

Или вызовите его напрямую с именем skill:

/summarize-changes

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

Выбор места загрузки скиллов

От того, где вы сохраните скилл, зависит, какие сессии его загрузят. Сохраните его в домашнем каталоге, чтобы он был доступен во всех проектах; сделайте коммит в репозиторий, чтобы поделиться им со всеми, кто там работает; или распространите его через плагин или управляемые настройки, чтобы он был доступен всей команде.

Папки скиллов также подчиняются следующим правилам:

• Папки-символические ссылки: запись <skill-name> в корпоративном, личном или проектном расположении может быть символической ссылкой на каталог в другом месте на диске. Claude Code читает SKILL.md из целевого каталога и загружает скилл один раз, даже если на один и тот же целевой каталог указывают несколько расположений. Скиллы плагинов обрабатывают символические ссылки иначе.
• Зарезервированное имя synced: не называйте папку скилла synced ни в каком регистре. Claude Code использует ~/.claude/skills/synced/ для скиллов, загруженных с claude.ai, и пропускает созданный вами скилл с этим именем в корпоративном, личном и проектном расположениях.
• Зарезервированное имя anthropic-skills: вне плагина папка скилла или файл команды с именем anthropic-skills или именем, начинающимся с anthropic-skills:, не загружается. См. Имена, зарезервированные для синхронизированных скиллов.
• Символы в имени: вне плагина папка скилла не загружается, если её имя содержит такой символ, как пробел нулевой ширины или <. См. Символы, которые не может содержать имя скилла.
• Файлы команд: файл Markdown в .claude/commands/ — это более старый формат, который по-прежнему работает. Он поддерживает тот же frontmatter, за исключением name и paths. Чтобы узнать имя, которое нужно ввести для его вызова, см. Как скилл получает имя команды. Для новой работы предпочтительнее скилл, поскольку скиллы также поддерживают вспомогательные файлы.
• Папка скилла как плагин: добавьте .claude-plugin/plugin.json в папку личного или проектного скилла, и Claude Code сможет загрузить её как плагин с именем <name>@skills-dir с собственными агентами, хуками и MCP-серверами. В .claude/skills/ проекта для этого сначала нужно принять диалог доверия к рабочему пространству, а в обоих расположениях также требуется, чтобы ваш администратор не заблокировал плагины из каталогов скиллов.

Загрузка скиллов в монорепозиториях и подкаталогах

Claude Code загружает проектные скиллы из .claude/skills/ в каталоге, в котором вы его запускаете, и в каждом родительском каталоге вплоть до корня репозитория, поэтому при запуске в packages/frontend/ всё равно подхватываются скиллы, определённые в корне. Когда вы перемещаете сессию с помощью /cd в версии v2.1.246 или новее, Claude Code добавляет проектные скиллы нового каталога.

В сессии, работающей в связанном git worktree, который вы создали с помощью --worktree или git worktree add, Claude Code ищет родительские каталоги только до корня worktree. В Claude Code v2.1.277 или новее, если в корне checkout worktree нет каталога .claude/skills, Claude Code вместо этого загружает проектные скиллы основного checkout. См. Что worktree разделяют с основным checkout.

Скиллы в каталоге .claude/skills/ ниже места запуска не загружаются при старте. Они загружаются, когда Claude впервые читает или редактирует файл в этом подкаталоге, и остаются доступными до конца сессии. До этого момента они не отображаются в меню /, и вы не можете вызвать их по имени. Чтобы загрузить их раньше, выполните /add-dir с путём к подкаталогу; для этого требуется Claude Code v2.1.257 или новее. О сессии в worktree, которую вы запускаете из приложения Desktop, см. Что worktree разделяют с основным checkout.

Когда имя каталога вложенного скилла совпадает с именем другого скилла, доступными остаются оба. Если скилл deploy есть в корне репозитория и ещё один — в apps/web/.claude/skills/:

• /deploy запускает корневой скилл. Claude Code также перечисляет для Claude варианты с указанием каталога вместе с инструкцией вызывать тот, в каталоге которого находятся файлы, с которыми он работает, поэтому вложенный скилл по-прежнему применяется к работе в apps/web/.
• /apps/web:deploy запускает только вложенный скилл. В его описании указан каталог, к которому он относится.

Загрузка скиллов из каталога вне проекта

Когда вы добавляете каталог с помощью --add-dir или /add-dir, Claude Code загружает скиллы из .claude/skills/ этого каталога, а также его .claude/commands/ и .claude/agents/. Каталоги, которые Agent SDK добавляет через additionalDirectories в TypeScript или add_dirs в Python, загружаются так же, поскольку SDK передаёт их как --add-dir. Настройка permissions.additionalDirectories в settings.json предоставляет только доступ к файлам и ничего из этого не загружает.

Claude Code отслеживает .claude/skills/ в каталоге, который вы передаёте через --add-dir при запуске, как описано в разделе Редактирование скилла во время сессии. Он не отслеживает .claude/commands/ и .claude/agents/ добавленного каталога, поэтому после изменения файла там перезапустите сессию.

Эта загрузка зависит от источника настроек project, который включён по умолчанию. Политика strictPluginOnlyCustomization, режим bare и --safe-mode дополнительно её ограничивают, как описано на соответствующих страницах. Полную таблицу того, что загружает добавленный каталог, включая CLAUDE.md и настройки плагинов, см. в разделе Дополнительные каталоги предоставляют доступ к файлам, а не конфигурацию.

Запуск одноимённого скилла из добавленного каталога

Скилл добавленного каталога получает префикс, когда имя его папки конфликтует с корпоративным, личным или проектным скиллом либо со скиллом в каталоге, добавленном ранее. Чтобы запустить его, введите /<prefix>:<skill-name> в промпте Claude Code. Меню / показывает скилл под именем с префиксом, а в разделе Как скилл получает имя команды описано, откуда берётся префикс. Для этого имени требуется Claude Code v2.1.309 или новее.

Например, при --add-dir ../cli и скилле verify и в вашем проекте, и в ../cli:

• /verify запускает скилл вашего проекта
• /cli:verify запускает скилл из ../cli

Разрешение конфликтов скиллов с одинаковым именем

Когда у двух скиллов совпадает имя каталога или файла, то, какой из них запустит /name, зависит от их происхождения. Об имени, заданном полем name во frontmatter, см. Как скилл получает имя команды.

Использование скиллов в Cowork и облачных сессиях

Сессии Cowork и облачные сессии, включая облачные запланированные задачи, не читают ~/.claude/skills/ на вашем компьютере. Как интерактивные, так и запланированные сессии Cowork загружают скиллы, включённые для вашего аккаунта claude.ai и синхронизируемые при старте сессии. Управляйте ими через Customize на боковой панели приложения Desktop или в настройках скиллов на claude.ai.

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

• Для сессий Cowork, облачных сессий и облачных тредов в проекте включите скилл для своего аккаунта claude.ai. В облачном треде проекта скиллы, закоммиченные в .claude/skills/ репозитория, недоступны. Некоторые сессии в самостоятельно размещённой среде не загружают скиллы вашего аккаунта.
• Для облачных сессий, отличных от тредов проекта, вы можете вместо этого сделать коммит скилла в .claude/skills/ репозитория. Плагины, объявленные в .claude/settings.json репозитория, и плагины, включённые только в ваших пользовательских настройках, не загружаются в облачных сессиях.

Запланированные задачи Desktop выполняются локально на вашем компьютере, поэтому они загружают ~/.claude/skills/.

Скиллы, синхронизированные с claude.ai

Этот раздел относится к вам, если вы используете Cowork или облачные сессии либо входите в Claude Code в терминале с аккаунтом claude.ai. В таких сессиях Claude Code загружает скиллы, включённые для вашего аккаунта claude.ai, без какой-либо настройки с вашей стороны, как описано в разделе Где загружаются синхронизированные скиллы. К ним относятся скиллы, которые вы создаёте или включаете в настройках claude.ai, скиллы, которые там предоставляет ваша организация, и встроенные скиллы Anthropic, такие как pdf и xlsx.

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

Где загружаются синхронизированные скиллы

В сессии Cowork или облачной сессии Claude Code загружает скиллы, включённые для вашего аккаунта claude.ai, а в разделе Скиллы в Cowork и облачных сессиях описано, как выбрать, какие скиллы получат эти сессии.

В терминале Claude Code синхронизирует эти скиллы в сессиях, где вы входите со своим аккаунтом claude.ai. При старте сессии Claude Code в фоновом режиме скачивает скиллы вашего аккаунта в ~/.claude/skills/synced/, а затем, пока сессия работает, проверяет claude.ai на наличие изменений. Когда проверка обнаруживает, что скилл был добавлен, изменён или отключён на claude.ai, Claude Code добавляет, обновляет или удаляет его в работающей сессии без перезапуска. Для синхронизации в сессиях терминала требуется Claude Code v2.1.273 или новее.

Пока сессия простаивает, проверки выполняются реже:

• Пока вы или Claude работаете в сессии: проверка выполняется примерно каждые 10 минут.
• Пока сессия простаивает: проверка выполняется примерно каждые 40 минут. Когда вы снова начинаете вводить текст в сессии, Claude Code выполняет проверку в течение нескольких минут, если последняя проверка была более 10 минут назад.

Синхронизация никогда не задерживает запуск, поскольку Claude ожидает скачивания скилла только тогда, когда вызывает этот скилл. Поэтому короткий неинтерактивный запуск может завершиться до того, как скачается недавно добавленный скилл; в таком случае его скачает одна из следующих сессий. Чтобы неинтерактивный запуск скачивал ваши скиллы и дожидался списка, прежде чем ответить на промпт, установите CLAUDE_CODE_SYNC_SKILLS в 1. До v2.1.273 сессии терминала скачивали их только при запуске с -p и установленной этой переменной.

Claude Code выполняет синхронизацию только в сессии, в которой выполнен вход с вашим аккаунтом claude.ai и которая получает флаги функций от Anthropic. Синхронизация не выполняется в следующих сессиях:

• Сессия, которая не использует вход, сохранённый через /login, например сессия с аутентификацией по API-ключу или сессия, в которой учётные данные предоставляет ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN или скрипт apiKeyHelper
• Сессия, которая не получает флаги функций, например сессия в Amazon Bedrock или сессия, в которой вы установили CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC
• Сессия в режиме bare или сессия, запущенная с --safe-mode
• Сессия, в которой управляемые настройки вашей организации ограничивают скиллы источниками-плагинами, или сессия, запущенная со списком --setting-sources, в котором нет user

Если вы входите через /login во время сессии, перезапустите Claude Code, чтобы начать синхронизацию.

Скиллы, синхронизированные в предыдущей сессии, остаются на диске. Claude Code загружает их в последующих сессиях с входом в тот же аккаунт, даже если не может связаться с claude.ai.

Claude Code скачивает синхронизированные скиллы и никогда не отправляет их обратно в ваш аккаунт. Если вы или Claude редактируете файл в ~/.claude/skills/synced/, изменение не сохраняется в вашем аккаунте claude.ai, и последующая синхронизация может перезаписать или удалить его. Чтобы изменить синхронизированный скилл, обновите его на claude.ai; следующая синхронизация скачает новую версию.

Чтобы увидеть, какие скиллы синхронизированы, выполните /skills. Меню перечисляет их в разделе claude.ai sync.

Некоторые скиллы Anthropic, такие как pdf и xlsx, синхронизируются всегда. Для остальных включите или отключите скилл в настройках скиллов на claude.ai, чтобы изменить, синхронизируется ли он.

Чтобы остановить синхронизацию на компьютере, установите syncClaudeAiSkills в false в своих пользовательских настройках. Claude Code прекращает скачивание, а при следующем запуске перемещает уже синхронизированные скиллы в ~/.claude/skills/.trash/ и больше их не загружает. Ваша организация может отключить синхронизацию для всех, отключив Skills на claude.ai. Чтобы остановить синхронизацию, оставив Skills включёнными, она может задать тот же ключ в управляемых настройках.

Если ваша организация отключает Skills на claude.ai, Claude Code удаляет скачанные скиллы, и они перестают загружаться. Удалённые скиллы перемещаются в ~/.claude/skills/.trash/, где вы можете восстановить файлы, пока их не удалит очистка по сроку хранения. Как только ваша организация снова включит Skills, Claude Code скачает включённые вами скиллы при следующей синхронизации.

Когда имя синхронизированного скилла совпадает с другой командой

Вы можете вызвать синхронизированный скилл по короткому имени, /<name>, или по полному имени, /anthropic-skills:<name>. Когда короткое имя использует другая команда, /<name> запускает другую команду, а синхронизированный скилл запускается только как /anthropic-skills:<name>. Если есть локальный скилл deploy и синхронизированный deploy, /deploy запускает локальный скилл, а /anthropic-skills:deploy — синхронизированный. До v2.1.269 у синхронизированного скилла было только короткое имя.

В меню /, /skills и /context синхронизированный скилл отображается под своим коротким именем или под полным именем, пока короткое имя использует другая команда. Выполните /skills в своей сессии. Примечание под списком поясняет каждый синхронизированный скилл, потерявший своё короткое имя. Если это имя использует один из ваших личных скиллов или файлов команд в ~/.claude/, в примечании также указано, что переименовать или удалить, чтобы освободить его.

С v2.1.269 по v2.1.280 эти списки показывали каждый синхронизированный скилл под полным именем, а в /skills не было такого примечания; и то и другое изменилось в v2.1.281.

Командой, использующей короткое имя, может быть любая из следующих:

• Встроенная команда или встроенный скилл, включая недоступный в вашей сессии, например после того, как вы отключили встроенные скиллы
• Скилл на любом локальном уровне или файл в .claude/commands/
• Скилл плагина
• MCP-промпт

Claude Code помечает синхронизированные скиллы, чтобы вы могли определить их происхождение. Меню /skills и /context группируют синхронизированные скиллы в разделе claude.ai sync, а меню команд / помечает их как полученные с claude.ai.

При сравнении имён Claude Code игнорирует регистр, пробелы и невидимые символы, а совместимые формы, такие как полноширинные буквы и варианты тире, считает их обычными эквивалентами. Например, синхронизированный скилл с именем Commit и локальный скилл с именем commit считаются одним и тем же именем, поэтому /commit продолжает запускать ваш локальный скилл.

Имя, отличающееся только похожей буквой из другого алфавита, считается другим именем, и различить их можно по метке claude.ai sync. Для этих проверок и меток требуется Claude Code v2.1.228 или новее.

Имена, зарезервированные для синхронизированных скиллов

Claude Code резервирует имя anthropic-skills и все имена внутри этого пространства имён, такие как anthropic-skills:pdf, для скиллов, синхронизированных с claude.ai, поэтому полное имя синхронизированного скилла никогда не запускает ничего другого. Имя зарезервировано в каждой сессии, независимо от того, входите ли вы с аккаунтом claude.ai.

• Папка скилла, name во frontmatter, файл или подпапка в .claude/commands/ или сохранённый workflow: не загружается. Уведомление при запуске указывает первый элемент, который нужно переименовать или изменить.
• Плагин с именем anthropic-skills: загружается. Когда один из его скиллов и синхронизированный скилл оба называются <name>, /anthropic-skills:<name> запускает синхронизированный скилл.
• MCP-сервер с именем anthropic-skills: подключается, и его инструменты работают, но его промпты не отображаются как команды. Переименуйте сервер в конфигурации MCP, чтобы они отображались.

Как Claude Code обрабатывает frontmatter синхронизированного скилла

Claude Code применяет к frontmatter синхронизированного скилла два правила:

• Frontmatter применяется в любой сессии, поэтому разрешение allowed-tools проходит через обычный процесс разрешений. Если ваша организация устанавливает allowManagedPermissionRulesOnly, разрешение не применяется.
• Claude Code очищает отображаемый текст, предоставляемый скиллом, например его описание. Он удаляет управляющие символы, а в тексте, который попадает к Claude, например в описании, также экранирует угловые скобки, чтобы текст не мог имитировать внутреннее форматирование Claude Code. Для этой очистки требуется Claude Code v2.1.228 или новее.

Как Claude Code обрабатывает тело синхронизированного скилла

То, что Claude Code делает с телом синхронизированного скилла, зависит от того, где выполняется сессия:

• В облачной сессии тело ведёт себя так же, как у локального скилла, поскольку сессия выполняется в изолированном контейнере.
• В сессии Cowork на вашем компьютере тело ведёт себя так же, как у локального скилла, за исключением того, что Claude Code заменяет каждую строку команды ! на заполнитель disableSkillShellExecution, как он делает для каждого скилла, который вы там предоставляете.
• В любой другой сессии на вашем компьютере Claude Code не выполняет команды !, не прикрепляет файлы, указанные в ссылках @, как он делает для локального скилла, и не подставляет заполнители ${CLAUDE_PROJECT_DIR} и ${CLAUDE_SESSION_ID}, поэтому ссылки @ и оба заполнителя попадают к Claude как буквальный текст. Строка команды ! также попадает к Claude как буквальный текст или как тот заполнитель, когда включён disableSkillShellExecution. Для такой обработки требуется Claude Code v2.1.228 или новее.

Редактирование скилла во время сессии

Claude Code отслеживает изменения файлов в каталогах скиллов, за исключением режима bare. Когда вы добавляете, редактируете или удаляете скилл в ~/.claude/skills/, в .claude/skills/ проекта или в .claude/skills/ внутри каталога --add-dir, Claude Code подхватывает изменение в текущей сессии без перезапуска.

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

Отслеживание изменений в реальном времени охватывает только текст SKILL.md. Для папки скилла, которая также является плагином, изменения в hooks/, .mcp.json, agents/ и output-styles/ вступают в силу только после /reload-plugins.

Удаление скилла

Способ удаления скилла зависит от его происхождения:

• Личный или проектный скилл: удалите каталог скилла, ~/.claude/skills/<skill-name>/ или .claude/skills/<skill-name>/. Claude Code убирает его из /skills в текущей сессии; содержимое, которое Claude Code уже загрузил из него, подчиняется жизненному циклу содержимого скилла.
• Корпоративный скилл: администратор удаляет каталог скилла из .claude/skills/ внутри каталога управляемых настроек, например /etc/claude-code/.claude/skills/<skill-name>/ в Linux.
• Скилл плагина: отключите или удалите плагин, который его предоставляет, через меню /plugin или с помощью /plugin uninstall <plugin-name>@<marketplace-name>. Claude Code выгружает скиллы плагина, когда изменение применяется, или при перезапуске.
• Скилл, синхронизированный с claude.ai: отключите скилл для своего аккаунта claude.ai там же, где вы его включили. Claude Code удалит его из ~/.claude/skills/synced/ при следующей синхронизации ваших скиллов. Если вместо этого вы удалите каталог вручную, следующая синхронизация скачает его снова, пока скилл остаётся включённым на claude.ai.
• Встроенный скилл: установите disableBundledSkills в true, чтобы отключить встроенные скиллы, или установите для одного скилла значение "off" в skillOverrides, чтобы скрыть его.

Чтобы сохранить личный или проектный скилл, но запретить Claude вызывать его самостоятельно, установите disable-model-invocation: true в его frontmatter или "user-invocable-only" в skillOverrides, если не хотите редактировать файл.

Настройка скиллов

Скиллы настраиваются с помощью YAML frontmatter в начале SKILL.md и следующего за ним markdown-содержимого.

Типы содержимого скилла

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

Справочное содержимое добавляет знания, которые Claude применяет к вашей текущей работе: соглашения, паттерны, руководства по стилю, знания предметной области. Это содержимое встраивается напрямую, поэтому Claude может использовать его вместе с контекстом вашего диалога.

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

Содержимое задачи даёт Claude пошаговые инструкции для конкретного действия, например развёртывания, коммитов или генерации кода. Часто это действия, которые вы хотите вызывать напрямую через /skill-name, а не позволять Claude решать, когда их запускать. Добавьте disable-model-invocation: true, чтобы Claude не мог запускать скилл автоматически. В примере ниже добавлено context: fork, благодаря чему скилл выполняется в собственном контексте субагента; см. Запуск скиллов в субагенте.

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

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

Делайте само тело скилла лаконичным. После загрузки скилла его содержимое остаётся в контексте на протяжении последующих ходов, поэтому каждая строка — это постоянный расход токенов. Указывайте, что делать, а не рассказывайте, как или почему, и применяйте ту же проверку на лаконичность, что и для содержимого CLAUDE.md.

Справочник по frontmatter

Настройте скилл с помощью YAML frontmatter между маркерами --- в начале SKILL.md, а инструкции скилла напишите в формате Markdown после закрывающего ---. Имена полей состоят из слов в нижнем регистре, разделённых дефисами, за исключением when_to_use. Файл команды в .claude/commands/ принимает те же поля, кроме name и paths. В этом примере задано четыре поля:

---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---

Your skill instructions here...

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

Claude Code читает frontmatter, только если открывающий --- находится в первой строке файла. В противном случае весь файл, включая маркеры ---, рассматривается как содержимое скилла. Если YAML между маркерами не удаётся разобрать, скилл всё равно загружается, но без заданных полей; чтобы найти и исправить ошибку, см. Скилл не срабатывает.

Использование frontmatter скилла вне Claude Code

Claude Code принимает все поля из таблицы выше. Вне Claude Code можно использовать только поля из спецификации Agent Skills:

Когда вы включаете личный скилл для своей учётной записи claude.ai, например чтобы использовать его в Cowork и облачных сессиях и запланированных задачах, вы загружаете его в claude.ai. К такой загрузке применяются те же правила.

Если вы включите любое поле, не разрешённое спецификацией, упаковка или загрузка завершится с ошибкой, а не проигнорирует это поле:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Если ограничить frontmatter шестью полями спецификации, приведённой выше ошибки о неожиданном ключе не возникнет. Всё остальное, что проверяется при этих способах, определяют спецификация Agent Skills и требования Skills API. Возможности тела скилла, доступные только в Claude Code, например внедрение динамического контекста, не работают в чате claude.ai и через API. Claude Code принимает все шесть полей, поэтому frontmatter, соответствующий спецификации, загружается в Claude Code без изменений.

Как скилл получает имя команды

Команда, которую вы вводите для вызова скилла, определяется расположением файла скилла, а для каталогов скиллов и скиллов плагинов — ещё и полем name во frontmatter. В личном или проектном каталоге скиллов name задаёт команду, которую показывает меню / и которую вы вводите, если только это имя уже не занято другой командой. Имя каталога тоже вызывает скилл. В скилле плагина name задаёт последний сегмент команды, а префикс плагина остаётся на месте.

В таблице ниже показано, откуда берётся имя команды для каждого варианта расположения:

В скилле плагина name из frontmatter заменяет имя каталога в последнем сегменте команды, поэтому my-plugin/skills/review/SKILL.md с name: fancy становится /my-plugin:fancy. Простое /fancy тоже вызывает скилл, если только это имя уже не занято другой командой. Если указанное вами name уже начинается с собственного префикса плагина, Claude Code в v2.1.246 и новее не добавляет префикс повторно. Например, name: my-plugin:fancy по-прежнему становится /my-plugin:fancy. В версиях с v2.1.216 по v2.1.245 Claude Code удваивал префикс, если name уже его содержало.

В неинтерактивных сессиях имена help и feedback не зарезервированы за соответствующими встроенными командами, доступными только в терминале, поэтому скилл плагина с одним из этих имён сохраняет там свою простую команду. Имена всех остальных встроенных команд, доступных только в терминале, например /login, остаются зарезервированными, хотя сами команды в таких сессиях выполнить нельзя.

Для SKILL.md в корне плагина нет каталога скилла, из которого можно взять имя, поэтому name задаёт весь последний сегмент. Без поля name Claude Code использует имя каталога плагина как резервный вариант.

Символы, которые не может содержать имя скилла

Если скилл или пользовательская команда отсутствует в меню / или меню не показывает name скилла из frontmatter, проверьте имя. Claude Code отклоняет имя команды или name из frontmatter, содержащее, например, такие символы:

• Пробел нулевой ширины или управляющий символ
• Символ из области частного использования или неназначенный символ, например глиф из иконочного шрифта
• Символ, меняющий направление окружающего его текста
• Любой пробельный символ, кроме одного обычного пробела между словами, например неразрывный пробел, два пробела подряд или пробел в начале или в конце
• < или >

Пользовательская команда или скилл не загружается, если Claude Code отклоняет имя его каталога или файла. Переименуйте эту папку или файл, удалив эти символы. Скилл всё же загружается, если такие символы есть только в имени папки скилла плагина или в его name из frontmatter:

• Папка в каталоге skills/ плагина или в путях skills его манифеста: переименовывать папку не нужно. Эти символы превращаются в дефисы в имени команды скилла, поэтому вводите команду с дефисами.
• name из frontmatter: меню / не показывает значение name, и его ввод не вызывает скилл. Отредактируйте строку name:, удалив эти символы.

Чтобы узнать, какое имя отклонил Claude Code, запустите его из оболочки с помощью claude --debug и найдите в отладочном логе [names]. В интерактивной сессии о том, что имена были отклонены, также сообщает уведомление при запуске. После переименования или правки name: перезапустите сессию, если только файл не находится в каталоге, который Claude Code отслеживает на предмет изменений.

Доступные строковые подстановки

Скиллы поддерживают строковую подстановку динамических значений в содержимом скилла:

Claude Code подставляет ${CLAUDE_SKILL_DIR} и ${CLAUDE_PROJECT_DIR} в двух местах: в markdown-содержимом скилла и в правилах Bash в поле allowed-tools frontmatter. В скилле плагина Claude Code подставляет ${CLAUDE_PLUGIN_ROOT} и ${CLAUDE_PLUGIN_DATA} в тех же двух местах. Использование одной и той же переменной в обоих местах позволяет скиллу запускать поставляемый с ним скрипт без запроса разрешения. Следующий скилл демонстрирует этот паттерн:

---
name: render-chart
description: Render a chart from a CSV file
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

Если этот скилл установлен в ~/.claude/skills/render-chart/, оба вхождения ${CLAUDE_SKILL_DIR} раскрываются в этот каталог. Тогда правило allowed-tools совпадает в точности с командой, которую тело скилла велит Claude выполнить, и скрипт запускается без запроса.

Индексированные аргументы используют кавычки в стиле оболочки, поэтому заключайте значения из нескольких слов в кавычки, чтобы передать их как один аргумент. Например, /my-skill "hello world" second приводит к тому, что $0 раскрывается в hello world, а $1 — в second. Плейсхолдер $ARGUMENTS всегда раскрывается в полную строку аргументов в том виде, в каком она введена.

Индексированный плейсхолдер без соответствующего аргумента, например $2, когда передан только один аргумент, остаётся в содержимом без изменений. Именованный плейсхолдер из arguments во frontmatter без соответствующего аргумента раскрывается в пустую строку.

Если вы передаёте значение аргумента, которое само содержит текст вроде $1 или $ARGUMENTS, Claude Code вставляет его как буквальный текст и не раскрывает. Например, если тело скилла содержит Summarize $0, а вы выполняете /summarize "$ARGUMENTS from yesterday", Claude получает Summarize $ARGUMENTS from yesterday. Переменные ${CLAUDE_*}, например ${CLAUDE_SKILL_DIR}, Claude Code по-прежнему заменяет после вставки аргументов.

Чтобы вставить буквальный $ перед цифрой, ARGUMENTS или объявленным именем аргумента, например $1.00 в тексте, экранируйте его обратной косой чертой: \$1.00. Обратная косая черта перед любым другим $ остаётся без изменений. Экранирует токен только одна обратная косая черта непосредственно перед ним. Двойная обратная косая черта, например \\$1, оставляет обе обратные косые черты на месте, и $1 по-прежнему раскрывается в значение аргумента. Экранирование обратной косой чертой распространяется только на эти плейсхолдеры аргументов. Обратная косая черта не предотвращает подстановку переменной ${CLAUDE_*} там, где эта переменная применяется.

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

---
name: session-logger
description: Log activity for this session
---

Log the following to logs/${CLAUDE_SESSION_ID}.log:

$ARGUMENTS

Добавление вспомогательных файлов

Скиллы могут включать несколько файлов в своём каталоге. Это позволяет сосредоточить в SKILL.md самое важное, давая Claude доступ к подробным справочным материалам только при необходимости. Большие справочные документы, спецификации API или коллекции примеров не нужно загружать в контекст при каждом запуске скилла.

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](/anthropic/claude-code/history/docs/ru/2026-11-08-2258..2026-11-09-2302/reference/)
- For usage examples, see [examples.md](/anthropic/claude-code/history/docs/ru/2026-11-08-2258..2026-11-09-2302/examples/)

[!TIP]

Держите SKILL.md в пределах 500 строк. Переносите подробные справочные материалы в отдельные файлы.

Управление тем, кто вызывает скилл

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

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

• user-invocable: false: вызвать скилл может только Claude. Используйте для фоновых знаний, которые не имеют смысла как команда. Скилл legacy-system-context объясняет, как работает старая система. Claude должен знать это, когда это актуально, но /legacy-system-context не является осмысленным действием для пользователей.

В этом примере создаётся скилл развёртывания. Если задать disable-model-invocation: true, Claude не сможет запустить скилл автоматически:

---
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 самостоятельно.

Вот как эти два поля влияют на вызов и загрузку в контекст:

[!NOTE]

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

Где писать имя скилла

Чтобы запустить скилл напрямую, поставьте его имя в начало сообщения. После обычного текста имя даёт Claude разрешение запустить скилл, но не запускает его:

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

Жизненный цикл содержимого скилла

Когда вы или Claude вызываете скилл, отрисованное содержимое SKILL.md попадает в диалог как одно сообщение и остаётся там на протяжении последующих ходов. Это сохранение распространяется на инструкции скилла, но не на его разрешения: разрешение allowed-tools сбрасывается, когда вы отправляете следующее сообщение. Claude Code не перечитывает файл скилла на последующих ходах, поэтому указания, которые должны действовать на протяжении всей задачи, пишите как постоянные инструкции, а не как одноразовые шаги.

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

Автосжатие переносит вызванные скиллы дальше в пределах бюджета токенов. Когда диалог суммируется для освобождения контекста, Claude Code повторно прикрепляет после сводки последний вызов каждого скилла, сохраняя первые 5 000 токенов каждого. Повторно прикреплённые скиллы делят общий бюджет в 25 000 токенов. Claude Code заполняет этот бюджет, начиная с последнего вызванного скилла, поэтому если вы вызвали много скиллов в одной сессии, более старые могут быть полностью отброшены после сжатия контекста.

Если Claude перестаёт следовать скиллу посреди сессии, см. Claude перестаёт следовать скиллу.

Предварительное разрешение инструментов для скилла

Поле allowed-tools предоставляет разрешение на использование перечисленных инструментов в течение хода, в котором вызван скилл, поэтому Claude может использовать их, не запрашивая у вас подтверждения. Разрешение сбрасывается, когда вы отправляете следующее сообщение, хотя содержимое скилла остаётся в контексте; повторный вызов скилла снова применяет его для этого хода. Поле не ограничивает набор доступных инструментов: все инструменты остаются доступными для вызова, а инструменты, не указанные в списке, по-прежнему регулируются вашими настройками разрешений. Чтобы предварительно разрешить инструменты на всю сессию, а не на один ход, добавьте вместо этого правила разрешения в эти настройки разрешений.

Доверие к рабочему пространству не влияет на это поле. Claude Code применяет allowed-tools проектного скилла даже при запуске с -p в папке, которой вы никогда не доверяли. Скилл может предоставить себе широкий доступ к инструментам, поэтому проверяйте allowed-tools скиллов, добавленных в репозиторий, прежде чем запускать там Claude Code. Чтобы во всей организации это поле не применялось к скиллам из репозиториев, см. Когда применяются только управляемые правила разрешений.

Этот скилл позволяет Claude выполнять команды git без подтверждения каждого использования всякий раз, когда вы его вызываете:

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Чтобы удалить инструменты из доступного Claude набора, пока скилл активен, перечислите их в disallowed-tools во frontmatter скилла. Ограничение снимается, когда вы отправляете следующее сообщение. Как и правила запрета, это поле не может удалить EndConversation, пока остаётся хотя бы один другой инструмент. Чтобы заблокировать инструменты для всех скиллов и промптов, добавьте правила запрета в свои настройки разрешений.

Когда управляемые настройки ограничивают хуки плагинами

Когда управляемые настройки вашей организации указывают hooks в strictPluginOnlyCustomization, личный или проектный скилл, frontmatter которого объявляет hooks, теряет предварительное разрешение allowed-tools, за исключением скиллов, которые его сохраняют.

• Проверка: введите /status в сессии Claude Code. Если /status показывает Enterprise managed settings, спросите у администратора, указан ли hooks в strictPluginOnlyCustomization.
• Исправление: удалите hooks из frontmatter скилла, поскольку при этой настройке его хуки не выполняются. Чтобы сохранить их, перенесите скилл в плагин, который вы устанавливаете из маркетплейса.

Когда применяются только управляемые правила разрешений

Когда ваша организация задаёт allowManagedPermissionRulesOnly в управляемых настройках, Claude Code игнорирует allowed-tools в проектных и личных скиллах, а также в других источниках, перечисленных в описании этой настройки. Для этого требуется Claude Code v2.1.282 или новее.

Вместо этого инструменты, перечисленные в затронутом скилле, проходят через управляемые правила вашей организации и обычный запрос разрешения. Выполните /status, чтобы увидеть список всех скиллов, чьи allowed-tools Claude Code к этому моменту проигнорировал в сессии. Внедрённая в скилл команда, которую не разрешает ни одно управляемое правило, обрабатывается согласно разделу Проверки разрешений для внедрённых команд.

Передача аргументов скиллам

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

Этот скилл исправляет GitHub issue по номеру. Плейсхолдер $ARGUMENTS заменяется тем, что следует за именем скилла:

---
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...»

Если вы вызываете скилл с аргументами, но ни один плейсхолдер в содержимом скилла их не получает, Claude Code добавляет ARGUMENTS: <your input> в конец содержимого скилла, чтобы Claude всё равно увидел, что вы ввели. Плейсхолдер — это $ARGUMENTS, индексированная форма, например $1, или именованный аргумент. Индексированный плейсхолдер, для позиции которого нет аргумента, остаётся буквальным текстом и не считается получившим аргумент. Именованный плейсхолдер считается получившим аргумент, даже если для его позиции аргумента нет, поскольку он раскрывается в пустую строку.

Чтобы обратиться к отдельным аргументам по позиции, используйте $ARGUMENTS[N] или более короткое $N:

---
name: migrate-component
description: Migrate a component from one language to another
---

Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].
Preserve all existing behavior and tests.

Выполнение /migrate-component SearchBar JavaScript TypeScript заменяет $ARGUMENTS[0] на SearchBar, $ARGUMENTS[1] на JavaScript, а $ARGUMENTS[2] на TypeScript. Тот же скилл с сокращением $N:

---
name: migrate-component
description: Migrate a component from one language to another
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

Объединение нескольких скиллов в одном сообщении

Когда вы вводите текст в промпт Claude Code в терминале, вы можете поставить несколько скиллов подряд в начале одного сообщения. Через Agent SDK или claude -p Claude Code загружает только первый скилл, а остаток строки использует как его аргументы. В промпте терминала ввод /write-tests /fix-issue 123 загружает оба скилла и передаёт завершающий текст 123 каждому из них как $ARGUMENTS.

Claude Code раскрывает первый скилл и до пяти следующих за ним. Раскрытие останавливается на первом токене, который не является скиллом, вызываемым пользователем и выполняемым в текущем диалоге. Если вы добавите скилл, который выполняется как ответвлённый субагент, например /code-review, или скилл, аргументы которого могут начинаться с другой команды, например /loop, раскрытие на нём заканчивается. Этот токен и всё, что следует за ним, становятся текстом аргументов для каждого раскрытого скилла.

Продвинутые приёмы

Внедрение динамического контекста

Синтаксис !`<command>` выполняет shell-команды до того, как содержимое скилла будет отправлено Claude. Вывод команды заменяет заполнитель, поэтому Claude получает реальные данные, а не саму команду. Claude Code не выполняет эти команды на вашем компьютере, если скилл синхронизирован из вашей учётной записи claude.ai. Это ограничение требует Claude Code v2.1.228 или новее.

Этот скилл кратко описывает pull request, получая актуальные данные PR с помощью GitHub CLI. Команда !`gh pr diff` и другие команды выполняются первыми, и их вывод вставляется в промпт:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

Подстановка выполняется один раз по исходному файлу. Вывод команды вставляется как обычный текст и повторно не сканируется на наличие других заполнителей !`<command>`, поэтому команда не может вывести заполнитель, который раскрылся бы при последующем проходе.

Встроенная форма распознаётся, только если ! стоит в начале строки или сразу после пробельного символа. Если ! следует за другим символом, как в KEY=!`cmd`, заполнитель остаётся буквальным текстом, и команда не выполняется.

Для многострочных команд используйте вместо встроенной формы блок кода, открытый с помощью ```!:

## Environment
```!
node --version
git status --short
```

Чтобы отключить это поведение для скиллов и пользовательских команд из пользовательских, проектных, плагинных источников или источников дополнительных каталогов, задайте "disableSkillShellExecution": true в настройках. Вместо выполнения каждая команда заменяется на [shell command execution disabled by policy]. На встроенные и управляемые скиллы это не влияет. Эта настройка наиболее полезна в управляемых настройках, где пользователи не могут её переопределить.

Claude Code никогда не выполняет эти команды на вашем компьютере, если они встречаются в скиллах, синхронизированных из вашей учётной записи claude.ai, независимо от этой настройки. Это ограничение требует Claude Code v2.1.228 или новее. В разделе Как Claude Code обрабатывает тело синхронизированного скилла описано, что Claude получает вместо команды в каждом типе сессии.

[!TIP]

Чтобы запросить более глубокие рассуждения при запуске скилла, включите ultrathink в любом месте содержимого скилла. См. Использование ultrathink для разового глубокого рассуждения.

Как выполняются внедрённые команды

Claude Code выбирает инструмент для выполнения внедрённых команд скилла на основе ключа shell во frontmatter скилла и вашего окружения. При любой комбинации команды выполняются через инструмент Bash или инструмент PowerShell, кроме одной, при которой вызов сразу завершается ошибкой:

• shell: powershell при включённом инструменте PowerShell: команды выполняются через инструмент PowerShell.
• shell: bash, когда bash недоступен: вызов завершается ошибкой до выполнения какой-либо команды. Так происходит в Windows без Git Bash. Claude Code показывает Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found.
• Любая другая комбинация: команды выполняются через инструмент Bash, если bash доступен. Если нет — через инструмент PowerShell.

Любой из инструментов выполняет команды так же, как собственные shell-команды Claude. У них общий рабочий каталог, таймаут и обработка вывода:

• Рабочий каталог: Claude Code выполняет каждую команду в текущем рабочем каталоге оболочки сессии. Этот каталог меняется, когда Claude выполняет cd. Используйте ${CLAUDE_SKILL_DIR} или ${CLAUDE_PROJECT_DIR} в путях, которые должны каждый раз разрешаться одинаково.
• stderr: при оболочке bash по умолчанию Claude Code объединяет stderr со stdout. Всё, что команда пишет в stderr, появляется во внедрённом тексте.
• Таймаут: каждая команда выполняется с таймаутом инструмента Bash по умолчанию — 2 минуты. Когда инструмент Bash переводит команду с истёкшим таймаутом в фон, скилл всё равно отображается. Внедрённый текст сообщает о переводе в фон и называет фоновую задачу и файл, в который собирается вывод команды. Если это команда, которую инструмент Bash никогда не переводит в фон автоматически, Claude Code завершает её по таймауту. Такой сбой прерывает вызов.
• Размер вывода: вывод, превышающий встроенный предел инструмента Bash, поступает в виде пути к файлу и короткого предпросмотра, а не усечённого текста. В разделе Ограничения вывода описан этот предел и то, как настроить каждую границу.

Инструмент PowerShell применяет то же поведение таймаута, перевода в фон и предела вывода к выполняемым им командам. Подробности см. в разделе Инструмент PowerShell.

Когда внедрённая команда завершается ошибкой

Неудачная команда прерывает весь вызов скилла, а не только собственный заполнитель. Claude так и не видит содержимое скилла для этого вызова. При прерывании отображается Shell command failed for pattern "...". Сообщение об ошибке включает вывод команды.

При оболочке bash по умолчанию любой ненулевой код выхода считается ошибкой. Есть одно исключение: Claude Code считает код выхода 1 от команд поиска и сравнения обычным результатом и внедряет их вывод. Коды выхода 2 и выше приводят к ошибке даже для этих команд.

На какие команды распространяется исключение, зависит от оболочки:

• Оболочка bash по умолчанию: команды, перечисленные в разделе Ограничения вывода
• shell: powershell при включённом инструменте PowerShell: другой набор, который включает grep и git diff, но не find или diff

При оболочке bash по умолчанию добавляйте || true к любой другой команде, которая, как вы ожидаете, завершится с ненулевым кодом. Пример — скрипт проверки, который завершается с кодом 1, если находит проблемы.

Когда ни одна shell-команда не была выполнена

No shell command in <name> was run означает, что одна из его shell-команд содержит символ, который инструмент не принимает. Чтобы найти и удалить этот символ, см. справочник по ошибкам.

Проверка разрешений для внедрённых команд

Внедрённые команды никогда не запрашивают разрешение во время отображения скилла. Claude Code сначала проверяет каждую из них по вашим правилам разрешений. Команда, соответствующая правилу запрета, прерывает вызов с ошибкой Shell command permission check failed for pattern "...".

Вне авторежима, если проверка разрешений команды возвращает что-либо, кроме разрешения, Claude Code прерывает вызов с той же ошибкой. Это относится и к правилу, которое обычно запросило бы подтверждение у вас. Чтобы несовпадающая команда не прерывала вызов, заранее разрешите её с помощью allowed-tools. Если ваша организация ограничивает правила разрешений управляемыми настройками, см. Когда применяются только управляемые правила разрешений. Правила запрета и запроса по-прежнему имеют приоритет над allowed-tools. См. Управление разрешениями.

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

Запуск скиллов в субагенте

Добавьте context: fork во frontmatter, если хотите, чтобы скилл выполнялся изолированно. Claude Code запускает новый субагент типа, заданного в поле agent, и передаёт ему содержимое скилла в качестве промпта. Субагент не видит историю вашего диалога, поэтому инструкции скилла должны быть самодостаточными.

[!NOTE]

Несмотря на название, скилл с context: fork не выполняется в ответвлении текущего диалога, которое передало бы субагенту всё, что вы успели обсудить. Если задача зависит от этой истории, ответвите диалог вместо использования context: fork.

Ответвлённый субагент выполняется в фоне: вы продолжаете работать, пока он выполняется, а его результат появляется в вашем диалоге по завершении. Задайте background: false во frontmatter, чтобы вместо этого ждать результата в том ходе, который вызвал скилл.

Claude Code также ждёт результата, даже если скилл не задаёт background: false, в таких случаях:

• В неинтерактивном режиме, с флагом -p или в Agent SDK
• Когда вы задаёте CLAUDE_CODE_DISABLE_BACKGROUND_TASKS равным 1, что также отключает другие функции фоновых задач
• Когда вы вызываете ответвлённый скилл, пока предыдущий вызов того же скилла ещё выполняется
• Когда срабатывает запланированная задача уровня сессии со скиллом в качестве промпта

Когда агент в динамическом рабочем процессе вызывает ответвлённый скилл, этот агент ждёт результата и получает его, даже если скилл не задаёт background: false. До v2.1.295, если скилл выполнялся в фоне, этот агент его не ждал. Результат скилла тогда появлялся в вашем основном диалоге, а не доходил до агента.

Ответвление, выполняемое в фоне, также работает с более узким набором инструментов, который применяется к фоновым субагентам: субагент скилла — это обычный тип агента, поэтому на него не распространяется исключение для субагентов, ответвляющих диалог. Если шаги вашего скилла зависят от инструмента вне этого набора, задайте background: false, чтобы сохранить полный набор инструментов.

Ответвлённый скилл, выполняемый в фоне, применяет свои правки вне чекпоинтов вашей сессии. После его выполнения /rewind восстанавливает только те файлы, которые Claude уже редактировал в вашем диалоге. Правки скилла в других файлах остаются, поэтому для их отката используйте git.

[!WARNING]

context: fork имеет смысл только для скиллов с явными инструкциями. Если ваш скилл содержит рекомендации вроде «используйте эти соглашения API» без задачи, субагент получает рекомендации, но не получает промпта, на основе которого можно действовать, и возвращается без значимого результата.

Скиллы и субагенты взаимодействуют в двух направлениях:

С context: fork вы пишете задачу в скилле и выбираете тип агента для её выполнения. Встроенные агенты Explore и Plan запускаются без CLAUDE.md и git status, чтобы их контекст оставался небольшим. Поместите в SKILL.md всё, что нужно для задачи. Ответвлённый скилл с agent: Explore начинает работу с этим содержимым и собственным системным промптом агента, без каких-либо ваших файлов CLAUDE.md.

Для обратного случая, когда вы определяете пользовательский субагент, использующий скиллы как справочный материал, см. Субагенты.

Пример: исследовательский скилл с агентом Explore

Этот скилл выполняет исследование в ответвлённом агенте Explore. Содержимое скилла становится задачей, а агент предоставляет инструменты только для чтения, оптимизированные для изучения кодовой базы:

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

Когда этот скилл запускается:

1. Создаётся новый изолированный контекст
2. Субагент получает содержимое скилла в качестве промпта (инструкции «Research $ARGUMENTS thoroughly»)
3. Поле agent определяет среду выполнения (модель, инструменты и разрешения)
4. Субагент обобщает свои результаты и возвращает их в ваш основной диалог по завершении

Поле agent указывает, какую конфигурацию субагента использовать. Варианты включают встроенных агентов (Explore, Plan, general-purpose) или любой пользовательский субагент из .claude/agents/. Если поле не указано, используется general-purpose.

Ограничение доступа Claude к скиллам

По умолчанию Claude может вызывать любой скилл, у которого не задано disable-model-invocation: true. Скиллы, определяющие allowed-tools, предоставляют Claude доступ к этим инструментам без подтверждения каждого использования в течение хода, вызвавшего скилл; это разрешение снимается, когда вы отправляете следующее сообщение. Ваши настройки разрешений по-прежнему определяют базовое поведение подтверждения для всех остальных инструментов. Несколько встроенных команд также доступны через инструмент Skill, включая /init и /security-review. Другие встроенные команды, такие как /compact, — нет.

Три способа управлять тем, какие скиллы может вызывать Claude:

Отключите все скиллы, запретив инструмент Skill в /permissions:

# Add to deny rules:
Skill

Разрешите или запретите конкретные скиллы с помощью правил разрешений:

# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)

Синтаксис разрешений: Skill(name) для точного совпадения, Skill(name *) для совпадения по префиксу с любыми аргументами.

В таблице показано, что блокирует правило deny помимо указанного вами имени, в зависимости от вида имени в правиле.

До v2.1.260 Claude Code не блокировал вложенный скилл, указанный под квалифицированным именем, если правило запрета называло только неквалифицированное имя.

Claude Code сопоставляет правило allow только с собственным именем скилла и именем в вызове Claude. Чтобы разрешить синхронизированный скилл без запроса, укажите его внутри его зарезервированного пространства имён:

• Skill(anthropic-skills:pdf) разрешает синхронизированный скилл pdf
• Skill(anthropic-skills *) разрешает все синхронизированные скиллы
• Skill(anthropic *) не охватывает anthropic-skills:pdf, потому что префикс вне пространства имён не совпадает с именами внутри него

Скройте отдельные скиллы, добавив disable-model-invocation: true в их frontmatter. Это полностью удаляет скилл из контекста Claude.

[!NOTE]

С user-invocable: false вы не можете вызвать скилл, но Claude по-прежнему может. Чтобы Claude не вызывал его через инструмент Skill, задайте disable-model-invocation: true.

Переопределение видимости скиллов из настроек

Настройка skillOverrides управляет видимостью скиллов из ваших настроек, а не из frontmatter самого скилла. Используйте её для скиллов, SKILL.md которых вы не хотите редактировать, например для тех, что хранятся в общем репозитории проекта. Меню /skills записывает её за вас: выделите скилл и нажимайте Space для переключения состояний, затем Esc, чтобы сохранить в .claude/settings.local.json.

Каждый ключ — это имя скилла, а каждое значение — одно из четырёх состояний:

В меню /skills состояние "user-invocable-only" обозначено как user-only.

"off" также скрывает скилл из списков команд, предоставляемых клиентам Remote Control и вызывающим сторонам Agent SDK, помимо меню / в терминале. Вызов скрытого скилла по его полному имени возвращает ошибку skillOverrides вместо его выполнения.

Скилл, отсутствующий в skillOverrides, считается "on". В примере ниже один скилл сворачивается до имени, а другой полностью отключается:

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

У некоторых встроенных скиллов есть псевдонимы, например checkup для /doctor. Если вы задаёте запись skillOverrides под псевдонимом в управляемых настройках или в файле, передаваемом с флагом --settings, Claude Code применяет её к скиллу, стоящему за псевдонимом. Через псевдоним скилл можно только дополнительно ограничить, но никогда не сделать более видимым, а если вы также задаёте запись под собственным именем скилла в управляемых настройках, эта запись имеет приоритет. До v2.1.260 Claude Code ни в одном источнике настроек не применял запись под псевдонимом к скиллу.

В пользовательских, проектных и локальных настройках Claude Code сопоставляет записи только с именами скиллов. Если вы задаёте там запись для review, она применяется к скиллу с именем review, а не к встроенному /code-review через его псевдоним /review.

skillOverrides не влияет на скиллы плагинов. Управляйте ими через /plugin.

Поиск неиспользуемых скиллов

Каждый скилл в списке скиллов увеличивает ваш контекст на каждом ходе, независимо от того, использует ли его Claude. Выполните /skill-doctor, чтобы увидеть, во что обходится каждый из ваших скиллов и как часто он используется, и решить, какие из них отключить. В интерактивной сессии отчёт открывается на вкладке Stats менеджера /plugin. В неинтерактивном режиме с -p Claude Code выводит его как текст.

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

/skill-doctor требует Claude Code v2.1.252 или новее и недоступен в сессиях, пропускающих получение флагов функций. Если вы выполняете /skill-doctor через Remote Control с телефона или в браузере, Claude Code вместо этого отвечает Skill usage reports are not available on this connection.. Выполняйте /skill-doctor в терминале на компьютере, где запущена сессия.

Оценка и итерация навыка

Видение срабатывания навыка говорит вам, что Claude его нашел, но не то, что он сделал то, что вы намеревались. Чтобы узнать, работает ли навык, измерьте две вещи отдельно: вызывает ли Claude его на подсказках, которые он должен, и соответствует ли результат тому, что вы ожидаете, когда он это делает.

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

Способ отключения навыка для второго запуска зависит от того, откуда он поступает:

• Личный или проектный навык: установите его на "off" в skillOverrides.
• Навык, который предоставляет плагин: skillOverrides не применяется к навыкам плагина. Используйте claude plugin eval вместо этого, который повторяет каждый запуск без загруженного плагина.

Два инструмента автоматизируют сравнение базовых показателей. Для навыка, который поставляется в плагине, claude plugin eval запускает каждую подсказку в изолированном сеансе с плагином и без него, оценивает его с помощью оценщиков, которые вы определяете или которые он пишет для вас, и выходит с ненулевым кодом ниже порога, чтобы вы могли заблокировать CI на нем. Для итерации над одним навыком внутри разговора Claude Code плагин skill-creator ниже запускает аналогичный цикл с собственным форматом evals/evals.json. Эти два формата не взаимозаменяемы.

Запуск оценок с skill-creator

Плагин skill-creator автоматизирует цикл сравнения внутри Claude Code. В расширении VS Code или десктопном приложении установите его из официального маркетплейса, следуя инструкциям в разделе Установка плагина. В терминале запустите Claude Code командой claude, затем введите в его строке ввода следующее:

/plugin install skill-creator@claude-plugins-official

Если установка не удалась, сопоставьте сообщение, которое сообщает Claude Code:

• Marketplace "claude-plugins-official" not found: добавьте marketplace с помощью /plugin marketplace add anthropics/claude-plugins-official, затем повторите попытку установки.
• Plugin "<name>" not found in marketplace "claude-plugins-official": ваша локальная копия каталога маркетплейса может быть устаревшей. Обновите ее с помощью /plugin marketplace update claude-plugins-official, затем повторите попытку установки. Если повторная попытка выводит то же сообщение, см. Плагин не найден в маркетплейсе.

Если сводка установки сообщает Run /reload-plugins to apply., Claude Code затем сам выполняет эту перезагрузку. Если при перезагрузке появляется предупреждение о том, что ваше следующее сообщение повторно прочитает диалог, выполните /reload-plugins --force, чтобы сделать скиллы плагина доступными в текущей сессии. Затем попросите Claude оценить существующий скилл, например evaluate my summarize-changes skill with skill-creator. Плагин проведет вас через написание тестовых случаев и запустит цикл:

• Тестовые случаи: сохраняет подсказки, входные файлы и ожидаемое поведение в evals/evals.json внутри каталога навыка
• Изолированные запуски: порождает подагента для каждого тестового случая, чтобы каждый запуск начинался с чистого контекста, и записывает количество токенов и продолжительность
• Оценка: проверяет каждое утверждение против результата и записывает успех или неудачу с доказательствами в grading.json
• Эталон: агрегирует процент успеха, время и токены для с навыком и без навыка в benchmark.json, чтобы вы могли сравнить улучшение процента успеха с накладными расходами на токены и время
• Сравнение версий: запускает слепое A/B между двумя версиями навыка, чтобы вы могли подтвердить, что редактирование является улучшением перед его фиксацией
• Настройка описания: генерирует подсказки should-trigger и should-not-trigger, измеряет процент попаданий и предлагает редактирование описания, когда навык активируется на неправильных запросах
• Средство просмотра отзывов: открывает отчет HTML, где вы проверяете каждый результат и записываете качественный отзыв, который следующая итерация читает

Для формата файла оценки и полного рабочего процесса итерации см. Evaluating skill output quality на agentskills.io. Для справки о режимах эталона и сравнения см. объявление skill-creator.

Совместное использование skills

Skills можно распространять на разных уровнях в зависимости от вашей аудитории:

• Project skills: Зафиксируйте .claude/skills/ в системе контроля версий
• Plugins: Создайте директорию skills/ в вашем plugin
• Managed: Разверните на уровне организации через managed settings

Генерация визуального вывода

Skills могут объединять и запускать скрипты на любом языке, предоставляя Claude возможности, которые невозможны в одном запросе. Один из паттернов — генерация визуального вывода: интерактивные HTML-файлы, которые открываются в вашем браузере для исследования данных, отладки или создания отчётов.

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

Создайте директорию Skill:

mkdir -p ~/.claude/skills/codebase-visualizer/scripts

Сохраните это в ~/.claude/skills/codebase-visualizer/SKILL.md. Описание сообщает Claude, когда активировать этот Skill, а инструкции указывают Claude запустить встроенный скрипт. Путь к скрипту использует ${CLAUDE_SKILL_DIR}, поэтому он правильно разрешается независимо от того, установлен ли skill на личном, проектном или уровне plugin:

---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python3 *)
---

# Codebase Visualizer

Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.

## Usage

Run the visualization script from your project root:

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
```

This creates `codebase-map.html` in the current directory and opens it in your default browser.

## What the visualization shows

- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder

Сохраните это в ~/.claude/skills/codebase-visualizer/scripts/visualize.py. Этот скрипт сканирует дерево директорий и генерирует самодостаточный HTML-файл с:

• Боковой панелью сводки, показывающей количество файлов, количество директорий, общий размер и количество типов файлов
• Столбчатой диаграммой, разбивающей кодовую базу по типам файлов (топ 8 по размеру)
• Сворачиваемым деревом, где вы можете разворачивать и сворачивать директории, с цветовыми индикаторами типов файлов

Скрипт требует Python 3, но использует только встроенные библиотеки, поэтому нет пакетов для установки:

#!/usr/bin/env python3
"""Generate an interactive collapsible tree visualization of a codebase."""

import json
import sys
import webbrowser
from html import escape
from pathlib import Path
from collections import Counter

IGNORE = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'}

def scan(path: Path, stats: dict) -> dict:
    result = {"name": path.name, "children": [], "size": 0}
    try:
        for item in sorted(path.iterdir()):
            if item.name in IGNORE or item.name.startswith('.'):
                continue
            if item.is_file():
                size = item.stat().st_size
                ext = item.suffix.lower() or '(no ext)'
                result["children"].append({"name": item.name, "size": size, "ext": ext})
                result["size"] += size
                stats["files"] += 1
                stats["extensions"][ext] += 1
                stats["ext_sizes"][ext] += size
            elif item.is_dir():
                stats["dirs"] += 1
                child = scan(item, stats)
                if child["children"]:
                    result["children"].append(child)
                    result["size"] += child["size"]
    except PermissionError:
        pass
    return result

def generate_html(data: dict, stats: dict, output: Path) -> None:
    ext_sizes = stats["ext_sizes"]
    total_size = sum(ext_sizes.values()) or 1
    sorted_exts = sorted(ext_sizes.items(), key=lambda x: -x[1])[:8]
    colors = {
        '.js': '#f7df1e', '.ts': '#3178c6', '.py': '#3776ab', '.go': '#00add8',
        '.rs': '#dea584', '.rb': '#cc342d', '.css': '#264de4', '.html': '#e34c26',
        '.json': '#6b7280', '.md': '#083fa1', '.yaml': '#cb171e', '.yml': '#cb171e',
        '.mdx': '#083fa1', '.tsx': '#3178c6', '.jsx': '#61dafb', '.sh': '#4eaa25',
    }
    lang_bars = "".join(
        f'<div class="bar-row"><span class="bar-label">{ext}</span>'
        f'<div class="bar" style="width:{(size/total_size)*100}%;background:{colors.get(ext,"#6b7280")}"></div>'
        f'<span class="bar-pct">{(size/total_size)*100:.1f}%</span></div>'
        for ext, size in sorted_exts
    )
    def fmt(b):
        if b < 1024: return f"{b} B"
        if b < 1048576: return f"{b/1024:.1f} KB"
        return f"{b/1048576:.1f} MB"

    html = f'''<!DOCTYPE html>
<html><head>
  <meta charset="utf-8"><title>Codebase Explorer</title>
  <style>
    body {{ font: 14px/1.5 system-ui, sans-serif; margin: 0; background: #1a1a2e; color: #eee; }}
    .container {{ display: flex; height: 100vh; }}
    .sidebar {{ width: 280px; background: #252542; padding: 20px; border-right: 1px solid #3d3d5c; overflow-y: auto; flex-shrink: 0; }}
    .main {{ flex: 1; padding: 20px; overflow-y: auto; }}
    h1 {{ margin: 0 0 10px 0; font-size: 18px; }}
    h2 {{ margin: 20px 0 10px 0; font-size: 14px; color: #888; text-transform: uppercase; }}
    .stat {{ display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid #3d3d5c; }}
    .stat-value {{ font-weight: bold; }}
    .bar-row {{ display: flex; align-items: center; margin: 6px 0; }}
    .bar-label {{ width: 55px; font-size: 12px; color: #aaa; }}
    .bar {{ height: 18px; border-radius: 3px; }}
    .bar-pct {{ margin-left: 8px; font-size: 12px; color: #666; }}
    .tree {{ list-style: none; padding-left: 20px; }}
    details {{ cursor: pointer; }}
    summary {{ padding: 4px 8px; border-radius: 4px; }}
    summary:hover {{ background: #2d2d44; }}
    .folder {{ color: #ffd700; }}
    .file {{ display: flex; align-items: center; padding: 4px 8px; border-radius: 4px; }}
    .file:hover {{ background: #2d2d44; }}
    .size {{ color: #888; margin-left: auto; font-size: 12px; }}
    .dot {{ width: 8px; height: 8px; border-radius: 50%; margin-right: 8px; }}
  </style>
</head><body>
  <div class="container">
    <div class="sidebar">
      <h1>📊 Summary</h1>
      <div class="stat"><span>Files</span><span class="stat-value">{stats["files"]:,}</span></div>
      <div class="stat"><span>Directories</span><span class="stat-value">{stats["dirs"]:,}</span></div>
      <div class="stat"><span>Total size</span><span class="stat-value">{fmt(data["size"])}</span></div>
      <div class="stat"><span>File types</span><span class="stat-value">{len(stats["extensions"])}</span></div>
      <h2>By file type</h2>
      {lang_bars}
    </div>
    <div class="main">
      <h1>📁 {escape(data["name"])}</h1>
      <ul class="tree" id="root"></ul>
    </div>
  </div>
</body></html>'''
    output.write_text(html)

if __name__ == '__main__':
    target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()
    stats = {"files": 0, "dirs": 0, "extensions": Counter(), "ext_sizes": Counter()}
    data = scan(target, stats)
    out = Path('codebase-map.html')
    generate_html(data, stats, out)
    print(f'Generated {out.absolute()}')
    webbrowser.open(f'file://{out.absolute()}')

Для тестирования откройте Claude Code в любом проекте и попросите "Visualize this codebase." Claude запускает скрипт, который выводит путь к созданному файлу, например Generated /path/to/codebase-map.html, и открывает его в вашем браузере. Если вы работаете в среде без графического интерфейса, где браузер не открывается, выведенный путь подтверждает, что скрипт выполнен успешно.

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

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

Скилл не срабатывает

Если Claude не использует ваш skill, когда это ожидается:

1. Проверьте, что описание включает ключевые слова, которые пользователи естественно произносят
2. Убедитесь, что skill появляется в What skills are available?
3. Попробуйте переформулировать ваш запрос, чтобы он лучше соответствовал описанию
4. Вызовите его напрямую с помощью /skill-name, если skill можно вызывать пользователю
5. Если /skill-name тоже не распознаётся, проверьте, не отклонил ли Claude Code имя skill
6. Если skill задаёт paths, проверьте, что файлы, которые Claude читает, редактирует или записывает, находятся внутри текущего рабочего каталога Claude. Skill не активируется для файлов за его пределами, например для файлов в соседнем git worktree, даже если вы добавили его с помощью /add-dir. Чтобы skill активировался для этих файлов, запустите Claude Code в этом worktree или переместите сессию туда с помощью /cd.

Если frontmatter YAML неправильно сформирован, Claude Code загружает тело skill с пустыми метаданными, поэтому /skill-name все еще работает, но Claude не может сопоставить с вашим description. Запустите с --debug, чтобы увидеть ошибку парсинга.

Если skill поставляется в плагине, вы можете измерить, как часто он срабатывает на реалистичных запросах, вместо того чтобы проверять по одному: напишите eval case с tool_used: Skill grader и запустите его с claude plugin eval после каждого изменения описания.

Чтобы найти файлы SKILL.md, frontmatter которых не парсится, запустите claude plugin validate в директории skills, например claude plugin validate .claude/skills для skills проекта или claude plugin validate ~/.claude/skills для личных skills. Требуется Claude Code v2.1.233 или позже.

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

Если Claude использует ваш skill, когда вы этого не хотите:

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

Claude перестаёт следовать скиллу

Если Claude следует skill в своем первом ответе и перестает следовать ему позже, начните с того случая, который соответствует вашей ситуации:

• Claude пропустил правило, которое должно соблюдаться каждый раз: переместите правило в hook. Claude Code запускает hook каждый раз, когда происходит его событие, например перед каждым редактированием файла, независимо от того, следует ли Claude skill или нет. Чтобы сохранить правило вместе со skill, определите hook в hooks frontmatter skill. Этот hook применяется с момента вызова skill до конца сеанса.
• Claude пропустил руководство, которое он должен применять с суждением: сформулируйте руководство так, чтобы оно применялось ко всей задаче, например "Запустите тесты после каждого редактирования" вместо "Запустите тесты". Claude Code добавляет содержимое skill в разговор при вызове skill и не перечитывает файл на более поздних ходах.
• Разговор был сжат: вызовите skill снова, чтобы восстановить его полное содержимое. После сжатия, Claude Code может сохранить только начало вызванного skill, поэтому поместите наиболее важные инструкции в начало SKILL.md.

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

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

Запустите /doctor для оценки стоимости контекста списка и его основных участников. Чтобы найти skills, стоящие отключения, запустите /skill-doctor. Когда список превышает свой бюджет, Claude Code также записывает предупреждение в журнал отладки, видимый с --debug.

Строка Skills в /context сообщает размер списка после применения бюджета, поэтому он соответствует тому, что получает модель. До v2.1.196 строка считала полный текст каждого описания и могла показать значение в несколько раз больше, чем настроенный бюджет.

Чтобы увеличить бюджет, установите параметр skillListingBudgetFraction (например 0.02 = 2%) или переменную окружения SLASH_COMMAND_TOOL_CHAR_BUDGET на фиксированное количество символов. Чтобы освободить бюджет для других skills, установите записи с низким приоритетом на "name-only" в skillOverrides, чтобы они отображались без описания. Вы также можете сократить текст description и when_to_use в источнике: поместите основной вариант использования в первую очередь, так как объединённый текст каждой записи ограничен 1536 символами независимо от бюджета. Ограничение настраивается с помощью skillListingMaxDescChars.

Угловые скобки в описании скилла отображаются как < и >

Claude Code отображает < и > в полях description и when_to_use как < и >. Чтобы показать заполнитель, например <branch>, используйте квадратные скобки или argument-hint:

• Квадратные скобки: замените <branch> на [branch], что отображается так, как введено
• argument-hint: перенесите заполнитель в новую строку argument-hint: <branch>. Он отображается после имени команды. Если вы также загружаете skill в claude.ai или Skills API, сначала проверьте, принимается ли там argument-hint.

Личные скиллы исчезли

Если папки skills, которые вы создали в ~/.claude/skills/, исчезли, посмотрите в ~/.claude/skills/.trash/. Когда Claude Code синхронизирует skills из claude.ai, он загружает их в отдельную подпапку synced и не перемещает и не удаляет папки, которые вы создаёте.

До v2.1.280 файл с именем manifest.json в ~/.claude/skills/ заставлял Claude Code перемещать папки skills, которые этот файл указывал, в папку с временной меткой под ~/.claude/skills/.trash/, и эти skills перестали загружаться.

Чтобы восстановить skill, переместите его папку из папки с временной меткой обратно в ~/.claude/skills/. Сделайте это до того, как очистка хранилища удалит записи из корзины, по умолчанию через 30 дней после их перемещения в корзину.

Связанные ресурсы

• Отладка вашей конфигурации: диагностируйте, почему 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