Claude Skills не загружаются в субагенте: что проверить

Диагностика навыков Claude Code: предварительная загрузка, динамический вызов, каталоги и права. Готовый пример с проверкой результата и отрицательными контролями.

Две отдельные рамки для вышивания: к меньшей подведена собственная оранжевая нить

Если навык Claude работает в основном разговоре, но не в пользовательском субагенте, проверяйте отдельно обнаружение, предварительную загрузку, вызов и выполнение. Добавление Skill в список инструментов не загружает инструкции заранее. Добавление имени в skills: не даёт доступ ко всем инструментам, которые нужны этим инструкциям.

Текущая документация Claude Code описывает и загрузку навыков при запуске субагента, и их динамический вызов во время работы. Старые утверждения, что субагенты вообще не могут вызывать навыки, следует относить к конкретным версиям, а не считать универсальным правилом. Поле skills (документация на английском) загружает инструкции при старте, а инструмент Skill предоставляет другой путь — вызов во время выполнения.

Статья посвящена локальным пользовательским агентам Claude Code и навыкам проекта. Сведения сверены с официальной документацией 18 ноября 2026 года. Доступный для скачивания проект — синтетический диагностический пример редакции: мы локально проверили его файлы и скрипт проверки ожидаемого результата, но не запускали инференс модели и не измеряли долю успешных запусков. Ответы ниже — критерии проверки, а не записанный вывод Claude.

Определите этап сбоя до изменения настроек

НаблюдениеЧто проверить сначалаПолезные свидетельства
Навык недоступен и в родительской сессииОбнаружение или ограничения вызоваФактически определённое имя навыка, путь к файлу, frontmatter, политика
Родитель использует навык, а пользовательский агент игнорирует его правилаПредварительную загрузку или динамический вызовФактически выбранное определение агента, предупреждение о загрузке или вызов Skill
Вызов Skill запрещёнДоступ к инструментам и правила разрешенийКакой именно инструмент запрещён и каким правилом
Инструкции есть, но скрипт или файловая операция завершается ошибкойВыполнениеПуть, рабочий каталог, запрещённая операция, ошибка скрипта
В одной папке всё работает, в другой — нетОбласть действия или конфликт имёнКаталог запуска, корень репозитория, фактический источник навыка

Сохраните один входной пример, на котором возникает сбой, и меняйте по одному условию за запуск. Для каждого варианта создавайте новую родительскую сессию и нового субагента, чтобы предыдущие результаты не попали в следующую делегированную задачу. Не включайте маркер и ожидаемый ответ ни в текст этой задачи, ни в автоматически загружаемые инструкции проекта. Одновременное перемещение файлов, выдача доступа и изменение описания помешают понять, что именно устранило проблему. Общие понятия разобраны в руководстве по Hooks, Subagents и Skills на английском; здесь мы сосредоточимся на диагностике.

1. Создайте небольшой навык с наблюдаемым результатом

Используйте временный локальный каталог. Нужны установленный Claude Code и уже настроенное разрешённое подключение к модели. До запуска инференса запишите claude --version, модель и провайдера. Запрос к модели может расходовать ваш обычный лимит использования или API-баланс; скачивание примера само по себе не отправляет запросов.

Скачайте диагностический проект или создайте перечисленные ниже файлы. Архив содержит те же файлы, промпты, проверку результата и инструкции. Распакуйте его в новую папку, изучите содержимое и запустите Claude Code из этой папки. В примере нет хуков, сетевых вызовов или файлов с учётными данными. Код и инструкции внутри архива оставлены на английском.

skill-diagnostic/
├── .claude/
│   ├── agents/
│   │   ├── audit-preloaded.md
│   │   └── audit-dynamic.md
│   └── skills/
│       └── sample-audit/
│           └── SKILL.md
├── sample.csv
└── check_result.py

Сохраните следующий текст в .claude/skills/sample-audit/SKILL.md. Маркер позволяет заметить, применилось ли требование навыка к формату ответа. Это не механизм безопасности и не доказательство того, каким путём поступили инструкции.

---
name: sample-audit
description: Audit the synthetic sample.csv fixture and report missing amounts.
---
Read sample.csv in the working directory. Do not change any files.
Return exactly four lines, with no Markdown fences:
SKILL_MARKER=sample-audit-v1
ROWS=<number of data rows, excluding the header>
MISSING_AMOUNT_IDS=<comma-separated IDs, or none>
TOTAL_KNOWN_AMOUNT=<sum of nonempty amounts, two decimal places>
Keep IDs as text. A blank amount is missing, not zero.

Входной файл sample.csv намеренно мал:

id,amount
0007,12.50
0008,
0009,7.50

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

2. Проверьте предварительную загрузку в пользовательском агенте

Создайте .claude/agents/audit-preloaded.md:

---
name: audit-preloaded
description: Audit sample.csv using the preloaded sample-audit instructions.
tools: Read
skills:
  - sample-audit
