Скилл не загружается в приложение 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 here | 15 | двоеточие с пробелом в описании без кавычек |
| Unexpected key(s) in SKILL.md frontmatter | 9 | поля Claude Code argument-hint и version |
| Description cannot contain angle brackets | 9 | символы < и > в описании |
| Description is too long | 5 | описание больше 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.
Запуск из терминала:
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 описывает правильную структуру так: имя папки совпадает с именем скилла, архив содержит эту папку в корне, а не файлы напрямую.
Из папки, где лежит скилл:
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 знаков. Оно длинное не просто так: туда записаны фразы, по которым агент узнаёт ситуацию. Режешь вслепую - скилл перестаёт срабатывать.
Порядок, который сохраняет узнаваемость:
Главное - в первое предложение
Что делает скилл и в какой ситуации его звать. Документация Claude Code советует ставить ключевой сценарий первым и для самого Claude Code, потому что там описание тоже обрезается, на 1536 знаках.Триггеры - самые частые
Оставить три-пять фраз, которыми ты реально формулируешь задачу. Редкие варианты убрать или перенести в тело SKILL.md, помня, что срабатывание держится на описании: тело агент читает уже после того, как выбрал скилл.Границы - одной фразой
«Не для X, это скилл Y» короче списка исключений и так же разводит похожие скиллы.Прогон валидатора
Проверить длину не на глаз: валидатор печатает число знаков, если описание длиннее нормы.
Перенести триггеры в поле when_to_use можно только для Claude Code: при загрузке в приложение это поле даст ошибку о лишнем ключе. Держать две версии одного скилла, длинную для агента и короткую для приложения, можно, но они начнут расходиться при первой же правке. Проще уложить одну версию в правила обеих сторон.
Частые вопросы
Частые вопросы
Главный вывод
Скилл в Claude Code и скилл в приложении - один и тот же SKILL.md, но с разными допусками. Claude Code принимает свои поля и длинное описание, загрузка по стандарту их не пропускает.
Поэтому порядок перед загрузкой короткий. Убрать поля, которых нет в стандарте, уложить описание в 1024 знака и взять его в кавычки, прогнать валидатор до «Skill is valid!», запаковать папку целиком и посмотреть список файлов архива. Если приложение всё равно отклоняет описание, сократи его до 200 знаков, как пишет справка.
Твои скиллы живут только в Claude Code или ты переносишь их в приложение Claude?
Источники
- Расширение Claude с помощью skills: поля заголовка и правила для загрузки в claude.ai - документация Claude Code
- Agent Skills: требования к полям name и description - документация Claude
- Agent Skills Specification - открытый стандарт формата скиллов
- How to create custom skills: структура архива и метаданные - справка Claude
- skill-creator со скриптами quick_validate.py и package_skill.py - репозиторий anthropics/skills
