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

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

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

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

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.

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

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

Три встроенных 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 в корне репозитория, или в затронутом каталоге пакета в монорепозитории, чтобы более поздние запуски и другие агенты следовали тем же шагам. В корне репозитория записанный skill заменяет встроенный /verify. Это требует Claude Code v2.1.200 или позже.

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

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

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

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

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

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

What did I change?

/summarize-changes

Выберите, где загружаются skills

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

Папки Skill также следуют этим правилам:

• Symlinked folders: запись <skill-name> в расположении enterprise, personal или project может быть символической ссылкой на каталог в другом месте на диске. Claude Code читает SKILL.md из целевого объекта и загружает skill один раз, даже если несколько расположений указывают на один и тот же целевой объект. Plugin skills обрабатывают символические ссылки по-другому.
• Reserved name: не называйте папку skill synced в любом регистре. Claude Code использует ~/.claude/skills/synced/ для skills загруженных с claude.ai и пропускает skill, который вы создаете с этим именем в расположениях enterprise, personal и project.
• Command files: файл Markdown в .claude/commands/ — это более старый формат, который все еще работает. Он поддерживает то же frontmatter, кроме name и paths. Чтобы найти имя, которое вы вводите для его вызова, см. Как skill получает имя команды. Предпочитайте skill для новой работы, так как skills также поддерживают вспомогательные файлы.
• Skill folder as a plugin: добавьте .claude-plugin/plugin.json в папку skill, и она загружается как plugin с именем <name>@skills-dir, поэтому она может объединять agents, hooks и MCP servers. В .claude/skills/ проекта это требует сначала принять диалог доверия рабочей области.

Загружайте skills в monorepos и подкаталоги

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

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

Когда вложенный skill имеет то же имя, что и другой skill, оба остаются доступными. С skill deploy в корне репозитория и другим в apps/web/.claude/skills/:

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

Загружайте skills из каталога вне проекта

Когда вы добавляете каталог с --add-dir или /add-dir, Claude Code загружает skills в .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 при запуске, как описано в Редактируйте skill во время сеанса. Он не отслеживает .claude/commands/ или .claude/agents/ добавленного каталога, поэтому перезапустите сеанс после изменения файла там.

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

Разрешайте skills, которые имеют одинаковое имя

Когда два skills имеют одинаковое имя, откуда каждый из них пришел, решает, какой из них запускает /name. Таблица охватывает расположения enterprise, personal, project, nested, plugin и claude.ai, встроенные skills и command files:

Используйте skills в Cowork и облачных сеансах

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

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

• Для Cowork и облачных сеансов включите skill для вашей учетной записи claude.ai.
• Для облачных сеансов вы можете вместо этого зафиксировать skill в .claude/skills/ репозитория или отправить его в plugin, объявленном в .claude/settings.json репозитория. Plugins, объявленные в репозитории, устанавливаются при запуске сеанса; plugins, включенные только в параметрах пользователя, не передаются.

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

Skills синхронизированные с claude.ai

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Другая команда может быть любой из этих:

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

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

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

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

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

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

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

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

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

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

Редактируйте skill во время сеанса

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

Live change detection охватывает только текст SKILL.md. Для папки skill, которая также является plugin, изменения в hooks/, .mcp.json, agents/ и output-styles/ требуют /reload-plugins для вступления в силу.

Удалите skill

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

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

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

Настройка skills

Skills настраиваются через YAML frontmatter в начале SKILL.md и содержимое markdown, которое следует за ним.

Типы содержимого skill

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

Справочное содержимое добавляет знания, которые 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

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

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

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

Справочник Frontmatter

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

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

Your skill instructions here...

Все поля являются необязательными. Рекомендуется только description, чтобы Claude знал, когда использовать skill.

Claude Code читает frontmatter только когда открывающий --- является первой строкой файла. В противном случае он обрабатывает весь файл, включая маркеры ---, как содержимое skill.

Логические поля принимают yes, no, on, off, 1 и 0 в любом регистре, в дополнение к true и false. До v2.1.218 Claude Code распознавал только true и false.

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

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

Когда вы включаете личный skill для сеансов Cowork и cloud, включая процедуры, вы загружаете его на 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 без изменений.

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

Команда, которую вы вводите для вызова skill, зависит от того, где находится файл skill и, для plugin skills, также от поля frontmatter name. В личном или проектном skill name устанавливает только отображаемый ярлык, показываемый в списках skills, а команда все еще поступает из имени каталога. В plugin skill name устанавливает последний сегмент команды, а префикс plugin остается на месте.

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

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

В неинтерактивных сеансах имена help и feedback не зарезервированы для их встроенных команд, специфичных для терминала, поэтому plugin skill с одним из этих имен сохраняет свою голую команду там. Каждое другое встроенное имя, специфичное для терминала, такое как /login, остается зарезервированным, даже если команда не может запуститься в этих сеансах.

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

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

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

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

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

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

Подстановка ${CLAUDE_PROJECT_DIR} требует Claude Code v2.1.196 или позже.

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

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

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

Чтобы включить буквальный $ перед цифрой, 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

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

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

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-09-17-0500..2026-09-18-2358/reference/)
- For usage examples, see [examples.md](/anthropic/claude-code/history/docs/ru/2026-09-17-0500..2026-09-18-2358/examples/)

Контроль того, кто вызывает skill

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

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

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

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

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

Deploy $ARGUMENTS to production:

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

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

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

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

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

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

