Полное руководство по созданию Skills для Claude

Введение

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

Skills особенно полезны для повторяющихся задач: собрать фронтенд по макету, провести ресёрч по единому шаблону, оформить документ по стандартам команды, пройти многоэтапный процесс шаг за шагом. Они отлично сочетаются со встроенными возможностями (запуском кода и генерацией документов). А если вы уже работаете с MCP-интеграциями, skills добавят слой экспертизы поверх инструментов и превратят голый доступ к API в отлаженные рабочие процессы.

Чему вы научитесь

• Как устроен skill технически и какие требования к структуре
• Какие паттерны работают для автономных skills и для связки с MCP
• Какие подходы показали себя лучше всего на практике
• Как тестировать, дорабатывать и публиковать свои skills

Для кого это

• Разработчики, которым нужно, чтобы Claude стабильно следовал определённому процессу
• Продвинутые пользователи, которым важна воспроизводимость результатов
• Команды, которые хотят стандартизировать работу с Claude у себя в организации

После прочтения вы сможете собрать свой первый рабочий skill за одну сессию. С помощью skill-creator это займёт примерно 15-30 минут.

Что такое skill?

Skill — это обычная папка, внутри которой лежат:

• SKILL.md (обязательный): главный файл с инструкциями в формате Markdown + YAML frontmatter
• scripts/ (опционально): скрипты на Python, Bash и т.д.
• references/ (опционально): справочные материалы, которые Claude подгрузит при необходимости
• assets/ (опционально): шаблоны, шрифты, иконки и другие ресурсы

Принципы, на которых всё построено

Progressive Disclosure

Skills устроены как матрёшка из трёх уровней:

• Первый уровень, YAML frontmatter: всегда на виду у Claude в системном промпте. Это «визитная карточка» skill: достаточно информации, чтобы понять, когда его подключать, но без лишней нагрузки на контекст.
• Второй уровень, тело SKILL.md: подгружается, когда Claude решает, что skill подходит к текущей задаче. Здесь лежат полные инструкции.
• Третий уровень, вложенные файлы: дополнительные материалы из папки skill, которые Claude подтянет сам, если понадобятся.

За счёт этого расход токенов минимален, а экспертиза всегда под рукой.

Совместимость (Composability)

Claude может загрузить сразу несколько skills. Поэтому ваш skill не должен вести себя так, будто он единственный. Пишите его с расчётом на совместную работу с другими.

Портативность (Portability)

Один и тот же skill работает в Claude.ai, Claude Code и через API без каких-либо правок. Единственное условие: среда должна поддерживать зависимости, которые нужны вашему skill.

Skills + MCP-коннекторы

Аналогия с кухней

MCP — это профессиональная кухня: плита, ножи, продукты, всё оборудование.
Skills — это рецепты: пошаговые инструкции, как из всего этого приготовить что-то стоящее.

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

Без skills

• Пользователь подключил MCP и завис: непонятно, с чего начать
• В поддержку летят вопросы: «а как мне сделать X через вашу интеграцию?»
• Каждый новый разговор начинается с чистого листа
• Результаты пляшут, каждый формулирует запросы по-своему

Со skills

• Готовые сценарии подключаются автоматически, когда нужно
• Инструменты используются стабильно и предсказуемо
• Лучшие практики зашиты в каждое взаимодействие
• Порог входа для новых пользователей резко снижается

Начните со сценариев использования

Прежде чем писать код, сформулируйте 2-3 конкретных сценария, которые ваш skill должен закрывать.

Ответьте себе на четыре вопроса:

• Какую задачу хочет решить пользователь?
• Из каких шагов складывается процесс?
• Какие инструменты понадобятся: встроенные или через MCP?
• Какую предметную экспертизу стоит зашить в skill?

Три типичные категории skills

Как понять, что skill работает

Это ориентиры, а не жёсткие пороги. Часть оценки неизбежно будет субъективной — и это нормально.

Цифры

• Skill подключается в 90% подходящих запросов
  Как проверить: прогоните 10-20 тестовых запросов. Посчитайте, в скольких случаях skill загрузился сам, без ручного вызова.
• Рабочий процесс укладывается в X вызовов инструментов
  Как проверить: дайте одну и ту же задачу с включённым skill и без. Сравните число вызовов и расход токенов.
• Ни одного сбойного API-вызова за весь процесс
  Как проверить: смотрите логи MCP-сервера во время тестовых прогонов.

Ощущения

• Пользователю не приходится подсказывать Claude, что делать дальше
• Процесс доходит до конца без ручных правок
• Результаты воспроизводимы от сессии к сессии

Технические требования

Структура файлов

Железные правила

Файл SKILL.md:

• Имя ровно SKILL.md, регистр важен
• Никакие вариации не пройдут: ни SKILL.MD, ни skill.md

Имя папки:

README.md внутри skill не нужен. Вся документация лежит в SKILL.md или references/. README понадобится позже, на уровне репозитория, для людей, а не для Claude.

YAML frontmatter: самое важное в skill

