> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Расширьте 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`, см. [справочник команд](/ru/commands).

  **Пользовательские команды были объединены с skills.** Файл в `.claude/commands/deploy.md` и skill в `.claude/skills/deploy/SKILL.md` оба создают `/deploy` и работают одинаково. Ваши существующие файлы `.claude/commands/` продолжают работать. Skills добавляют дополнительные функции: каталог для вспомогательных файлов, frontmatter для [управления тем, кто вызывает skill](#control-who-invokes-a-skill), и возможность для Claude загружать их автоматически при необходимости.
</Note>

Skills в Claude Code следуют открытому стандарту [Agent Skills](https://agentskills.io), который работает с несколькими инструментами AI. Claude Code расширяет стандарт дополнительными функциями, такими как [управление вызовом](#control-who-invokes-a-skill), [выполнение в subagent](#run-skills-in-a-subagent) и [динамическое внедрение контекста](#inject-dynamic-context).

<h2 id="bundled-skills">
  Встроенные skills
</h2>

Claude Code включает набор встроенных skills, которые доступны в каждой сессии, если они не отключены с помощью параметра [`disableBundledSkills`](/ru/settings#available-settings), включая `/code-review`, `/batch`, `/debug`, `/loop` и `/claude-api`. В отличие от большинства встроенных команд, которые выполняют фиксированную логику напрямую, встроенные skills основаны на подсказках: они дают Claude подробные инструкции и позволяют ему организовать работу, используя свои инструменты. Вы вызываете их так же, как любой другой skill, введя `/` и затем имя skill.

Встроенные skills перечислены вместе со встроенными командами в [справочнике команд](/ru/commands), отмечены как **Skill** в столбце Purpose.

<h3 id="run-and-verify-your-app">
  Запуск и проверка вашего приложения
</h3>

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

| Skill                  | Назначение                                                                                                                                   |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
| `/run`                 | Запустите и управляйте вашим приложением, чтобы увидеть работающее изменение                                                                 |
| `/verify`              | Соберите и запустите ваше приложение, чтобы подтвердить, что изменение кода делает то, что должно, без возврата к тестам или проверкам типов |
| `/run-skill-generator` | Научите `/run` и `/verify` собирать и запускать ваш проект                                                                                   |

{/* min-version: 2.1.145 */}Все три skills требуют Claude Code версии 2.1.145 или позже.

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

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

<h2 id="getting-started">
  Начало работы
</h2>

<h3 id="create-your-first-skill">
  Создайте свой первый skill
</h3>

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

<Steps>
  <Step title="Создайте каталог skill">
    Создайте каталог для skill в папке личных skills. Личные skills доступны во всех ваших проектах.

    ```bash theme={null}
    mkdir -p ~/.claude/skills/summarize-changes
    ```
  </Step>

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

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

    ```yaml theme={null}
    ---
    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` `` использует [динамическое внедрение контекста](#inject-dynamic-context): Claude Code запускает команду и заменяет строку её выходом перед тем, как Claude увидит содержимое skill, поэтому инструкции приходят с текущим diff уже встроенным.
  </Step>

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

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

    ```text theme={null}
    What did I change?
    ```

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

    ```text theme={null}
    /summarize-changes
    ```

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

<h3 id="where-skills-live">
  Где находятся skills
</h3>

Место, где вы сохраняете skill, определяет, кто может его использовать:

| Местоположение | Путь                                                     | Применяется к                        |
| :------------- | :------------------------------------------------------- | :----------------------------------- |
| Enterprise     | См. [управляемые параметры](/ru/settings#settings-files) | Все пользователи в вашей организации |
| Personal       | `~/.claude/skills/<skill-name>/SKILL.md`                 | Все ваши проекты                     |
| Project        | `.claude/skills/<skill-name>/SKILL.md`                   | Только этот проект                   |
| Plugin         | `<plugin>/skills/<skill-name>/SKILL.md`                  | Где включен плагин                   |

Когда skills имеют одинаковые имена на разных уровнях, enterprise переопределяет personal, а personal переопределяет project. Skill на любом из этих уровней также переопределяет встроенный skill с тем же именем. Например, skill `code-review` в папке `.claude/skills/` вашего проекта заменяет встроенный `/code-review`. Plugin skills используют пространство имён `plugin-name:skill-name`, поэтому они не могут конфликтовать с другими уровнями. Если у вас есть файлы в `.claude/commands/`, они работают так же, но если skill и команда имеют одинаковое имя, skill имеет приоритет.

Skills также загружаются из вложенных каталогов `.claude/skills/` ниже вашего рабочего каталога. Когда Claude читает или редактирует файл в подкаталоге, skills из `.claude/skills/` этого подкаталога становятся доступными. Это позволяет пакету monorepo предоставлять свои собственные skills, которые применяются при работе с этим пакетом, даже если сессия началась в корне репозитория.

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

* Вложенный появляется под квалифицированным именем каталога, `apps/web:deploy`.
* Его описание говорит, к какому каталогу он применяется.
* Claude выбирает вариант, который соответствует файлам, с которыми он работает.

Ввод `/deploy` запускает skill корня проекта. Введите квалифицированное имя `/apps/web:deploy`, чтобы запустить вложенный вариант явно.

Запись `<skill-name>` в местоположениях enterprise, personal или project может быть символической ссылкой на каталог в другом месте на диске. Claude Code следует символической ссылке и читает `SKILL.md` из целевого каталога, и если один и тот же целевой каталог доступен из более чем одного местоположения, Claude Code загружает skill один раз. Plugin skills обрабатывают символические ссылки иначе; см. [Совместное использование файлов в marketplace с помощью символических ссылок](/ru/plugins-reference#share-files-within-a-marketplace-with-symlinks).

<Note>
  Добавьте `.claude-plugin/plugin.json` в папку skill, и она загружается как [плагин](/ru/plugins-reference#skills-directory-plugins) с именем `<name>@skills-dir`, поэтому он может объединять agents, hooks и MCP servers. В `.claude/skills/` проекта это требует предварительного принятия диалога доверия рабочей области.
</Note>

<h4 id="live-change-detection">
  Обнаружение живых изменений
</h4>

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

<Note>
  Обнаружение живых изменений охватывает только текст `SKILL.md`. Для папки skill, которая также является [плагином](/ru/plugins-reference#skills-directory-plugins), изменения в `hooks/`, `.mcp.json`, `agents/` и `output-styles/` требуют `/reload-plugins` для вступления в силу.
</Note>

<h4 id="automatic-discovery-from-parent-and-nested-directories">
  Автоматическое обнаружение из родительских и вложенных каталогов
</h4>

Project skills загружаются из `.claude/skills/` в вашем начальном каталоге и в каждом родительском каталоге вплоть до корня репозитория, поэтому запуск Claude в подкаталоге по-прежнему подхватывает skills, определённые в корне. Когда вы работаете с файлами в подкаталогах ниже вашего начального каталога, Claude Code также обнаруживает skills из вложенных каталогов `.claude/skills/` по требованию. Например, если вы редактируете файл в `packages/frontend/`, Claude Code также ищет skills в `packages/frontend/.claude/skills/`. Это поддерживает настройки monorepo, где пакеты имеют свои собственные skills.

Каждый skill — это каталог с `SKILL.md` в качестве точки входа:

```text theme={null}
my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output showing expected format
└── scripts/
    └── validate.sh    # Script Claude can execute
