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

Ошибка загрузки скилла в Claude: что значат frontmatter, 1024 знака и один SKILL.md в архиве, почему скилл из Claude Code не проходит и как проверить заранее.

URL: https://posts.danashkin.ru/guides/oshibki-zagruzki-skilla-v-claude
Обновлено: 2026-11-15

---

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

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

**Главное**

У Claude Code и у приложения разные правила для одного и того же файла. Claude Code принимает свои дополнительные поля, а длинное описание просто обрезает в списке скиллов. Загрузка в приложение проверяет файл по стандарту Agent Skills, и лишнее поле или длинное описание дают жёсткую ошибку.

Скилл - инструкция, которую [ИИ-агент](/concepts/ai-agent) подхватывает сам, когда узнаёт ситуацию по описанию; [подробнее о том, когда задачу пора превращать в инструкцию](/guides/zadacha-povtorilas-tretiy-raz). Здесь речь о другом: скилл уже есть, и его нужно перенести из 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 не может подобрать его по описанию. Кавычки вокруг описания нужны и там.

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

**Главное**

Каждая ошибка называет одно правило формата: заголовок в первой строке, предел длины описания, один SKILL.md в архиве, только поля стандарта. Чинится каждая правкой в одном месте файла или архива.

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

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

**Главное**

Прогнать папку скилла через quick_validate.py из репозитория anthropics/skills. Ему нужна библиотека pyyaml, удобнее всего во временном окружении. Он выдаёт «Skill is valid!» или первую найденную ошибку, поэтому гонять его нужно до чистого ответа.

Валидатор лежит в скилле 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 при этом не трогается. Третья проверяет папку скилла. Если терминал пугает, это нормально: что в нём происходит, разобрано в статье [терминал для непрограммиста](/guides/terminal-dlya-neprogrammista). А можно попросить агента выполнить эти три команды за тебя.

Чтобы увидеть, что валидатор ловит, 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!». Чего он не проверяет: совпадает ли имя с названием папки и как собран архив. Это следующий шаг.

Если ответ валидатора непонятен, принеси агенту текст ошибки целиком и путь к папке, без пересказа своими словами. Как подать ошибку, чтобы её починили с первого раза, есть в статье [как принести агенту ошибку](/guides/kak-prinesti-agentu-oshibku). Сам skill-creator на моём обучении работе с ИИ-агентами ставят в первом модуле, вместе с другими базовыми скиллами и после проверки безопасности. Если хочешь собирать свои скиллы под присмотром и с разбором таких ошибок, это программа [обучения работе с ИИ-агентами](https://danashkin.ru/agents/).

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

**Главное**

Архивировать папку скилла целиком, а не её содержимое: в корне архива должна лежать папка с именем скилла, внутри неё SKILL.md. Перед загрузкой открыть список файлов архива командой unzip -l и убедиться, что 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`.

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

**Главное**

Описание решает, позовёт ли агент скилл, поэтому сокращать его надо с головы: первым - что делает и когда звать, фразы-триггеры потом. Поле when_to_use в приложение не загрузить, значит всё нужное для узнавания должно уместиться в описание: до 1024 знаков по стандарту и до 200 по справке приложения.

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

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

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

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

2. **Триггеры - самые частые**

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

3. **Границы - одной фразой**

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

4. **Прогон валидатора**

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

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

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

**Главное**

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

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

**Можно ли назвать скилл по-русски?**

В поле `name` по стандарту и по валидатору - только строчная латиница, цифры и дефис, например `svodka-za-nedelyu`. Русский текст пишется в описании и в теле скилла, там ограничений на язык нет.

**Где включить скилл после загрузки?**

По справке Claude - в разделе Customize, Skills. Для работы скиллов в приложении должно быть включено выполнение кода. После включения дай несколько запросов, которые должны его вызвать, и посмотри, подхватил ли его Claude.

**Нужно ли уметь программировать, чтобы проверить скилл?**

Нет. Три команды из раздела про валидатор можно выполнить самому или поручить агенту: «проверь папку скилла валидатором из skill-creator и исправь ошибки, которые он найдёт». Результат проверяй по финальному «Skill is valid!» и по списку файлов архива.

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

**Главное**

Частая причина ошибки загрузки - файл, написанный под Claude Code, где допускается больше, чем при загрузке. Валидатор Anthropic ловит перечисленные в статье правила формата, а приложение может проверять и больше.

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

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

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

### Источники

- [Расширение Claude с помощью skills: поля заголовка и правила для загрузки в claude.ai - документация Claude Code](https://code.claude.com/docs/ru/skills)
- [Agent Skills: требования к полям name и description - документация Claude](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
- [Agent Skills Specification - открытый стандарт формата скиллов](https://agentskills.io/specification)
- [How to create custom skills: структура архива и метаданные - справка Claude](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills)
- [skill-creator со скриптами quick_validate.py и package_skill.py - репозиторий anthropics/skills](https://github.com/anthropics/skills/tree/main/skills/skill-creator)