---
Follow the preloaded audit instructions on sample.csv.
Do not read SKILL.md yourself. If the audit instructions are absent,
report PRELOAD_MISSING rather than inventing a format.

Сейчас предварительная загрузка ограничена первыми 32 различными именами в списке. Она передаёт текст навыка, а не все вспомогательные файлы из его каталога. Ни одно из этих ограничений не влияет на наш пример с одним навыком.

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

Use the audit-preloaded subagent to audit sample.csv.
Return its result verbatim. Do not perform the audit in the parent.

Убедитесь по истории выполнения, что выбран именно audit-preloaded. Этому агенту намеренно оставлен только Read: отсутствие вызова инструмента Skill в проверке предварительной загрузки нормально. Если агент напрямую прочитал SKILL.md или работу выполнил родитель, сравнение не состоялось. Это другие способы получить ответ, а не свидетельство успешной загрузки при старте.

Ожидаемый ответ:

SKILL_MARKER=sample-audit-v1
ROWS=3
MISSING_AMOUNT_IDS=0008
TOTAL_KNOWN_AMOUNT=20.00

Скопируйте только ответ этого агента в result.txt и выполните python3 check_result.py result.txt. Скрипт проверяет четыре строки результата. Он не доказывает способ загрузки, поэтому дополнительно изучите историю выполнения и отладочные данные.

Для отрицательного контроля замените sample-audit в списке skills: агента на несуществующее имя, например sample-audit-missing, затем запустите новую сессию и нового агента. Ожидаемый диагностический ответ — PRELOAD_MISSING, но точная формулировка не гарантируется. Согласно текущей документации, отсутствующие или отключённые записи пропускаются с предупреждением в отладочном журнале. Прежде чем продолжить, восстановите исходное имя. Если агент всё равно возвращает обычный результат, проверьте, не передал ли инструкции родитель, не выбран ли другой агент и нет ли маркера в другом файле.

Англоязычная официальная документация Claude Code с настройкой предварительной загрузки навыков

Снимок официальной документации для этой статьи. Это не снимок успешного запуска инференса.

3. Сравните с динамическим вызовом без предварительной загрузки

Создайте .claude/agents/audit-dynamic.md:

---
name: audit-dynamic
description: Audit sample.csv by invoking the sample-audit skill.
tools: Read, Skill
---
First invoke the sample-audit skill using the Skill tool.
Then follow it on sample.csv. Do not read SKILL.md directly.
If the skill cannot be invoked, report INVOCATION_FAILED and the reason.

В этом определении нет поля skills:. Попросите родителя делегировать задачу audit-dynamic и вернуть его ответ без изменений. Успешная проверка динамического пути требует, чтобы в истории агента был вызов Skill для sample-audit, а затем тот же результат из четырёх строк. Одного маркера недостаточно.

Теперь удалите Skill из списка tools: этого агента, не меняя остальных условий. Ожидается ошибка вызова: определение требует инструмент, которого больше нет в наборе доступных инструментов. После проверки верните Skill. Не добавляйте skills: во время этого отрицательного контроля — иначе появится отдельный путь предварительной загрузки.

Такая явная команда проверяет возможность вызова, а не самостоятельный выбор навыка моделью. Чтобы отдельно проверить выбор, создайте новое определение агента: сохраните tools: Read, Skill, но уберите прямое указание вызвать sample-audit и задайте нейтральное описание, например Audit local CSV files. Дайте обычную задачу проверки без имени навыка и посмотрите, появился ли вызов Skill. Если явный вызов работает, а самостоятельный выбор — нет, изучите описание навыка и его соответствие задаче. Успешный явный вызов не доказывает автоматический выбор.

4. Проверьте ограничения вызова и права на выполнение

Применяйте следующие изменения по одному во временном примере, каждый раз возвращаясь к исходной конфигурации:

Одно изменениеОжидаемое различиеЧто исправить
Добавить навыку disable-model-invocation: trueНавык не должен использоваться ни для динамического вызова моделью, ни для предварительной загрузкиСохранить флаг для намеренно ручных процессов; в этом эксперименте взять подходящий навык, доступный модели
Вместо этого добавить user-invocable: falseРучная команда скрывается, но сам по себе флаг не запрещает вызов модельюНе путать отсутствие в меню с недоступностью для модели
Удалить Skill из явного списка инструментов динамического агентаДинамический путь недоступен; это не относится к агенту с предварительной загрузкойОткрыть Skill там, где нужен динамический вызов
Убрать доступ к входному файлуИнструкции могут присутствовать, но чтение данных завершится ошибкойИсправить конкретное разрешение на файл или инструмент либо путь

У двух флагов вызова разные задачи; см. управление вызовом навыков на английском. Не удаляйте намеренное ограничение ручного запуска из навыка развёртывания или разрушительной операции только ради автоматического использования агентом.