Именно по YAML-шапке Claude решает, подключать ваш skill или нет. Здесь нельзя ошибиться.

Минимально рабочий вариант

---
name: your-skill-name
description: Что делает. Подключать, когда пользователь просит [конкретные фразы].
---

Этого достаточно для старта.

Обязательные поля

name:

• Только kebab-case (строчные через дефис)
• Без пробелов и заглавных
• Должно совпадать с именем папки

description:

• Обязательно содержит две вещи: что skill делает и когда его подключать
• Не больше 1024 символов
• Никаких XML-тегов (< или >)
• Перечислите конкретные фразы, которые может сказать пользователь
• Укажите типы файлов, если это важно

Опциональные поля

• license: лицензия для открытых skills (MIT, Apache-2.0)
• compatibility: требования к окружению (1-500 символов)
• metadata: произвольные поля: автор, версия, mcp-server и т.д.

Ограничения безопасности

Во frontmatter запрещены:

• XML-угловые скобки (< >)
• Слова «claude» или «anthropic» в имени skill (зарезервированы)

Шапка попадает прямо в системный промпт Claude, поэтому вредоносный контент мог бы подменить инструкции.

Как писать описание

Формула: [Что делает] + [Когда подключать] + [Ключевые возможности]

Как писать инструкции

После YAML-шапки идёт тело skill, обычный Markdown. Вот рекомендуемый каркас:

---
name: your-skill
description: [...]
---

# Название Skill

## Инструкции

### Шаг 1: [Первый шаг]
Что конкретно нужно сделать.

Пример:
```bash
python scripts/fetch_data.py --project-id PROJECT_ID
```
Если всё прошло хорошо: [описание результата]

## Примеры

### Пример 1: [типичная ситуация]
Пользователь: "Создай новую маркетинговую кампанию"
Действия:
1. Забрать существующие кампании через MCP
2. Создать новую с указанными параметрами
Результат: кампания создана, ссылка для подтверждения отправлена

## Если что-то пошло не так

Ошибка: [текст ошибки]
Почему: [причина]
Что делать: [решение]

Как писать инструкции, которые работают

Запустите `python scripts/validate.py --input {filename}`
для проверки формата.
Если не прошло, типичные причины:
- Не хватает обязательных полей (допишите в CSV)
- Даты в неправильном формате (нужен YYYY-MM-DD)

Проверьте данные перед тем как продолжить.

Не забывайте про обработку ошибок и ссылки на справочные файлы. Главное правило: SKILL.md содержит суть, а детали выносите в references/.

Как тестировать

Глубина тестирования зависит от задачи:

• Вручную в Claude.ai: просто задаёте вопросы и смотрите, что происходит. Быстро, без настройки.
• Скриптами в Claude Code: автоматизированные тест-кейсы для повторяемой проверки после каждого изменения.
• Программно через Skills API: полноценные eval-наборы, прогоняемые систематически.

1. Проверка триггеров

Задача: убедиться, что skill подключается когда надо и молчит когда не надо.

2. Функциональные тесты

Задача: убедиться, что на выходе корректный результат.

Тест: Создать проект с 5 задачами
Дано: название проекта "Q4 Planning", 5 описаний задач
Когда: skill отрабатывает весь процесс
Тогда:
  - Проект появился в ProjectHub
  - 5 задач созданы с правильными полями
  - Все задачи привязаны к проекту
  - Ни одной ошибки API

3. Сравнение «до и после»

Задача: показать, что со skill реально лучше, чем без него.

Skill-creator — ваш помощник

skill-creator встроен в Claude.ai и доступен в Claude Code. Если у вас есть MCP-сервер и понимание 2-3 основных сценариев, первый рабочий skill можно собрать и обкатать за 15-30 минут.

• Создание: генерирует skill из описания на обычном языке, выдаёт готовый SKILL.md с правильной шапкой
• Ревью: находит слабые места: размытые описания, недостающие триггеры, структурные проблемы
• Доработка: покажите ему примеры граничных случаев, и он подскажет, как улучшить обработку

"Используй skill-creator, мне нужен skill для [ваш сценарий]"

Доработка по ходу дела

Skill — живой документ, а не монолит. Вот на что обращать внимание:

Skill молчит, когда должен работать

• Не подключается на подходящие запросы
• Пользователи вынуждены включать его руками

Что делать: обогатите описание: больше деталей, ключевых слов, технических терминов.

Skill лезет куда не просят

• Подключается на посторонние запросы
• Пользователи раздражённо его отключают

Что делать: добавьте «антитриггеры» (чётко скажите, когда НЕ использовать), сузьте формулировки.

Skill работает криво

• Результаты «плавают» от запуска к запуску
• API-вызовы падают

Что делать: конкретизируйте инструкции, добавьте обработку ошибок.

Skills делают вашу MCP-интеграцию полноценной. Когда пользователи сравнивают коннекторы, те, что идут со skills, быстрее приносят пользу — это ваше преимущество перед MCP-only альтернативами.

Как распространять

Текущая модель (январь 2026)

Для обычных пользователей

