Skills в Claude Code: как оставить нужные возможности без лишнего контекста

Как skills влияют на стартовое окно сессии

В обычной сессии Claude Code помещает в контекст список имён и description доступных skills, чтобы модель могла выбрать нужный. Полное тело SKILL.md загружается после вызова и остаётся в контексте этой сессии. Supporting files читаются по необходимости, а scripts выполняются как инструменты, а не целиком вставляются в prompt. Правила обнаружения отличаются для project, nested, plugin, synced, Cowork и cloud skills, поэтому нельзя считать простой обход одного каталога полной картиной.

Стоимость навыка в контексте складывается из трёх составляющих:

1. Системный анонс (описание и trigger): краткое имя и блок description в frontmatter файла SKILL.md. Эта часть находится в оперативной памяти агента, позволяя ему сопоставлять запрос пользователя с нужным инструментом.
2. Основное тело инструкции: детальные правила, шаги и примеры. Модель загружает их только в момент активации соответствующего навыка.
3. Вспомогательные ресурсы и скрипты: reference-файлы читаются по явному маршруту, а scripts выполняются через CLI-команды.

Основная ошибка при проектировании навыков — перенос объёмных справочников, дампов документации и жестких правил кодогенерации непосредственно в description или в глобальный CLAUDE.md. В результате базовый контекст сессии оказывается перегружен до начала работы.

При работе через собственный BetterToken API Key откройте Dashboard и сопоставьте тестовые вызовы по модели, времени, статусу, input, output и cache Token. Это помогает проверить фактический API-workflow, но не показывает, какой локальный skill занял контекст, и не заменяет /context. Актуальную настройку Claude Code сверяйте в BetterToken Docs.

Инвентаризация skills: частота и сценарии

Для оптимизации составьте список project skills (.claude/skills/) и personal skills (~/.claude/skills/). Отдельно отметьте nested skills, plugins и synced entries, которые видны в /skills: одного обхода файловой системы недостаточно для Cowork, cloud и синхронизированных конфигураций.

Сгруппируйте их по частоте применения:

Ключевой принцип: редкая процедура не обязана быть always-on. Оставьте её доступной по явному вызову, если она нужна для безопасности, восстановления или выпуска, и отключайте только после проверки реальных сценариев.

Разделение 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. Проверьте отдельно:

1. SKILL.md существует;
2. frontmatter разбирается YAML-парсером и содержит непустой description;
3. ссылки на references/, examples/ и scripts/ разрешаются от каталога skill;
4. script запускается на безопасном тестовом входе и возвращает ожидаемый exit code.

Исполняемый бит для Python-файла не обязателен, если он вызывается через python3; важнее существование файла, синтаксис и реальный тест.

Шаг 2: Проверьте видимость и явный вызов

Откройте свежую сессию, выполните /skills и подтвердите имя, источник и режим invocation. Затем вызовите /db-migrator явно на безопасной тестовой задаче. Это отделяет ошибку обнаружения от ошибки самой инструкции.

Шаг 3: Проверьте автоматический trigger

Откройте ещё одну чистую сессию и задайте вопрос, соответствующий trigger, не называя skill напрямую:

«Нужно обновить модель пользователя в схеме базы данных и проверить миграцию».

Агент должен:

1. Опознать задачу по описанию в description.
2. Загрузить тело инструкции db-migrator.
3. Предложить запуск подготовленного проверочного скрипта.

Шаг 4: Измерьте listing и стартовый контекст

Выполните /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 только потому, что они нужны редко.