Дмитрий Анашкин

Скилл не загружается в Claude: что значат ошибки архива и как проверить его до загрузки

Опубликовано 8 нояб. 2026 г.Обновлено 15 нояб. 2026 г.9 мин чтенияНачальный
Расстёгнутая папка-архив с вложенными файлами и лупой
Туториал
Скилл не загружается в Claude
Дмитрий Анашкин · 9 мин
Чему вы научитесь
  • Что означает каждая ошибка загрузки скилла и как её исправить
  • Как проверить скилл валидатором Anthropic до загрузки
  • Как собрать архив с одной папкой и одним SKILL.md
Начальный
2просмотров

Скилл не загружается в приложение Claude, когда архив не проходит проверку формата Agent Skills. Файл SKILL.md должен начинаться с заголовка YAML, в заголовке стоять только поля из стандарта, а в архиве лежать одна папка скилла с одним SKILL.md. С длиной описания источники расходятся: стандарт Agent Skills и текст ошибки называют 1024 знака, справка приложения - 200. Загрузку в приложение для этой статьи я не проверял, поэтому надёжнее уложиться в 200. Claude Code к тем же файлам допускает больше, поэтому скилл, который работает у агента на компьютере, при загрузке в приложение получает ошибку на английском. Поймать её заранее можно валидатором из открытого репозитория Anthropic.

Почему скилл из Claude Code не загружается в приложение?

Скилл - инструкция, которую ИИ-агент подхватывает сам, когда узнаёт ситуацию по описанию; подробнее о том, когда задачу пора превращать в инструкцию. Здесь речь о другом: скилл уже есть, и его нужно перенести из Claude Code в приложение Claude.

Документация Claude Code перечисляет различия прямо. В Claude Code все поля заголовка необязательны, незнакомое поле игнорируется без ошибки, а описание вместе с полем when_to_use обрезается в списке скиллов на 1536 знаках. Загрузка скилла в claude.ai, Skills API и упаковка скриптом package_skill.py разрешают в заголовке только шесть полей: name, description, license, compatibility, metadata, allowed-tools. Любое другое поле - жёсткая ошибка, а не предупреждение.

Замер на моих скиллах, 31 октября 2026 года. В моей папке скиллов Claude Code их 90, все написаны под Claude Code. У 15 описание больше 1024 знаков, самое длинное - 1477. Копии всех 90 прогнаны через валидатор Anthropic. Прошли 52, остальные 38 он остановил на первой найденной ошибке:

Первая ошибка валидатораСкилловОткуда взялась
Invalid YAML: mapping values are not allowed here15двоеточие с пробелом в описании без кавычек
Unexpected key(s) in SKILL.md frontmatter9поля Claude Code argument-hint и version
Description cannot contain angle brackets9символы < и > в описании
Description is too long5описание больше 1024 знаков

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

Расшифровка ошибок архива

Тексты ошибок приложения ниже взяты так, как люди вбивают их в поиск, а объяснения выведены из текста ошибки и правил формата: в приложение я эти архивы не загружал. Текст про лишние поля - из документации Claude Code.

ОшибкаЧто не такЧто сделать
skill.md must start with yaml frontmatterпервая строка файла - не ---: перед ней пустая строка, текст или заголовка нет вовсепервой строкой поставить ---, за ней name и description, закрыть вторым ---
field description in skill.md must be at most 1024 charactersописание больше 1024 знаковсократить, главное назначение - в начало (ниже); справка приложения называет предел 200 знаков, поэтому надёжнее уложиться в 200
zip must contain exactly one skill.md fileв архиве нет SKILL.md внутри папки скилла или их несколькоодин скилл - один архив, папка скилла в корне архива
Unexpected key(s) in SKILL.md frontmatter: argument-hintв заголовке поле, которого нет в стандартеоставить только шесть полей стандарта

Ещё два правила валидатор проверяет, а в поиске они встречаются реже. Имя скилла в поле name - до 64 знаков, только строчная латиница, цифры и дефис, без дефиса в начале и в конце и без двух дефисов подряд. Описание - без угловых скобок: документация Anthropic запрещает в нём XML-теги. И ещё одно правило из документации Agent Skills: в имени нельзя использовать слова anthropic и claude.

Двоеточие стоит запомнить отдельно. Фраза «Когда звать: прислали выгрузку» в описании без кавычек для строгого YAML выглядит как ещё одно поле, и разбор падает. Лечится кавычками вокруг всего описания.

Как проверить скилл до загрузки?

Валидатор лежит в скилле skill-creator в открытом репозитории Anthropic: skills/skill-creator/scripts/quick_validate.py. Если skill-creator у тебя уже стоит, скрипт есть и на диске, в его папке scripts.

Запуск из терминала:

bash
python3 -m venv ~/skill-check
~/skill-check/bin/pip install pyyaml
~/skill-check/bin/python ~/.claude/skills/skill-creator/scripts/quick_validate.py ~/Desktop/svodka-za-nedelyu

Первые две строки создают отдельное окружение и ставят туда библиотеку для чтения YAML, системный Python при этом не трогается. Третья проверяет папку скилла. Если терминал пугает, это нормально: что в нём происходит, разобрано в статье терминал для непрограммиста. А можно попросить агента выполнить эти три команды за тебя.

Чтобы увидеть, что валидатор ловит, 31 октября собран учебный скилл «сводка за неделю» и четыре его сломанные копии. Результат прогона:

КопияЧто сломаноОтвет валидатора
исходнаяничегоSkill is valid!
1пустая строка перед ---No YAML frontmatter found
2двоеточие в описании без кавычекInvalid YAML in frontmatter: mapping values are not allowed here
3поле argument-hint в заголовкеUnexpected key(s) in SKILL.md frontmatter: argument-hint
4описание на 1122 знакаDescription is too long (1122 characters). Maximum is 1024 characters.