1. Скачать папку skill
2. Запаковать в .zip (если нужно)
3. Загрузить в Claude.ai: Settings > Capabilities > Skills
4. Либо положить в папку skills Claude Code

Для организаций

• Админы могут раскатать skills на весь workspace разом (доступно с 18 декабря 2025)
• Обновления приезжают автоматически
• Управление из одного места

Открытый стандарт

Anthropic выпустила Agent Skills как открытый стандарт. Идея та же, что и с MCP: один skill должен работать везде: и в Claude, и на других AI-платформах, без переделок.

Skills через API

Если вы строите приложения, агентов или автоматические пайплайны, API даёт полный контроль над skills:

• Эндпоинт /v1/skills для управления
• Подключение skills к Messages API через параметр container.skills
• Версионирование через Claude Console
• Интеграция с Claude Agent SDK для кастомных агентов

Подробности в документации:

• Skills API Quickstart
• Create Custom Skills
• Skills in the Agent SDK

Как подать свой skill

Лучший вариант: публичный GitHub-репозиторий с понятным README, примерами и скриншотами. Плюс раздел в документации вашего MCP-сервера со ссылкой на skill и объяснением, зачем использовать оба вместе.

Шаблон инструкции по установке

## Установка skill [Название сервиса]

1. Скачайте skill:
   - Клонируйте репо: `git clone https://github.com/yourcompany/skills`
   - Или скачайте ZIP из Releases

2. Установите в Claude:
   - Откройте Claude.ai > Settings > Skills
   - Нажмите «Upload skill»
   - Выберите папку со skill (в .zip)

3. Активируйте:
   - Включите skill [Название сервиса]
   - Убедитесь, что MCP-сервер подключён

4. Проверьте:
   - Спросите Claude: «Создай новый проект в [Сервис]»

Подчеркните ценность связки MCP + Skills:

«Наш MCP-сервер открывает Claude доступ к вашим проектам в Linear. А наши skills учат его вашему процессу планирования спринтов. Вместе это AI-управление проектами из коробки.»

Типичные проблемы и решения

Skill не загружается

# Нет разделителей, не сработает
name: my-skill
description: Does things

# Незакрытые кавычки, не сработает
name: my-skill
description: "Does things

# Вот так правильно
---
name: my-skill
description: Does things
---

# Неправильно
name: My Cool Skill

# Правильно
name: my-cool-skill

Skill не подключается

Skill подключается к чему попало

MCP-вызовы падают

Claude игнорирует инструкции

Skill тормозит или деградирует

Документация Anthropic

• Skills Documentation
• API Quickstart
• API Reference
• MCP Documentation

Статьи в блоге

• Introducing Agent Skills
• Engineering Blog: Equipping Agents for the Real World
• Skills Explained
• How to Create Skills for Claude
• Improving Frontend Design through Skills

Готовые примеры

• GitHub: anthropics/skills — коллекция skills от Anthropic, можно форкнуть и адаптировать

Инструменты

• skill-creator: встроен в Claude.ai и доступен в Claude Code. Генерирует skills из описания, проверяет структуру, подсказывает улучшения.

Куда обращаться

• Вопросы: Claude Developers Discord
• Баги: anthropics/skills/issues на GitHub

До старта

• Сформулированы 2-3 конкретных сценария
• Понятно, какие инструменты нужны (встроенные или MCP)
• Просмотрены примеры существующих skills
• Продумана структура папок

В процессе

• Папка в kebab-case
• Файл называется ровно SKILL.md
• YAML frontmatter обрамлена ---
• name: строчные, через дефис, без пробелов
• description отвечает на «что делает» и «когда подключать»
• Нигде нет XML-тегов
• Инструкции конкретные, с примерами
• Описана обработка ошибок
• Есть примеры использования
• Ссылки на справочные файлы расставлены

Перед загрузкой

• Подключается на очевидные запросы
• Подключается на перефразированные запросы
• Не подключается на посторонние темы
• Функциональные тесты проходят
• Интеграция с инструментами работает (если есть)
• Папка запакована в .zip

После загрузки

• Обкатано в живых разговорах
• Отслеживаются ложные срабатывания и пропуски
• Собирается обратная связь
• Описание и инструкции дорабатываются
• Версия в метаданных обновлена

Обязательные поля

---
name: skill-name-in-kebab-case
description: Что делает и когда подключать. Перечислите фразы-триггеры.
---

Полный набор полей

name: skill-name
description: [обязательное описание]
license: MIT                    # Лицензия для open-source
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"  # Ограничение инструментов
metadata:                       # Произвольные поля
  author: Company Name
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]
  documentation: https://example.com/docs
  support: support@example.com

Безопасность

Полноценные, проверенные в бою skills, где можно подсмотреть все паттерны из руководства:

• Document Skills — генерация PDF, DOCX, PPTX, XLSX
• Example Skills — разные паттерны рабочих процессов
• Partner Skills Directory : skills от партнёров: Asana, Atlassian, Canva, Figma, Sentry, Zapier и др.

Репозитории актуальны. Форкайте, адаптируйте под себя, используйте как отправную точку.