Наличие инструмента в списке не означает, что любое его применение разрешено. Проверьте правила разрешений Claude Code на английском: запреты, управляемую политику и правила для конкретного имени навыка. Поле allowed-tools навыка не возвращает инструмент, исключённый из набора агента, и не отменяет запрет. Если реальный навык вызывает Python-скрипт, сначала подтвердите загрузку инструкций, затем проверяйте Bash и путь к скрипту. В нашем примере для самой проверки нужен только Read, поэтому этого дополнительного фактора нет.

Не используйте bypassPermissions как способ диагностики. Он меняет исследуемые условия и не нужен для чтения трёх строк.

5. Найдите проблемы с каталогами и именами

Прежде чем переносить навык в глобальный личный каталог, проверьте проект:

pwd
claude --version
ls -l .claude/skills/sample-audit/SKILL.md
ls -l .claude/agents/audit-preloaded.md
ls -l .claude/agents/audit-dynamic.md

Файл агента и файл навыка имеют разные задачи и лежат в разных каталогах. Файл в .claude/agents/ не становится навыком от упоминания слова «skill» в тексте. В этом примере имя папки, имя во frontmatter и запись предварительной загрузки должны совпадать. Не указывайте путь к файлу или /sample-audit в списке skills:.

В монорепозитории навык из packages/web/.claude/skills/ не равнозначен навыку в корне. Обнаружение вложенных навыков зависит от того, к какой области обращается Claude. Сначала поместите пример в корень проекта, чтобы убрать неопределённость, а затем верните настоящий подкаталог. Если команда запускает неожиданные инструкции, проверьте совпадающие имена личных и проектных навыков, а также пространства имён плагинов. Официальные правила обнаружения и именования на английском объясняют приоритет источников. Перенос всех навыков в глобальный каталог может создать новый конфликт вместо исправления исходного.

Если файл расположен в ../shared/.claude/skills/sample-audit/SKILL.md, запустите claude --add-dir ../shared и проверьте наличие навыка в новой сессии. Одно лишь permissions.additionalDirectories разрешает доступ к файлам, но не загружает навыки из этой папки. Для вложенного навыка начните с его подкаталога или используйте /add-dir в поддерживающей его версии, затем повторите вызов по имени. В отчёте об ошибке укажите каталог запуска и аргументы --add-dir. Для относительных путей к вспомогательным файлам уточните, отсчитываются ли они от каталога навыка или рабочего каталога; наш sample.csv явно использует второй вариант.

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

6. Соберите свидетельства, если минимальный пример тоже не работает

Начните новую локальную сессию с приватным файлом отладки, как описано в текущем справочнике CLI на английском:

claude --debug-file ./claude-skill-debug.log

Воспроизведите один вариант. Проверьте выбранного агента, фактическое имя навыка, предупреждения об отсутствующем или отключённом навыке, вызов Skill для динамического пути и запрещённые операции Read или Bash. Перед передачей логов просмотрите их: там могут быть пути, промпты и другие данные сессии. Не публикуйте учётные данные и постороннюю историю разговоров.

Используйте краткий шаблон отчёта. В нём нужны версия и ОС, модель и провайдер, рабочий каталог, определения, проверяемый путь, ожидаемый и фактический результат:

Claude Code version / OS:
Model / provider (no secrets):
Working directory / repository root:
Agent name and definition:
Skill name, path and frontmatter:
Route: preload OR dynamic invocation
Exact prompt and synthetic input:
Expected result / actual result:
Selected-agent evidence / relevant tool call or warning:
Single change made / result after restoring baseline:

Ошибка запуска, аутентификации, TLS или ограничения частоты возникает раньше, чем эта проверка позволяет установить поведение навыка. Такие симптомы разбираются в руководстве по TLS-ошибкам Claude Code на английском и руководстве по ограничениям частоты на английском. Повтор отклонённого запроса к модели не исправляет опечатку в имени предварительной загрузки, а правка навыка не устраняет ошибку сертификата.

А как работают context: fork, SDK и Ofox?

Навык с context: fork запускает агента для выполнения задачи навыка. Агент с skills: начинает со своих инструкций и получает дополнительное содержимое навыков. Выбирайте направление под свою задачу: это не взаимозаменяемые поля frontmatter. См. выполнение навыков в субагенте на английском.

Не рассчитывайте, что пользовательские агенты из этого примера получают всё, что вы обсуждали с родителем. Передавайте необходимые входные данные явно. Claude Code описывает и другие варианты fork; нельзя переносить изоляцию этого примера на каждый вид агента или ответвления разговора.

При запуске через Claude Agent SDK отдельно проверьте настройки файловой системы и инструмента Skill в документации SDK по навыкам на английском. То, что терминальная сессия обнаружила локальный навык, не доказывает, что SDK-процесс из другого каталога загружает ту же конфигурацию.

Если вы уже подключаете Claude Code через Ofox, конфигурацию подключения смотрите в документации интеграции Claude Code, а сбои API — в справочнике обработки ошибок. Связь с провайдером и загрузка локальных навыков проверяются отдельно. Смена API-эндпоинта сама по себе не открывает функции аккаунта Claude и не исправляет локальное определение агента.

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