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

Встроенные skills

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Your skill instructions here...

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

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

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

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

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

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

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

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

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

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

$ARGUMENTS

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

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)

## Additional resources

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Правила запрета и запроса: команда, соответствующая одному из них, всё равно прерывает вызов. Чтобы найти это правило, см. Управление разрешениями.
• Только управляемые правила: если /status в сессии показывает скилл в разделе allowed-tools ignored this session, см. Когда применяются только управляемые правила разрешений.
• Непроверенные папки Git: там, где файл HEAD или .git может принадлежать не вам, Claude Code игнорирует allowed-tools для команды Bash, которая содержит git или которую Claude Code не может разобрать. Если вы доверяете папке, например worktree вашего собственного bare-репозитория, разрешите команду с помощью /permissions в сессии.

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

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

Пример: исследовательский скилл с агентом 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. Субагент обобщает свои результаты и возвращает их в ваш основной диалог по завершении

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

# Add to deny rules:
Skill

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

# Deny specific skills
Skill(deploy *)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#!/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()}')

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

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

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

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

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

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

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

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

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

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

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

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

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