Skills в Claude Code: как оставить нужные возможности без лишнего контекста
Практический аудит skills в Claude Code: как разделить always-on правила и контекст по требованию, настроить triggers и проверить обнаружение инструмента.
Содержание
При активном использовании Claude Code каталог пользовательских расширений и инструкций быстро разрастается: специализированные скрипты, правила форматирования, проверки типов и шаблоны для отдельных фреймворков. Если подключать каждый инструмент как постоянную инструкцию, сессия начинает расходовать системный лимит контекста ещё до первого содержательного запроса. В этом материале разберём, как провести инвентаризацию skills, отделить постоянные правила от вызываемых по требованию и протестировать корректность их обнаружения моделью.
Как skills влияют на стартовое окно сессии
В обычной сессии Claude Code помещает в контекст имя и description skills со статусом on, чтобы модель могла выбрать нужный. В режиме name-only остаётся только имя; user-invocable-only или disable-model-invocation: true скрывают описание от модели, а off скрывает skill полностью. Полное тело SKILL.md загружается после вызова и остаётся в контексте этой сессии. Supporting files читаются по необходимости, а scripts выполняются как инструменты, а не целиком вставляются в prompt. Эти правила описаны в официальной документации Claude Code Skills.
Стоимость навыка в контексте складывается из трёх составляющих:
- Системный анонс (описание и trigger): краткое имя и блок
descriptionв frontmatter файлаSKILL.md. Эта часть находится в оперативной памяти агента, позволяя ему сопоставлять запрос пользователя с нужным инструментом. - Основное тело инструкции: детальные правила, шаги и примеры. Модель загружает их только в момент активации соответствующего навыка.
- Вспомогательные ресурсы и скрипты: reference-файлы читаются по явному маршруту, а scripts выполняются через CLI-команды.
Основная ошибка при проектировании навыков — перенос объёмных справочников, дампов документации и жестких правил кодогенерации непосредственно в description или в глобальный CLAUDE.md. В результате базовый контекст сессии оказывается перегружен до начала работы.
При работе через собственный BetterToken API Key откройте Dashboard и сопоставьте тестовые вызовы по модели, времени, статусу, input, output и cache Token. Это помогает проверить фактический API-workflow, но не показывает, какой локальный skill занял контекст, и не заменяет /context. Актуальную настройку Claude Code сверяйте в BetterToken Docs.
Skills становится слишком много: начните с /skill-doctor
Когда список уже трудно оценить вручную, запустите /skill-doctor в локальной сессии Claude Code. Команда показывает стоимость skills в контексте и частоту вызовов, выделяя загруженные, но не использованные навыки. Интерактивный отчёт открывается на вкладке Stats менеджера /plugin; он не охватывает встроенные и корпоративные skills. См. описание отчёта.
Используйте отчёт как начало проверки:
- Выберите проект, где регулярно работаете, и сопоставьте список с его типичными задачами. Отсутствие вызовов ещё не означает, что skill бесполезен: процедура восстановления может понадобиться раз в несколько месяцев.
- Для редко нужного personal или project skill выберите в
/skillsрежимuser-invocable-only(меткаuser-only). Если навык больше не нужен в этом окружении —off. Plugin skills управляйте через/plugin. - Откройте новую сессию, сравните
/contextи выполните одну обычную задачу плюс явный вызов оставленного редкого skill. Снижение контекста полезно, только если нужный сценарий сохранился.
Команда отмечена в релизе v2.1.261, но текущая документация указывает минимум v2.1.252. Проверьте свою версию через claude --version: доступность также зависит от загрузки feature flags. Через Remote Control отчёт недоступен — запускайте его в терминале машины, где работает сессия. Если команды нет, продолжайте ручную инвентаризацию ниже.
Инвентаризация skills: частота и сценарии
Для оптимизации составьте список project skills (.claude/skills/) и personal skills (~/.claude/skills/). Nested skill становится доступен после первого чтения или изменения файла в соответствующем подкаталоге, а не обязательно при старте. Plugin skill использует namespace плагина и не управляется через skillOverrides. Synced skill обнаруживается по-разному в локальной сессии, Cowork и cloud. Поэтому сопоставляйте файловый инвентарь с /skills в каждом реально используемом окружении.
Сгруппируйте их по частоте применения:
| Категория частоты | Примеры задач | Оптимальное размещение |
|---|---|---|
| Ежедневные (Always-on) | Базовый code style, запуск тестов, проверка git status | Компактные правила в CLAUDE.md или базовый skill |
| Ситуативные (Task-triggered) | Миграция базы данных, генерация OpenAPI клиентов, релизные чеклисты | Отдельный skill с узким description |
| Редкие / Архитектурные | Первичный аудит безопасности, развёртывание нового сервиса | Отдельный skill в режиме user-only с явной командой и scripts |
Ключевой принцип: редкая процедура не обязана быть always-on. Оставьте её доступной по явному вызову, если она нужна для безопасности, восстановления или выпуска, и отключайте только после проверки реальных сценариев.
Куда перенести правило, которое не должно быть всегда в контексте
Возьмите одну задачу: обновлять сгенерированную документацию через исходники и генератор. Её части требуют разных механизмов:
| Что требуется | Где разместить | Что проверить |
|---|---|---|
| Напоминать о способе обновления почти в каждой задаче | Короткое правило в CLAUDE.md | Файл действительно загружен в новую сессию |
| Выполнять процедуру только при обновлении документации | Отдельный skill | Явный вызов находит источник и документированную команду генератора |
| Отклонять конкретную попытку записи до выполнения | Hook PreToolUse | Нужный инструмент получает отказ, файл не меняется |
| Независимо проверить результат | Subagent с необходимыми инструментами | Отчёт содержит проверку; права не шире задачи |
| Получать данные из внешней системы | MCP-соединение | Доступен нужный сервер и один разрешённый запрос |
CLAUDE.md и skill дают модели инструкции. Наличие фразы «не редактировать generated» ещё не доказывает, что запись заблокирована. У Hook нужно проверить событие, matcher и фактический отказ: запрет для Write не ограничивает запись через Bash. Отдельный контекст subagent тоже не делает его автоматически read-only. Эти различия описаны в обзоре механизмов и справочнике Hooks.
Не переносите одну процедуру целиком во все пять мест. Оставьте в CLAUDE.md короткое правило и ссылку на skill, а проверку действия оформите отдельно там, где она нужна. Для примеров используйте уже разобранные правила CLAUDE.md, проверку завершения через Stop Hook и выбор MCP или команды. Stop Hook проверяет завершение работы; он не заменяет проверку до записи через PreToolUse.
Разделение Always-on правил и фоновых ресурсов
Чтобы снизить нагрузку на контекст, разделите логику навыка на компактную точку входа и вызываемые по требованию исполняемые файлы.
1. Оптимизация YAML frontmatter
Поле description должно содержать чёткие условия срабатывания (trigger terms) и краткую суть, избегая общих рассуждений:
---
name: db-migrator
description: >-
Используется для проверки и применения миграций Prisma при изменении схемы базы данных.
---Избегайте длинных списков примеров кода в самом заголовке. Подробные таблицы и примеры выносите в подкаталог references/.
2. Делегирование логики детерминированным скриптам
Вместо того чтобы заставлять LLM генерировать сложные команды парсинга или валидации по длинной текстовой инструкции, поместите логику в shell- или Python-скрипт в каталоге scripts/:
<!-- Внутри SKILL.md -->
Для проверки целостности схемы запустите:
```bash
python3 "${CLAUDE_SKILL_DIR}/scripts/validate_schema.py" --strict
```Так SKILL.md хранит маршрут и критерии, а повторяемую проверку выполняет один версионируемый script. Это улучшает воспроизводимость, если script сам протестирован и вызывается с одинаковыми входами. Никогда не отключайте обязательные проверки безопасности, линтеры или валидаторы типов ради экономии Token.
Тестирование обнаружения и контроль вызовов
После реструктуризации навыков проверьте, что модель продолжает корректно идентифицировать и подгружать нужные инструкции.
Шаг 1: Разделите четыре проверки
Не подменяйте валидацию YAML командой test -f. Проверьте отдельно:
SKILL.mdсуществует;- frontmatter разбирается YAML-парсером и содержит непустой
description; - ссылки на
references/,examples/иscripts/разрешаются от каталога skill; - script запускается на безопасном тестовом входе и возвращает ожидаемый exit code.
Исполняемый бит для Python-файла не обязателен, если он вызывается через python3; важнее существование файла, синтаксис и реальный тест.
Шаг 2: Проверьте видимость и явный вызов
Откройте свежую сессию, выполните /skills и подтвердите имя, источник и режим invocation. Затем вызовите /db-migrator явно на безопасной тестовой задаче. Это отделяет ошибку обнаружения от ошибки самой инструкции.
Шаг 3: Проверьте автоматический trigger
Откройте ещё одну чистую сессию и задайте вопрос, соответствующий trigger, не называя skill напрямую:
«Нужно обновить модель пользователя в схеме базы данных и проверить миграцию».
Агент должен:
- Опознать задачу по описанию в
description. - Загрузить тело инструкции
db-migrator. - Предложить запуск подготовленного проверочного скрипта.
Шаг 4: Измерьте listing и стартовый контекст
Используйте /skill-doctor для поиска неиспользуемых skills, как описано выше. Выполните /doctor: текущая документация Claude Code рекомендует его для оценки стоимости skill listing и крупнейших contributors. Затем выполните /context и запишите размер строки Skills. После одного изменения — например, сокращения description или перевода редкого skill в user-only — повторите те же команды в новой сессии.
Сравнивайте не только Token, но и качество: should-trigger запрос должен вызвать нужный skill, should-not-trigger — не вызвать его, а проверка задачи должна пройти. Классифицируйте записи как always-on, auto-triggered, user-only, name-only или off. Не удаляйте security и recovery skills только потому, что они нужны редко.