```

`SKILL.md` содержит основные инструкции и является обязательным. Другие файлы необязательны и позволяют вам создавать более мощные skills: шаблоны для заполнения Claude, примеры выходных данных, показывающие ожидаемый формат, скрипты, которые Claude может выполнять, или подробную справочную документацию. Ссылайтесь на эти файлы из вашего `SKILL.md`, чтобы Claude знал, что они содержат и когда их загружать. См. [Добавьте вспомогательные файлы](#add-supporting-files) для получения дополнительной информации.

<Note>
  Файлы в `.claude/commands/` по-прежнему работают и поддерживают тот же [frontmatter](#frontmatter-reference). Skills рекомендуются, так как они поддерживают дополнительные функции, такие как вспомогательные файлы.
</Note>

<h4 id="skills-from-additional-directories">
  Skills из дополнительных каталогов
</h4>

Флаг `--add-dir` и команда `/add-dir` [предоставляют доступ к файлам](/ru/permissions#additional-directories-grant-file-access-not-configuration) скорее, чем конфигурацию обнаружения, но skills — это исключение: `.claude/skills/` в добавленном каталоге загружается автоматически. Это исключение применяется только к `--add-dir` и `/add-dir`. Параметр `permissions.additionalDirectories` в `settings.json` предоставляет доступ к файлам только и не загружает skills. См. [Обнаружение живых изменений](#live-change-detection) для того, как правки подхватываются во время сессии.

Другая конфигурация `.claude/`, такая как commands и output styles, не загружается из дополнительных каталогов. См. [таблицу исключений](/ru/permissions#additional-directories-grant-file-access-not-configuration) для полного списка того, что загружается и что не загружается, и рекомендуемые способы совместного использования конфигурации между проектами.

<Note>
  Файлы CLAUDE.md из каталогов `--add-dir` не загружаются по умолчанию. Чтобы загружать их, установите `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`. См. [Загрузка из дополнительных каталогов](/ru/memory#load-from-additional-directories).
</Note>

<h2 id="configure-skills">
  Настройка skills
</h2>

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

<h3 id="types-of-skill-content">
  Типы содержимого skill
</h3>

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

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

```yaml theme={null}
---
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.