Auto-compact переносит вызванные skills в рамках бюджета токенов. Когда разговор суммируется для освобождения контекста, Claude Code повторно прикрепляет самый последний вызов каждого skill после резюме, сохраняя первые 5000 токенов каждого. Повторно прикрепленные skills делят объединенный бюджет 25000 токенов. Claude Code заполняет этот бюджет, начиная с самого недавно вызванного skill, поэтому старые skills могут быть полностью удалены после компактирования, если вы вызвали много в одном сеансе.

Если skill кажется перестает влиять на поведение после первого ответа, содержимое обычно все еще присутствует, и модель выбирает другие tools или подходы. Усильте description skill и инструкции, чтобы модель продолжала его предпочитать, или используйте hooks, чтобы детерминированно обеспечить поведение. Если skill большой или вы вызвали несколько других после него, повторно вызовите его после компактирования, чтобы восстановить полное содержимое.

Предварительное одобрение tools для skill

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

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

Этот skill позволяет 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 *)
---

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

Передача аргументов в skills

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

Этот skill исправляет проблему GitHub по номеру. Заполнитель $ARGUMENTS заменяется на все, что следует за именем skill:

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

Fix GitHub issue $ARGUMENTS following our coding standards.

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

Когда вы запускаете /fix-issue 123, Claude получает "Fix GitHub issue 123 following our coding standards..."

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

Вы также можете складывать несколько skills в начале одного сообщения. Ввод /write-tests /fix-issue 123 загружает оба skills и передает конечный текст 123 как $ARGUMENTS каждому из них. До v2.1.199 только первый skill загружался и получал /fix-issue 123 как буквальный текст аргумента.

Claude Code расширяет первый skill плюс до пяти дополнительных, сложенных после него. Расширение останавливается на первом токене, который не является встроенным skill, вызываемым пользователем, поэтому skill, который запускается как подагент fork, такой как /code-review, или тот, чьи аргументы сами могут начинаться с команды slash, такой как /loop, также заканчивается там. Этот токен и все, что после него, становятся текстом аргумента для каждого расширенного skill. /code-review запускается как подагент fork с v2.1.218; на более ранних версиях он запускался встроенным и складывался.

Чтобы получить доступ к отдельным аргументам по позиции, используйте $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. Тот же skill, использующий сокращение $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.

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

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

Синтаксис !`<command>` запускает команды оболочки перед отправкой содержимого навыка 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
```

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

Claude Code никогда не запускает эти команды на вашей машине, когда они появляются в навыках синхронизированных с вашего аккаунта claude.ai, независимо от этого параметра. Это ограничение требует Claude Code v2.1.228 или позже. How Claude Code handles the body of a synced skill говорит, что Claude получает вместо команды в каждом виде сеанса.

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

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.

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

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

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

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

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

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

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

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

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

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

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

Вне режима auto, когда проверка разрешения команды возвращает что-либо, кроме разрешения, Claude Code прерывает вызов с той же ошибкой. Это включает правило, которое обычно вас спрашивает. Чтобы предотвратить прерывание несовпадающей команды здесь, предварительно одобрите ее с помощью allowed-tools. Правила deny и ask все равно переопределяют allowed-tools. См. Manage permissions.

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

Запуск навыков в подагенте

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

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

Claude Code также ждет результата, даже когда навык не устанавливает background: false, в случаях, подобных этим:

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

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

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

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

С context: fork вы пишете задачу в своем навыке и выбираете тип агента для ее выполнения. Встроенные агенты Explore и Plan пропускают CLAUDE.md и статус git, чтобы сохранить их контекст небольшим, поэтому разветвленный навык, использующий agent: Explore, видит только содержимое SKILL.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 называет псевдоним или неквалифицированное имя, а не собственное имя навыка, Claude Code все равно блокирует навык: с Skill(review) он блокирует встроенный /code-review через его псевдоним /review, и с Skill(deploy) он блокирует вложенный навык, указанный как apps/web:deploy через его неквалифицированное имя. До v2.1.260 Claude Code не блокировал вложенный навык, указанный под его квалифицированным именем, когда правило deny называло только неквалифицированное имя.

Claude Code совпадает с правилом allow только с собственным именем навыка и именем в вызове Claude.

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

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

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

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

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

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

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

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

Некоторые встроенные навыки имеют псевдонимы, такие как checkup для /doctor. Если вы установите запись skillOverrides под псевдонимом в managed settings или в файле, который вы передаете с флагом --settings, Claude Code применит его к навыку за псевдонимом. Вы можете только ограничить навык дальше через псевдоним, никогда не сделать его более видимым, и если вы также установите запись под собственным именем навыка в managed settings, эта запись имеет приоритет. До 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 его на подсказках, которые он должен, и соответствует ли результат тому, что вы ожидаете, когда он это делает.

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

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

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

Плагин skill-creator автоматизирует цикл сравнения внутри Claude Code. Установите его из официального marketplace:

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

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

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

Если сводка установки сообщает Run /reload-plugins to activate., 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 управляет оркестрацией.

Troubleshooting

Skill not triggering

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

1. Проверьте, что описание включает ключевые слова, которые пользователи естественно произносят
2. Убедитесь, что skill появляется в What skills are available?
3. Попробуйте переформулировать ваш запрос, чтобы он лучше соответствовал описанию
4. Вызовите его напрямую с помощью /skill-name, если skill можно вызывать пользователю

Если 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 или позже.

Skill triggers too often

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

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

Skill descriptions are cut short

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.

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

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