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, но точная формулировка не гарантируется. Согласно текущей документации, отсутствующие или отключённые записи пропускаются с предупреждением в отладочном журнале. Прежде чем продолжить, восстановите исходное имя. Если агент всё равно возвращает обычный результат, проверьте, не передал ли инструкции родитель, не выбран ли другой агент и нет ли маркера в другом файле.

Снимок официальной документации для этой статьи. Это не снимок успешного запуска инференса.
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 и не исправляет локальное определение агента.
Критерий завершения должен быть конкретным: запущен нужный агент, виден нужный путь загрузки, четыре строки ответа соответствуют примеру, а отрицательный контроль даёт другое поведение. Сохраните эти свидетельства, прежде чем возвращать в проект весь рабочий процесс.