Валидатор останавливается на первой ошибке. Исправил одну - запусти снова, пока не появится «Skill is valid!». Чего он не проверяет: совпадает ли имя с названием папки и как собран архив. Это следующий шаг.

Если ответ валидатора непонятен, принеси агенту текст ошибки целиком и путь к папке, без пересказа своими словами. Как подать ошибку, чтобы её починили с первого раза, есть в статье как принести агенту ошибку. Сам skill-creator на моём обучении работе с ИИ-агентами ставят в первом модуле, вместе с другими базовыми скиллами и после проверки безопасности. Если хочешь собирать свои скиллы под присмотром и с разбором таких ошибок, это программа обучения работе с ИИ-агентами.

Как собрать архив, чтобы в нём был один SKILL.md?

Справка Claude описывает правильную структуру так: имя папки совпадает с именем скилла, архив содержит эту папку в корне, а не файлы напрямую.

Из папки, где лежит скилл:

bash
zip -r svodka-za-nedelyu.zip svodka-za-nedelyu -x "*.DS_Store"
unzip -l svodka-za-nedelyu.zip

Правильный архив в списке выглядит так: строка svodka-za-nedelyu/ и строка svodka-za-nedelyu/SKILL.md. Если запаковать содержимое изнутри папки, в списке будет голый SKILL.md без папки, а справка такую структуру называет неправильной.

Две ловушки, которые видно только в списке файлов:

  • Несколько скиллов в одном архиве. Запаковал общую папку со всеми скиллами - в архиве десятки SKILL.md. Один скилл - один архив.
  • Служебная папка macOS. Архив, собранный средствами macOS с сохранением атрибутов файлов, может нести папку __MACOSX. В проверочном прогоне команда ditto в таком режиме добавила в архив файл __MACOSX/svodka-za-nedelyu/._SKILL.md. Как приложение посчитает его, без загрузки проверить нельзя, поэтому надёжнее собирать архив командой zip и смотреть список.

Скрипт package_skill.py из того же skill-creator делает оба шага сразу: сначала прогоняет валидатор, при ошибке архив не собирает, при успехе кладёт папку скилла в архив с расширением .skill. На учебном скилле внутри оказался ровно один файл, svodka-za-nedelyu/SKILL.md.

Длинное описание: что сократить и что оставить

Самый болезненный случай - описание больше 1024 знаков. Оно длинное не просто так: туда записаны фразы, по которым агент узнаёт ситуацию. Режешь вслепую - скилл перестаёт срабатывать.

Порядок, который сохраняет узнаваемость:

  1. Главное - в первое предложение

    Что делает скилл и в какой ситуации его звать. Документация Claude Code советует ставить ключевой сценарий первым и для самого Claude Code, потому что там описание тоже обрезается, на 1536 знаках.
  2. Триггеры - самые частые

    Оставить три-пять фраз, которыми ты реально формулируешь задачу. Редкие варианты убрать или перенести в тело SKILL.md, помня, что срабатывание держится на описании: тело агент читает уже после того, как выбрал скилл.
  3. Границы - одной фразой

    «Не для X, это скилл Y» короче списка исключений и так же разводит похожие скиллы.
  4. Прогон валидатора

    Проверить длину не на глаз: валидатор печатает число знаков, если описание длиннее нормы.

Перенести триггеры в поле when_to_use можно только для Claude Code: при загрузке в приложение это поле даст ошибку о лишнем ключе. Держать две версии одного скилла, длинную для агента и короткую для приложения, можно, но они начнут расходиться при первой же правке. Проще уложить одну версию в правила обеих сторон.

Частые вопросы

Частые вопросы

Главный вывод

Скилл в Claude Code и скилл в приложении - один и тот же SKILL.md, но с разными допусками. Claude Code принимает свои поля и длинное описание, загрузка по стандарту их не пропускает.

Поэтому порядок перед загрузкой короткий. Убрать поля, которых нет в стандарте, уложить описание в 1024 знака и взять его в кавычки, прогнать валидатор до «Skill is valid!», запаковать папку целиком и посмотреть список файлов архива. Если приложение всё равно отклоняет описание, сократи его до 200 знаков, как пишет справка.

Твои скиллы живут только в Claude Code или ты переносишь их в приложение Claude?

Источники

Отправь другу или себе в избранное в Telegram, чтобы не потерять.

Поделиться в Telegram
Было полезно?
Автор
Дмитрий Анашкин
Практик-интегратор ИИ в бизнес

Основатель NeuroDA и SMAIPL. Корпоративные воркшопы по ИИ, внедрение AI в бизнес-процессы.

Похожие гайды

Альтернативы Claude Code в 2026: OpenCode, Qwen Code и GigaCode - в чём уступают и когда хватает

С 12 ноября 2026 года Anthropic отдельно прописал правило для компаний из неподдерживаемых регионов и их сотрудников. Сравниваю три альтернативы Claude Code: модель, куда уходят данные, лицензия, что проверить. Показываю, когда замены хватает и как проверить её за вечер на своей задаче.

12 мин

Мультиагентные системы: как несколько ИИ работают над одной задачей

Одна модель тянет простую задачу, но сложный проект требует команды. Разбираем, как мультиагентные системы делят работу между несколькими ИИ, какие архитектуры для этого есть и когда несколько агентов реально нужны, а когда это лишнее усложнение.

12 мин

Замена ИИ-модели: как проверить её на своих задачах до перехода

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

9 мин

Мониторинг задач по расписанию: как поймать сбой, если скрипт молчит

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

8 мин

Связанные понятия