```yaml theme={null}
---
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.md` может содержать что угодно, но размышление о том, как вы хотите вызывать skill (вы, Claude или оба) и где вы хотите его запускать (встроенно или в subagent), помогает направить, что включить. Для сложных skills вы также можете [добавить вспомогательные файлы](#add-supporting-files), чтобы сохранить основной skill сосредоточенным.

Сохраняйте само тело кратким. После загрузки skill его содержимое [остаётся в контексте на протяжении ходов](#skill-content-lifecycle), поэтому каждая строка — это повторяющаяся стоимость токенов. Указывайте, что делать, а не рассказывайте, как или почему, и применяйте тот же тест краткости, который вы бы применили к [содержимому CLAUDE.md](/ru/best-practices#write-an-effective-claude-md).

<h3 id="frontmatter-reference">
  Справочник frontmatter
</h3>

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

```yaml theme={null}
---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---

Your skill instructions here...
```

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

| Поле                       | Обязательно   | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| :------------------------- | :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                     | Нет           | Отображаемое имя, показываемое в списках skills. По умолчанию используется имя каталога. См. [Как skill получает имя команды](#how-a-skill-gets-its-command-name), чтобы узнать, чем это отличается от имени, которое вы вводите для вызова skill.                                                                                                                                                                                                                                                         |
| `description`              | Рекомендуется | Что делает skill и когда его использовать. Claude использует это, чтобы решить, когда применять skill. Если опущено, использует первый абзац содержимого markdown. Поместите основной вариант использования в первую очередь: комбинированный текст `description` и `when_to_use` усекается на 1 536 символах в списке skills для уменьшения использования контекста.                                                                                                                                      |
| `when_to_use`              | Нет           | Дополнительный контекст для того, когда Claude должен вызвать skill, такой как фразы-триггеры или примеры запросов. Добавляется к `description` в списке skills и учитывается в лимите 1 536 символов.                                                                                                                                                                                                                                                                                                     |
| `argument-hint`            | Нет           | Подсказка, показываемая при автодополнении, чтобы указать ожидаемые аргументы. Пример: `[issue-number]` или `[filename] [format]`.                                                                                                                                                                                                                                                                                                                                                                         |
| `arguments`                | Нет           | Именованные позиционные аргументы для [подстановки `$name`](#available-string-substitutions) в содержимом skill. Принимает строку, разделённую пробелами, или список YAML. Имена соответствуют позициям аргументов по порядку.                                                                                                                                                                                                                                                                             |
| `disable-model-invocation` | Нет           | Установите на `true`, чтобы предотвратить автоматическую загрузку этого skill Claude. Используйте для рабочих процессов, которые вы хотите запустить вручную с помощью `/name`. Также предотвращает [предварительную загрузку skill в subagents](/ru/sub-agents#preload-skills-into-subagents). {/* min-version: 2.1.196 */}Начиная с версии 2.1.196, также предотвращает запуск skill при срабатывании [запланированной задачи](/ru/scheduled-tasks) с skill в качестве подсказки. По умолчанию: `false`. |
| `user-invocable`           | Нет           | Установите на `false`, чтобы скрыть из меню `/`. Используйте для фоновых знаний, которые пользователи не должны вызывать напрямую. По умолчанию: `true`.                                                                                                                                                                                                                                                                                                                                                   |
| `allowed-tools`            | Нет           | Инструменты, которые Claude может использовать без запроса разрешения, когда этот skill активен. Принимает строку, разделённую пробелами или запятыми, или список YAML.                                                                                                                                                                                                                                                                                                                                    |
| `disallowed-tools`         | Нет           | Инструменты, удалённые из доступного пула Claude, пока этот skill активен. Используйте для автономных skills, которые никогда не должны вызывать определённые инструменты, такие как `AskUserQuestion` для фонового цикла. Принимает строку, разделённую пробелами или запятыми, или список YAML. Ограничение очищается при отправке вашего следующего сообщения.                                                                                                                                          |
| `model`                    | Нет           | Модель для использования, когда этот skill активен. Переопределение применяется для остальной части текущего хода и не сохраняется в параметры; модель сессии возобновляется при вашем следующем запросе. Принимает те же значения, что и [`/model`](/ru/model-config), или `inherit`, чтобы сохранить активную модель. Значение, исключённое списком разрешений `availableModels` вашей организации, не используется, и сессия сохраняет свою текущую модель.                                             |
| `effort`                   | Нет           | [Уровень усилий](/ru/model-config#adjust-effort-level) при активном этом skill. Переопределяет уровень усилий сессии. По умолчанию: наследует из сессии. Опции: `low`, `medium`, `high`, `xhigh`, `max`; доступные уровни зависят от модели.                                                                                                                                                                                                                                                               |
| `context`                  | Нет           | Установите на `fork`, чтобы запустить в контексте forked subagent.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `agent`                    | Нет           | Какой тип subagent использовать, когда установлен `context: fork`.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `hooks`                    | Нет           | Hooks, ограниченные жизненным циклом этого skill. См. [Hooks в skills и agents](/ru/hooks#hooks-in-skills-and-agents) для формата конфигурации.                                                                                                                                                                                                                                                                                                                                                            |
| `paths`                    | Нет           | Glob паттерны, которые ограничивают, когда этот skill активируется. Принимает строку, разделённую запятыми, или список YAML. Когда установлено, Claude загружает skill автоматически только при работе с файлами, соответствующими паттернам. Использует тот же формат, что и [правила, специфичные для пути](/ru/memory#path-specific-rules).                                                                                                                                                             |
| `shell`                    | Нет           | Shell для использования в блоках `` !`command` `` и ` ```! ` в этом skill. Принимает `bash` (по умолчанию) или `powershell`. Установка `powershell` запускает встроенные команды shell через PowerShell на Windows. Требует `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`.                                                                                                                                                                                                                                           |

<h4 id="how-a-skill-gets-its-command-name">
  Как skill получает имя команды
</h4>

Команда, которую вы вводите для вызова skill, зависит от того, где находится файл skill. Поле frontmatter `name` устанавливает отображаемый ярлык, показываемый в списках skills и, за исключением корневого `SKILL.md` плагина, не изменяет то, что вы вводите после `/`.

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

| Расположение skill                                                                              | Источник имени команды                                                       | Пример                                                                                                                               |
| :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| Каталог skill в `~/.claude/skills/` или `.claude/skills/`                                       | Имя каталога                                                                 | `.claude/skills/deploy-staging/SKILL.md` → `/deploy-staging`                                                                         |
| [Вложенный](#where-skills-live) каталог `.claude/skills/`, когда имя конфликтует с другим skill | Путь подкаталога относительно рабочего каталога, затем имя каталога skill    | `apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy`                                                                       |
| Файл в `.claude/commands/`                                                                      | Имя файла без расширения                                                     | `.claude/commands/deploy.md` → `/deploy`                                                                                             |
| Подкаталог `skills/` плагина                                                                    | Имя каталога, с пространством имён по плагину                                | `my-plugin/skills/review/SKILL.md` → `/my-plugin:review`                                                                             |
| Корневой `SKILL.md` плагина                                                                     | Frontmatter `name`, с именем каталога плагина в качестве резервного варианта | `my-plugin/SKILL.md` с `name: review` → `/my-plugin:review`. См. [Правила поведения пути](/ru/plugins-reference#path-behavior-rules) |

Случай с корневым плагином — это единственное место, где `name` устанавливает имя команды, потому что нет каталога skill, чтобы взять его оттуда. Если `name` не установлен в frontmatter, вместо этого используется имя каталога плагина.

<h4 id="available-string-substitutions">
  Доступные подстановки строк
</h4>

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

| Переменная              | Описание                                                                                                                                                                                                                                                                                                                     |
| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$ARGUMENTS`            | Все аргументы, переданные при вызове skill. Если `$ARGUMENTS` отсутствует в содержимом, аргументы добавляются как `ARGUMENTS: <value>`.                                                                                                                                                                                      |
| `$ARGUMENTS[N]`         | Доступ к конкретному аргументу по индексу на основе 0, например `$ARGUMENTS[0]` для первого аргумента.                                                                                                                                                                                                                       |
| `$N`                    | Сокращение для `$ARGUMENTS[N]`, например `$0` для первого аргумента или `$1` для второго.                                                                                                                                                                                                                                    |
| `$name`                 | Именованный аргумент, объявленный в списке frontmatter [`arguments`](#frontmatter-reference). Имена соответствуют позициям по порядку, поэтому с `arguments: [issue, branch]` заполнитель `$issue` расширяется до первого аргумента и `$branch` ко второму.                                                                  |
| `${CLAUDE_SESSION_ID}`  | Текущий ID сессии. Полезно для логирования, создания файлов, специфичных для сессии, или корреляции выходных данных skill с сессиями.                                                                                                                                                                                        |
| `${CLAUDE_EFFORT}`      | Текущий уровень усилий: `low`, `medium`, `high`, `xhigh` или `max`. Ultracode не является отдельным уровнем и сообщается как `xhigh`. Используйте это, чтобы адаптировать инструкции skill к активному параметру усилий.                                                                                                     |
| `${CLAUDE_SKILL_DIR}`   | Каталог, содержащий файл `SKILL.md` skill. Для plugin skills это подкаталог skill в плагине, а не корень плагина. Используйте это в командах bash injection для ссылки на скрипты или файлы, поставляемые с skill, независимо от текущего рабочего каталога.                                                                 |
| `${CLAUDE_PROJECT_DIR}` | Каталог корня проекта. Это тот же путь, который [hooks](/ru/hooks#reference-scripts-by-path) и MCP серверы получают как `CLAUDE_PROJECT_DIR`. Используйте это для ссылки на скрипты или файлы, специфичные для проекта, такие как `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`, независимо от того, где установлен skill. |

Подстановка `${CLAUDE_PROJECT_DIR}` требует Claude Code версии 2.1.196 или позже. Она применяется как к телу skill, так и к frontmatter [`allowed-tools`](#frontmatter-reference), поэтому правило разрешения, такое как `Bash(${CLAUDE_PROJECT_DIR}/scripts/lint.sh *)`, разрешается в тот же путь, который использует тело skill.

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

Чтобы включить литеральный `$` перед цифрой, `ARGUMENTS` или объявленным именем аргумента, например `$1.00` в прозе, экранируйте его обратной косой чертой: `\$1.00`. Обратная косая черта перед любым другим `$` остаётся неизменной. Только одна обратная косая черта непосредственно перед токеном экранирует его. Удвоенная обратная косая черта, такая как `\\$1`, оставляет обе обратные косые черты на месте, и `$1` всё ещё расширяется до значения аргумента.

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

```yaml theme={null}
---
name: session-logger
description: Log activity for this session
---

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

$ARGUMENTS
```

<h3 id="add-supporting-files">
  Добавьте вспомогательные файлы
</h3>

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

```text theme={null}
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 знал, что содержит каждый файл и когда его загружать:

```markdown theme={null}
## Additional resources

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

<Tip>Сохраняйте `SKILL.md` под 500 строк. Переместите подробный справочный материал в отдельные файлы.</Tip>

<h3 id="control-who-invokes-a-skill">
  Управляйте тем, кто вызывает skill
</h3>

По умолчанию как вы, так и 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:

```yaml theme={null}
---
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
```

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

| Frontmatter                      | Вы можете вызвать | Claude может вызвать | Когда загружается в контекст                                       |
| :------------------------------- | :---------------- | :------------------- | :----------------------------------------------------------------- |
| (по умолчанию)                   | Да                | Да                   | Описание всегда в контексте, полный skill загружается при вызове   |
| `disable-model-invocation: true` | Да                | Нет                  | Описание не в контексте, полный skill загружается при вашем вызове |
| `user-invocable: false`          | Нет               | Да                   | Описание всегда в контексте, полный skill загружается при вызове   |

<Note>
  В обычной сессии описания skills загружаются в контекст, чтобы Claude знал, что доступно, но полное содержимое skill загружается только при вызове. [Subagents с предварительно загруженными skills](/ru/sub-agents#preload-skills-into-subagents) работают иначе: полное содержимое skill внедряется при запуске.
</Note>

<h3 id="skill-content-lifecycle">
  Жизненный цикл содержимого skill
</h3>

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

[Auto-compact](/ru/how-claude-code-works#when-context-fills-up) переносит вызванные skills в рамках бюджета токенов. Когда разговор суммируется для освобождения контекста, Claude Code повторно прикрепляет самый последний вызов каждого skill после сводки, сохраняя первые 5 000 токенов каждого. Повторно прикреплённые skills делят объединённый бюджет в 25 000 токенов. Claude Code заполняет этот бюджет, начиная с самого недавно вызванного skill, поэтому более старые skills могут быть полностью удалены после компактирования, если вы вызвали много в одной сессии.

Если skill кажется перестаёт влиять на поведение после первого ответа, содержимое обычно всё ещё присутствует, и модель выбирает другие инструменты или подходы. Усильте описание skill и инструкции, чтобы модель продолжала его предпочитать, или используйте [hooks](/ru/hooks) для детерминированного обеспечения поведения. Если skill большой или вы вызвали несколько других после него, повторно вызовите его после компактирования, чтобы восстановить полное содержимое.

<h3 id="pre-approve-tools-for-a-skill">
  Предварительно одобрите инструменты для skill
</h3>

Поле `allowed-tools` предоставляет разрешение для перечисленных инструментов, пока skill активен, поэтому Claude может использовать их без запроса вашего одобрения. Это не ограничивает, какие инструменты доступны: каждый инструмент остаётся вызываемым, и ваши [параметры разрешений](/ru/permissions) по-прежнему управляют инструментами, которые не указаны.

Для skills, проверенных в каталоге `.claude/skills/` проекта, `allowed-tools` вступает в силу после того, как вы примете диалог доверия рабочей области для этой папки, так же как правила разрешений в `.claude/settings.json`. Проверьте skills проекта перед доверием к репозиторию, так как skill может предоставить себе широкий доступ к инструментам.

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

```yaml theme={null}
---
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, пока skill активен, перечислите их в `disallowed-tools` в frontmatter skill. Ограничение очищается при отправке вашего следующего сообщения. Чтобы заблокировать инструменты во всех skills и подсказках, добавьте правила отказа в ваши [параметры разрешений](/ru/permissions).

<h3 id="pass-arguments-to-skills">
  Передайте аргументы в skills
</h3>

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

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

```yaml theme={null}
---
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 не включает `$ARGUMENTS`, Claude Code добавляет `ARGUMENTS: <your input>` в конец содержимого skill, чтобы Claude всё ещё видел, что вы ввели.

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

```yaml theme={null}
---
name: migrate-component
description: Migrate a component from one framework to another
---

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

Запуск `/migrate-component SearchBar React Vue` заменяет `$ARGUMENTS[0]` на `SearchBar`, `$ARGUMENTS[1]` на `React` и `$ARGUMENTS[2]` на `Vue`. Тот же skill, используя сокращение `$N`:

```yaml theme={null}
---
name: migrate-component
description: Migrate a component from one framework to another
---

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

<h2 id="advanced-patterns">
  Продвинутые паттерны
</h2>

<h3 id="inject-dynamic-context">
  Внедрите динамический контекст
</h3>

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

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

```yaml theme={null}
---
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...
```

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

1. Каждый `` !`<command>` `` выполняется немедленно (перед тем, как Claude что-либо увидит)
2. Выходные данные заменяют заполнитель в содержимом skill
3. Claude получает полностью отрендеренную подсказку с фактическими данными PR

Это предварительная обработка, а не то, что Claude выполняет. Claude видит только окончательный результат.

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

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

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

````markdown theme={null}
## Environment
```!
node --version
npm --version
git status --short
```
````

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

<Tip>
  Чтобы запросить более глубокое рассуждение при запуске skill, включите `ultrathink` где-нибудь в содержимое skill. См. [Используйте ultrathink для одноразового глубокого рассуждения](/ru/model-config#use-ultrathink-for-one-off-deep-reasoning).
</Tip>

<h3 id="run-skills-in-a-subagent">
  Запустите skills в subagent
</h3>

Добавьте `context: fork` в ваш frontmatter, когда вы хотите, чтобы skill запускался в изоляции. Содержимое skill становится подсказкой, которая управляет subagent. Он не будет иметь доступ к истории вашего разговора.

<Warning>
  `context: fork` имеет смысл только для skills с явными инструкциями. Если ваш skill содержит рекомендации, такие как "используйте эти соглашения API" без задачи, subagent получает рекомендации, но не действенную подсказку, и возвращается без значимого выходного сигнала.
</Warning>

Skills и [subagents](/ru/sub-agents) работают вместе в двух направлениях:

| Подход                    | Системная подсказка    | Задача                         | Также загружает                                                 |
| :------------------------ | :--------------------- | :----------------------------- | :-------------------------------------------------------------- |
| Skill с `context: fork`   | От типа агента         | Содержимое SKILL.md            | CLAUDE.md, кроме случаев, когда агент является Explore или Plan |
| Subagent с полем `skills` | Тело markdown subagent | Сообщение делегирования Claude | Предварительно загруженные skills + CLAUDE.md                   |

С `context: fork` вы пишете задачу в своём skill и выбираете тип агента для её выполнения. Встроенные агенты Explore и Plan [пропускают CLAUDE.md и git status](/ru/sub-agents#what-loads-at-startup), чтобы сохранить их контекст небольшим, поэтому forked skill, использующий `agent: Explore`, видит только содержимое SKILL.md и собственную системную подсказку агента. Для обратного случая, где вы определяете пользовательский subagent, который использует skills как справочный материал, см. [Subagents](/ru/sub-agents#preload-skills-into-subagents).

<h4 id="example-research-skill-using-explore-agent">
  Пример: Research skill, используя Explore agent
</h4>

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

```yaml theme={null}
---
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
```

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

1. Создаётся новый изолированный контекст
2. Subagent получает содержимое skill в качестве своей подсказки ("Research \$ARGUMENTS thoroughly...")
3. Поле `agent` определяет среду выполнения (модель, инструменты и разрешения)
4. Результаты суммируются и возвращаются в ваш основной разговор

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

<h3 id="restrict-claude’s-skill-access">
  Ограничьте доступ Claude к skills
</h3>

По умолчанию Claude может вызывать любой skill, у которого не установлен `disable-model-invocation: true`. Skills, которые определяют `allowed-tools`, предоставляют Claude доступ к этим инструментам без одобрения за использование, когда skill активен. Ваши [параметры разрешений](/ru/permissions) по-прежнему управляют поведением одобрения базовой линии для всех остальных инструментов. Несколько встроенных команд также доступны через инструмент Skill, включая `/init`, `/review` и `/security-review`. Другие встроенные команды, такие как `/compact`, недоступны.

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

**Отключите все skills**, отказав в инструменте Skill в `/permissions`:

```text theme={null}
# Add to deny rules:
Skill
```

**Разрешите или запретите конкретные skills**, используя [правила разрешений](/ru/permissions):

```text theme={null}
# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)
```

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

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

<Note>
  Поле `user-invocable` управляет только видимостью меню, а не доступом инструмента Skill. Используйте `disable-model-invocation: true`, чтобы заблокировать программный вызов.
</Note>

<h3 id="override-skill-visibility-from-settings">
  Переопределите видимость skill из параметров
</h3>

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

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

| Значение                | Указано Claude | В меню `/` |
| :---------------------- | :------------- | :--------- |
| `"on"`                  | Имя и описание | Да         |
| `"name-only"`           | Только имя     | Да         |
| `"user-invocable-only"` | Скрыто         | Да         |
| `"off"`                 | Скрыто         | Скрыто     |

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

```json theme={null}
{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}
```

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

<h2 id="evaluate-and-iterate-on-a-skill">
  Оцените и улучшайте skill
</h2>

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

Проверка обоих — это сравнение базовой линии. Соберите несколько реалистичных подсказок, запустите каждую в свежей сессии с доступным skill и снова с ним [отключённым](#override-skill-visibility-from-settings), и сравните результаты. Свежая сессия важна, потому что оставшийся контекст от авторства skill будет скрывать пробелы в написанных инструкциях.

<h3 id="run-evals-with-skill-creator">
  Запустите evals с skill-creator
</h3>

Плагин [`skill-creator`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/skill-creator) автоматизирует цикл сравнения внутри Claude Code. Установите его из официального marketplace:

```text theme={null}
/plugin install skill-creator@claude-plugins-official
```

Если Claude Code сообщает, что плагин не найден ни в одном marketplace, ваш marketplace либо отсутствует, либо устарел. Запустите `/plugin marketplace update claude-plugins-official` для его обновления, или `/plugin marketplace add anthropics/claude-plugins-official`, если вы его ещё не добавили. Затем повторите попытку установки.

После установки запустите `/reload-plugins`, чтобы сделать skills плагина доступными в текущей сессии. Затем попросите Claude оценить существующий skill, например `evaluate my summarize-changes skill with skill-creator`. Плагин проведёт вас через написание тестовых случаев и запустит цикл:

* **Тестовые случаи**: сохраняет подсказки, входные файлы и ожидаемое поведение в `evals/evals.json` внутри каталога skill
* **Изолированные запуски**: порождает [subagent](/ru/sub-agents) для каждого тестового случая, чтобы каждый запуск начинался с чистого контекста, и записывает количество токенов и продолжительность
* **Оценка**: проверяет каждое утверждение против выходного сигнала и пишет pass или fail с доказательством в `grading.json`
* **Benchmark**: агрегирует процент успеха, время и токены для с-skill против без-skill в `benchmark.json`, чтобы вы могли сравнить улучшение процента успеха с накладными расходами на токены и время
* **Сравнение версий**: запускает слепой A/B между двумя версиями skill, чтобы вы могли подтвердить, что правка — это улучшение перед фиксацией
* **Настройка описания**: генерирует подсказки should-trigger и should-not-trigger, измеряет процент попаданий и предлагает правки описания, когда skill активируется на неправильных запросах
* **Средство просмотра отзывов**: открывает HTML отчёт, где вы проверяете каждый выходной сигнал и записываете качественный отзыв, который следующая итерация читает

Для формата файла eval и полного рабочего процесса итерации см. [Evaluating skill output quality](https://agentskills.io/skill-creation/evaluating-skills) на agentskills.io. Для справки о benchmark и режимах сравнения см. [объявление skill-creator](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills).

<h2 id="share-skills">
  Делитесь skills
</h2>

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

* **Project skills**: Зафиксируйте `.claude/skills/` в контроле версий
* **Plugins**: Создайте каталог `skills/` в вашем [плагине](/ru/plugins)
* **Managed**: Развёртывайте организацию-широко через [управляемые параметры](/ru/settings#settings-files)

<h3 id="generate-visual-output">
  Генерируйте визуальный выходной сигнал
</h3>

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

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

Создайте каталог Skill:

```bash theme={null}
mkdir -p ~/.claude/skills/codebase-visualizer/scripts
```

Сохраните это в `~/.claude/skills/codebase-visualizer/SKILL.md`. Описание говорит Claude, когда активировать этот Skill, а инструкции говорят Claude запустить поставляемый скрипт. Путь скрипта использует [`${CLAUDE_SKILL_DIR}`](#available-string-substitutions), поэтому он разрешается правильно независимо от того, установлен ли skill на личном, проектном или плагин-уровне:

````yaml theme={null}
---
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, но использует только встроенные библиотеки, поэтому нет пакетов для установки:

```python expandable theme={null}
#!/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>
  <script>
    const data = {json.dumps(data)};
    const colors = {json.dumps(colors)};
    function fmt(b) {{ if (b < 1024) return b + ' B'; if (b < 1048576) return (b/1024).toFixed(1) + ' KB'; return (b/1048576).toFixed(1) + ' MB'; }}
    function esc(s) {{ return s.replace(/[&<>"']/g, c => ({{"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"}}[c])); }}
    function render(node, parent) {{
      if (node.children) {{
        const det = document.createElement('details');
        det.open = parent === document.getElementById('root');
        det.innerHTML = `<summary><span class="folder">📁 ${{esc(node.name)}}</span><span class="size">${{fmt(node.size)}}</span></summary>`;
        const ul = document.createElement('ul'); ul.className = 'tree';
        node.children.sort((a,b) => (b.children?1:0)-(a.children?1:0) || a.name.localeCompare(b.name));
        node.children.forEach(c => render(c, ul));
        det.appendChild(ul);
        const li = document.createElement('li'); li.appendChild(det); parent.appendChild(li);
      }} else {{
        const li = document.createElement('li'); li.className = 'file';
        li.innerHTML = `<span class="dot" style="background:${{colors[node.ext]||'#6b7280'}}"></span>${{esc(node.name)}}<span class="size">${{fmt(node.size)}}</span>`;
        parent.appendChild(li);
      }}
    }}
    data.children.forEach(c => render(c, document.getElementById('root')));
  </script>
</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 запускает скрипт, генерирует `codebase-map.html` и открывает его в вашем браузере.

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

<h2 id="troubleshooting">
  Устранение неполадок
</h2>

<h3 id="skill-not-triggering">
  Skill не срабатывает
</h3>

Если Claude не использует ваш skill при необходимости:

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

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

<h3 id="skill-triggers-too-often">
  Skill срабатывает слишком часто
</h3>

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

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

<h3 id="skill-descriptions-are-cut-short">
  Описания skills обрезаны
</h3>

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

Начиная с версии 2.1.196, строка Skills в `/context` отображает размер списка после применения бюджета, поэтому он соответствует тому, что получает модель. В более ранних версиях подсчитывался полный текст каждого описания, поэтому строка могла показывать значение в несколько раз больше, чем бюджет, который сообщает `/doctor`.

Чтобы повысить бюджет, установите параметр [`skillListingBudgetFraction`](/ru/settings#available-settings) (например, `0.02` = 2%) или переменную окружения `SLASH_COMMAND_TOOL_CHAR_BUDGET` на фиксированное количество символов. Чтобы освободить бюджет для других skills, установите записи с низким приоритетом на `"name-only"` в [`skillOverrides`](#override-skill-visibility-from-settings), чтобы они отображались без описания. Вы также можете обрезать текст `description` и `when_to_use` в источнике: поместите ключевой вариант использования в начало, так как комбинированный текст каждой записи ограничен 1 536 символами независимо от бюджета. Лимит настраивается с помощью [`skillListingMaxDescChars`](/ru/settings#available-settings).

<h2 id="related-resources">
  Связанные ресурсы
</h2>

* **[Отладка вашей конфигурации](/ru/debug-your-config)**: диагностируйте, почему skill не появляется или не срабатывает
* **[Evaluating skill output quality](https://agentskills.io/skill-creation/evaluating-skills)**: формат файла eval и рабочий процесс итерации на agentskills.io
* **[Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)**: рекомендации по написанию, которые применяются во всех продуктах Claude
* **[Subagents](/ru/sub-agents)**: делегируйте задачи специализированным агентам
* **[Plugins](/ru/plugins)**: упакуйте и распространяйте skills с другими расширениями
* **[Hooks](/ru/hooks)**: автоматизируйте рабочие процессы вокруг событий инструментов
* **[Memory](/ru/memory)**: управляйте файлами CLAUDE.md для постоянного контекста
* **[Commands](/ru/commands)**: справочник для встроенных команд и встроенных skills
* **[Permissions](/ru/permissions)**: управляйте доступом к инструментам и skills
* **[Claude Tag skills](https://claude.com/docs/claude-tag/admins/skills-repo)**: skills проекта, зафиксированные в репозитории, также загружаются при использовании этого репозитория в канале Claude Tag
