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

Перевод команды ENGRAM · оригинал Anthropic

Коротко: Это полный русский перевод официального руководства Anthropic «The Complete Guide to Building Skills for Claude» - о том, как создавать скиллы (Skills) для Claude: навыки-папки, которые один раз учат Claude вашему процессу и дальше срабатывают сами. Ниже все шесть глав и приложения оригинала, без сокращений. Ссылка на первоисточник и пометка о переводе - в конце страницы.

Скилл - это набор инструкций, упакованный в виде обычной папки, который учит Claude справляться с конкретными задачами или рабочими процессами. Скиллы - один из самых мощных способов настроить Claude под свои нужды. Вместо того чтобы заново объяснять свои предпочтения, процессы и экспертизу в каждом разговоре, скиллы позволяют научить Claude один раз и получать пользу каждый раз.

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

Для кого это руководство

Это руководство охватывает всё, что нужно для создания эффективных скиллов - от планирования и структуры до тестирования и распространения.

Что вы узнаете:

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

Для кого:

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

Два пути по этому руководству. Строите самостоятельные скиллы? Сосредоточьтесь на разделах «Основы», «Планирование и проектирование» и категориях 1-2. Улучшаете MCP-интеграцию? Ваши разделы - «Скиллы + MCP» и категория 3. Оба пути опираются на одни и те же технические требования.

Что вы получите. К концу вы сможете собрать работающий скилл за один присест. Рассчитывайте примерно на 15-30 минут на создание и тестирование первого рабочего скилла с помощью скилла-создателя (skill-creator).

Глава 1. Основы

Что такое скилл

Скилл - это папка, содержащая:

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

Ключевые принципы проектирования

Прогрессивное раскрытие (progressive disclosure). Скиллы используют трёхуровневую систему:

• Первый уровень (YAML-фронтматтер): всегда загружается в системный промпт Claude. Даёт ровно столько информации, чтобы Claude понимал, когда применить каждый скилл, не загружая его целиком в контекст.
• Второй уровень (тело SKILL.md): загружается, когда Claude считает скилл релевантным задаче. Содержит полные инструкции и рекомендации.
• Третий уровень (связанные файлы): дополнительные файлы внутри директории скилла, которые Claude открывает только по мере необходимости.

Такое прогрессивное раскрытие минимизирует расход токенов, сохраняя специализированную экспертизу.

Композируемость. Claude может загружать несколько скиллов одновременно. Ваш скилл должен хорошо работать рядом с другими и не предполагать, что он - единственная доступная возможность.

Переносимость. Скиллы работают одинаково в Claude.ai, Claude Code и через API. Создайте скилл один раз - и он работает на всех поверхностях без изменений, если окружение поддерживает нужные скиллу зависимости.

Для создателей MCP: скиллы + коннекторы

Если у вас уже есть работающий MCP-сервер, самую сложную часть вы сделали. Скиллы - это слой знаний поверх него: они фиксируют рабочие процессы и лучшие практики, которые вы уже знаете, чтобы Claude применял их стабильно.

Аналогия с кухней. MCP предоставляет профессиональную кухню: доступ к инструментам, ингредиентам и оборудованию. Скиллы предоставляют рецепты: пошаговые инструкции, как приготовить что-то ценное. Вместе они позволяют решать сложные задачи, не разбираясь самостоятельно в каждом шаге.

Без скиллов: пользователи подключают ваш MCP, но не знают, что делать дальше; тикеты «как сделать X с вашей интеграцией»; каждый разговор с нуля; непоследовательные результаты; пользователи винят коннектор, хотя проблема - в отсутствии рекомендаций по процессу.

Со скиллами: готовые рабочие процессы включаются автоматически при необходимости; стабильное использование инструментов; лучшие практики встроены в каждое взаимодействие; ниже порог входа в вашу интеграцию.

Глава 2. Планирование и проектирование

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

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

Сценарий: Планирование спринта проекта
Триггер: Пользователь говорит «помоги спланировать этот спринт»
         или «создай задачи спринта»
Шаги:
1. Получить текущий статус проекта из Linear (через MCP)
2. Проанализировать скорость и загрузку команды
3. Предложить приоритизацию задач
4. Создать задачи в Linear с нужными метками и оценками
Результат: Полностью спланированный спринт с созданными задачами

Спросите себя: чего пользователь хочет достичь; какие многошаговые процессы для этого нужны; какие инструменты потребуются (встроенные или MCP); какие доменные знания или лучшие практики стоит встроить.

Частые категории сценариев

Категория 1. Создание документов и ассетов. Стабильный, качественный результат - документы, презентации, приложения, дизайны, код. Пример: скилл frontend-design (а также docx, pptx, xlsx). Приёмы: встроенные стайл-гайды и бренд-стандарты, шаблонные структуры, чеклисты качества перед финализацией. Внешние инструменты не требуются - используются встроенные возможности Claude.

Категория 2. Автоматизация рабочих процессов. Многошаговые процессы с единой методологией, включая координацию нескольких MCP-серверов. Пример: скилл skill-creator - интерактивно проводит через определение сценария, генерацию фронтматтера, написание инструкций и валидацию. Приёмы: пошаговый процесс с гейтами валидации, шаблоны, встроенные проверки, циклы итеративной доработки.

Категория 3. Усиление MCP. Рекомендации по процессу, усиливающие доступ к инструментам от MCP-сервера. Пример: скилл sentry-code-review - анализирует и исправляет баги в pull-запросах на GitHub, используя данные Sentry через их MCP-сервер. Приёмы: координация нескольких вызовов MCP по порядку, встроенная доменная экспертиза, контекст, который иначе задавал бы пользователь, обработка типичных проблем MCP.

Определите критерии успеха

Это ориентиры-цели, скорее приблизительные бенчмарки, чем точные пороги. Стремитесь к строгости, но принимайте, что элемент субъективной оценки неизбежен.

Количественные метрики:

• Скилл срабатывает на 90% релевантных запросов. Прогоните 10-20 тестовых запросов, которые должны его запускать; посчитайте, сколько раз он загрузился сам, а сколько потребовал явного вызова.
• Завершает процесс за X вызовов инструментов. Сравните одну задачу со скиллом и без; посчитайте число вызовов инструментов и расход токенов.
• 0 неуспешных вызовов API на процесс. Следите за логами MCP-сервера во время тестов; отслеживайте повторы и коды ошибок.

Качественные метрики:

• Пользователям не нужно подсказывать Claude следующие шаги. Отмечайте, как часто приходится перенаправлять; собирайте обратную связь у бета-пользователей.
• Процессы завершаются без правок пользователя. Запустите один запрос 3-5 раз; сравните результаты на стабильность и качество.
• Стабильные результаты между сессиями. Сможет ли новый пользователь решить задачу с первого раза при минимальных подсказках?

Технические требования: структура файлов

your-skill-name/
├── SKILL.md              # Обязательно - главный файл скилла
├── scripts/              # Опционально - исполняемый код
│   ├── process_data.py
│   └── validate.sh
├── references/           # Опционально - документация
│   ├── api-guide.md
│   └── examples/
└── assets/               # Опционально - шаблоны и т. п.
    └── report-template.md

Критически важные правила.

Имя файла - ровно SKILL.md (с учётом регистра). Варианты SKILL.MD, skill.md не принимаются.

Имя папки скилла - в kebab-case: notion-project-setup - да; Notion Project Setup (пробелы), notion_project_setup (подчёркивания), NotionProjectSetup (заглавные) - нет.

Никакого README.md внутри папки скилла - вся документация в SKILL.md или в references/. Примечание: при распространении через GitHub README на уровне репозитория всё же нужен - для людей (см. «Распространение и публикация»).

YAML-фронтматтер: самая важная часть

По YAML-фронтматтеру Claude решает, загружать ли ваш скилл. Минимальный формат:

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

Требования к полям.

name (обязательно): только kebab-case, без пробелов и заглавных, должно совпадать с именем папки.

description (обязательно): ОБЯЗАТЕЛЬНО включает и что скилл делает, и когда его применять (условия срабатывания). Менее 1024 символов. Без XML-тегов (< или >). Включайте конкретные формулировки, которые говорят пользователи, и упоминайте типы файлов, если уместно.

license (опционально): укажите для open-source-скилла (например, MIT, Apache-2.0).

compatibility (опционально): 1-500 символов, обозначает требования к окружению (целевой продукт, системные пакеты, потребность в сети и т. д.).

metadata (опционально): любые пары «ключ-значение». Рекомендуется author, version, mcp-server:

metadata:
  author: ProjectHub
  version: 1.0.0
  mcp-server: projecthub

Ограничения безопасности. Во фронтматтере запрещены угловые скобки XML (< >) и слова «claude»/«anthropic» в имени (зарезервированы). Причина: фронтматтер попадает в системный промпт Claude, вредоносное содержимое может внедрить инструкции.

Как писать поле description

Первый уровень прогрессивного раскрытия - метаданные - «даёт ровно столько информации, чтобы Claude понимал, когда применять каждый скилл, не загружая его целиком в контекст». Структура: [что делает] + [когда применять] + [ключевые возможности].

Хорошие описания:

# Конкретно и применимо
description: Analyzes Figma design files and generates developer
handoff documentation. Use when user uploads .fig files, asks for
"design specs", "component documentation", or "design-to-code handoff".

# Включает фразы-триггеры
description: Manages Linear project workflows including sprint
planning, task creation, and status tracking. Use when user
mentions "sprint", "Linear tasks", "project planning", or asks
to "create tickets".

# Понятная ценность
description: End-to-end customer onboarding workflow for PayFlow.
Handles account creation, payment setup, and subscription
management. Use when user says "onboard new customer", "set up
subscription", or "create PayFlow account".

Плохие описания:

# Слишком расплывчато
description: Helps with projects.

# Нет триггеров
description: Creates sophisticated multi-page documentation systems.

# Слишком технично, нет пользовательских триггеров
description: Implements the Project entity model with hierarchical
relationships.

Написание основных инструкций

После фронтматтера напишите сами инструкции в Markdown. Рекомендуемая структура (замените части в скобках своим содержимым):

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

# Название вашего скилла

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

### Шаг 1: [Первый крупный шаг]
Понятное объяснение того, что происходит.
Команда-пример: python scripts/fetch_data.py --project-id PROJECT_ID
Ожидаемый результат: [опишите, как выглядит успех]
(Добавьте столько шагов, сколько нужно)

## Примеры

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

## Устранение проблем

Ошибка: [типичное сообщение]
Причина: [почему происходит]
Решение: [как исправить]

Лучшие практики для инструкций

Будьте конкретны и применимы.

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

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

Включайте обработку ошибок.

## Частые проблемы

### Сбой подключения MCP
Если видите "Connection refused":
1. Убедитесь, что MCP-сервер запущен: Settings > Extensions
2. Проверьте, что API-ключ действителен
3. Переподключитесь: Settings > Extensions > [Ваш сервис] > Reconnect

Чётко ссылайтесь на вложенные ресурсы.

Прежде чем писать запросы, сверьтесь с references/api-patterns.md:
- рекомендации по лимитам запросов;
- паттерны пагинации;
- коды ошибок и их обработка.

Используйте прогрессивное раскрытие. Держите SKILL.md сфокусированным на основных инструкциях. Подробную документацию выносите в references/ и ссылайтесь на неё.

Глава 3. Тестирование и итерации

Тестировать скиллы можно с разной строгостью:

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

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

Три области тестирования

1. Тесты срабатывания - скилл загружается в нужные моменты.

Должен срабатывать:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"

НЕ должен срабатывать:
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "Create a spreadsheet" (если скилл не про таблицы)

2. Функциональные тесты - скилл выдаёт правильный результат.

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

3. Сравнение производительности - скилл улучшает результат против базовой линии.

Без скилла:
- Пользователь даёт инструкции каждый раз
- 15 сообщений туда-сюда
- 3 неуспешных вызова API, требующих повтора
- Израсходовано 12 000 токенов

Со скиллом:
- Автоматическое выполнение процесса
- Только 2 уточняющих вопроса
- 0 неуспешных вызовов API
- Израсходовано 6 000 токенов

Скилл skill-creator

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

Он умеет: генерировать скиллы из описаний на естественном языке; формировать корректный SKILL.md с фронтматтером; подсказывать фразы-триггеры и структуру; указывать на типичные проблемы (расплывчатые описания, отсутствующие триггеры, структурные ошибки); выявлять риски избыточного/недостаточного срабатывания; предлагать тест-кейсы.

Итеративное улучшение: столкнувшись с граничным случаем, принесите пример обратно в skill-creator - «Используй проблемы и решения из этого чата, чтобы улучшить, как скилл обрабатывает [граничный случай]». Как вызвать: "Use the skill-creator skill to help me build a skill for [ваш сценарий]".

Примечание: skill-creator помогает проектировать и дорабатывать, но не выполняет автоматические наборы тестов и не выдаёт количественных результатов оценки.

Итерации на основе обратной связи

Скиллы - живые документы.

Недостаточное срабатывание (не загружается, когда должен; включают вручную; вопросы «когда применять»): добавьте деталей и нюансов в описание, включая ключевые слова, особенно для технических терминов.

Избыточное срабатывание (загружается на нерелевантные запросы; отключают; путаница с назначением): добавьте негативные триггеры, будьте конкретнее.

Проблемы исполнения (непоследовательные результаты, сбои API, нужны правки): улучшите инструкции, добавьте обработку ошибок.

Глава 4. Распространение и публикация

Скиллы делают вашу MCP-интеграцию полнее: коннекторы со скиллами дают более быстрый путь к ценности - это преимущество перед решениями «только MCP».

Текущая модель распространения

Отдельные пользователи: скачивают папку скилла → упаковывают в zip (если нужно) → загружают в Claude.ai через Settings > Capabilities > Skills, либо кладут в директорию скиллов Claude Code.

Уровень организации: администраторы могут развернуть скиллы на всё рабочее пространство, с автообновлениями и централизованным управлением.

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

Anthropic опубликовала Agent Skills как открытый стандарт. Как и в случае с MCP, скиллы должны быть переносимы между инструментами и платформами: один и тот же скилл должен работать независимо от платформы. При этом некоторые скиллы спроектированы под конкретную платформу; авторы могут отметить это в поле compatibility.

Использование скиллов через API

Для программных сценариев (приложения, агенты, автоматизированные процессы) API даёт прямой контроль над скиллами:

• Эндпоинт /v1/skills для получения списка и управления
• Добавление скиллов в запросы Messages API через параметр container.skills
• Контроль версий через Claude Console
• Работа с Claude Agent SDK для собственных агентов

Примечание: скиллы в API требуют бета-инструмента Code Execution Tool - защищённого окружения, необходимого для работы скиллов.

Рекомендуемый подход на сегодня

1. Разместите на GitHub - публичный репозиторий, понятный README с установкой (для людей; это отдельно от папки скилла, где README.md быть не должно), примеры использования и скриншоты.
2. Задокументируйте в репозитории MCP - ссылка на скиллы из документации MCP, объяснение ценности совместного использования, быстрый старт.
3. Дайте инструкцию по установке:

## Установка скилла [Ваш сервис]

1. Скачайте: git clone https://github.com/yourcompany/skills
   (или ZIP из Releases)
2. Установите: Claude.ai > Settings > Skills > Upload skill >
   выберите папку скилла (в zip)
3. Включите: тумблер скилла [Ваш сервис];
   убедитесь, что MCP-сервер подключён
4. Проверьте: "Set up a new project in [Ваш сервис]"

Как позиционировать свой скилл

Фокусируйтесь на результатах, а не на функциях.

Хорошо: «Скилл ProjectHub позволяет командам за секунды разворачивать полноценные рабочие пространства - страницы, базы данных, шаблоны - вместо 30 минут ручной настройки».

Плохо: «Скилл ProjectHub - это папка с YAML-фронтматтером и Markdown-инструкциями, которая вызывает инструменты нашего MCP-сервера».

Подчёркивайте связку: «Наш MCP-сервер даёт Claude доступ к вашим проектам в Linear. Наши скиллы учат Claude процессу планирования спринтов вашей команды. Вместе - управление проектами на базе ИИ».

Глава 5. Паттерны и устранение проблем

Эти паттерны выделились из скиллов ранних пользователей и внутренних команд. Это общие подходы, а не предписывающие шаблоны.

От проблемы или от инструмента

Как в магазине стройтоваров. Можно прийти с проблемой («нужно починить шкаф») - и сотрудник укажет инструменты. А можно выбрать новую дрель и спросить, как применить её к задаче.

• От проблемы: «Мне нужно развернуть рабочее пространство проекта» → скилл оркестрирует нужные вызовы MCP в правильном порядке. Пользователь описывает результат; скилл управляет инструментами.
• От инструмента: «У меня подключён Notion MCP» → скилл учит Claude оптимальным процессам. У пользователя есть доступ; скилл даёт экспертизу.

Большинство скиллов склоняются в одну сторону. Понимание рамки помогает выбрать паттерн ниже.

Паттерн 1. Оркестрация последовательного процесса

Когда: пользователям нужны многошаговые процессы в определённом порядке.

## Процесс: Онбординг нового клиента

### Шаг 1: Создать аккаунт
MCP-инструмент: create_customer | Параметры: name, email, company

### Шаг 2: Настроить оплату
MCP-инструмент: setup_payment_method | Ожидать: подтверждение способа оплаты

### Шаг 3: Создать подписку
MCP-инструмент: create_subscription | Параметры: plan_id, customer_id (из шага 1)

### Шаг 4: Отправить приветственное письмо
MCP-инструмент: send_email | Шаблон: welcome_email_template

Приёмы: явный порядок, зависимости между шагами, валидация на каждом этапе, инструкции по откату при сбоях.

Паттерн 2. Координация нескольких MCP

Когда: процессы охватывают несколько сервисов. Пример - передача от дизайна к разработке.

### Фаза 1: Экспорт дизайна (Figma MCP)
Экспортировать ассеты → сгенерировать спецификации → создать манифест ассетов

### Фаза 2: Хранение (Drive MCP)
Создать папку проекта → загрузить ассеты → сгенерировать ссылки доступа

### Фаза 3: Задачи (Linear MCP)
Создать задачи разработки → приложить ссылки на ассеты → назначить команду

### Фаза 4: Уведомление (Slack MCP)
Опубликовать сводку в #engineering → включить ссылки на ассеты и задачи

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

Паттерн 3. Итеративная доработка

Когда: качество результата растёт с итерациями. Пример - генерация отчёта.

### Первый черновик
Получить данные через MCP → сгенерировать черновик → сохранить во временный файл

### Проверка качества
Запустить scripts/check_report.py → выявить: отсутствующие разделы,
непоследовательное форматирование, ошибки валидации данных

### Цикл доработки
Устранить каждую проблему → перегенерировать разделы → повторно валидировать
→ повторять до порога качества

### Финализация
Применить форматирование → сгенерировать сводку → сохранить финал

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

Паттерн 4. Выбор инструмента по контексту

Когда: результат один, инструменты разные по контексту. Пример - хранение файлов.

### Дерево решений
Проверить тип и размер файла → выбрать место хранения:
  - Большие файлы (>10 МБ): облачное хранилище MCP
  - Документы для совместной работы: Notion/Docs MCP
  - Файлы кода: GitHub MCP
  - Временные файлы: локальное хранилище

### Выполнить
Вызвать подходящий MCP → применить метаданные сервиса → сгенерировать ссылку
### Дать контекст
Объяснить пользователю, почему выбрано это хранилище

Приёмы: чёткие критерии решения, запасные варианты, прозрачность выбора.

Паттерн 5. Доменно-специфичный интеллект

Когда: скилл добавляет специализированные знания сверх доступа к инструментам. Пример - финансовый комплаенс.

### Перед обработкой (проверка комплаенса)
Получить детали транзакции через MCP → применить правила:
санкционные списки, допустимость юрисдикции, уровень риска → задокументировать

### Обработка
ЕСЛИ комплаенс пройден: вызвать обработку платежа → проверки на мошенничество
ИНАЧЕ: пометить для проверки → создать комплаенс-кейс

### Аудиторский след
Логировать проверки → записывать решения → сгенерировать аудиторский отчёт

Приёмы: доменная экспертиза в логике, комплаенс до действия, полная документация, чёткое управление.

Устранение проблем

Скилл не загружается.

Ошибка «Could not find SKILL.md» - файл назван не ровно SKILL.md. Переименуйте с учётом регистра; проверьте ls -la.

Ошибка «Invalid frontmatter» - проблема YAML. Частые причины:

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

# Неверно - незакрытая кавычка
description: "Does things

# Верно
---
name: my-skill
description: Does things
---

Ошибка «Invalid skill name» - пробелы или заглавные. My Cool Skill - нет; my-cool-skill - да.

Скилл не срабатывает. Переработайте description. Чеклист: не слишком ли общее («Helps with projects» не сработает); есть ли реальные фразы-триггеры; упомянуты ли типы файлов. Приём отладки: спросите Claude - «Когда бы ты применил скилл [имя]?» - он процитирует описание; скорректируйте недостающее.

Скилл срабатывает слишком часто.

# Негативные триггеры
description: Advanced data analysis for CSV files. Use for
statistical modeling, regression, clustering. Do NOT use for
simple data exploration (use data-viz skill instead).

# Конкретнее вместо широкого
description: Processes PDF legal documents for contract review

Проблемы подключения MCP. Проверьте: MCP-сервер подключён (Settings > Extensions, статус «Connected»); аутентификация (ключи, права, OAuth-токены); протестируйте MCP отдельно, без скилла («Use [Service] MCP to fetch my projects» - если и так не работает, проблема в MCP); правильные ли имена инструментов (регистр важен).

Инструкции не выполняются. Частые причины: инструкции слишком многословны (короче, списки, детали - в отдельные файлы); инструкции спрятаны (критичное - наверх, заголовки ## Важно); двусмысленные формулировки.

# Плохо
Make sure to validate things properly

# Хорошо
CRITICAL: Before calling create_project, verify:
- Project name is non-empty
- At least one team member assigned
- Start date is not in the past

При «лени» модели помогает явное поощрение (эффективнее в пользовательском промпте, чем в SKILL.md): «Не торопись, сделай тщательно. Качество важнее скорости. Не пропускай шаги валидации».

Проблемы большого контекста (медленно, ответы деградируют): оптимизируйте размер SKILL.md (подробности - в references/, держите короче 5000 слов); сократите число включённых скиллов (оцените, не более ли 20-50 сразу; рассмотрите «паки» скиллов).

Глава 6. Ресурсы и справочники

Строите первый скилл - начните с руководства по лучшим практикам, затем обращайтесь к документации API по мере необходимости.

• Документация Claude: docs.claude.com
• Публичный репозиторий скиллов: github.com/anthropics/skills - созданные Anthropic скиллы, которые можно адаптировать под себя
• MCP: modelcontextprotocol.io
• Скилл skill-creator - встроен в Claude.ai и доступен для Claude Code; генерирует скиллы из описаний, проверяет и даёт рекомендации. Вызов: "Help me build a skill using skill-creator". Проверка: "Review this skill and suggest improvements".

Баг-репорты - в GitHub Issues репозитория anthropics/skills (укажите имя скилла, сообщение об ошибке, шаги воспроизведения). Общие вопросы - в сообществе Claude Developers.

Приложение A. Быстрый чеклист

Сгенерируйте первый черновик скиллом skill-creator, затем пройдитесь по списку.

Перед началом:

• ☐ Определены 2-3 конкретных сценария использования
• ☐ Определены инструменты (встроенные или MCP)
• ☐ Изучены руководство и примеры скиллов
• ☐ Спланирована структура папок

Во время разработки:

• ☐ Папка названа в kebab-case
• ☐ Файл SKILL.md существует (точное написание)
• ☐ YAML-фронтматтер имеет разделители ---
• ☐ Поле name: kebab-case, без пробелов и заглавных
• ☐ Описание включает ЧТО и КОГДА
• ☐ Нигде нет XML-тегов (< >)
• ☐ Инструкции понятны и применимы
• ☐ Включена обработка ошибок
• ☐ Приведены примеры
• ☐ Ссылки на references расставлены явно

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

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

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

• ☐ Протестировано в реальных разговорах
• ☐ Отслеживается избыточное/недостаточное срабатывание
• ☐ Собрана обратная связь пользователей
• ☐ Доработаны описание и инструкции
• ☐ Обновлена версия в metadata

Приложение B. YAML-фронтматтер

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

---
name: skill-name-in-kebab-case
description: What it does and when to use it. Include specific
trigger phrases.
---

Все опциональные поля:

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

Разрешено: любые стандартные типы YAML (строки, числа, булевы, списки, объекты), произвольные поля metadata, длинные описания (до 1024 символов).

Запрещено: угловые скобки XML (< >); выполнение кода в YAML (используется безопасный парсинг); скиллы с префиксом «claude»/«anthropic» в имени (зарезервированы).

Приложение C. Полные примеры скиллов

Готовые к продакшену скиллы, демонстрирующие паттерны из руководства:

• Document Skills - создание PDF, DOCX, PPTX, XLSX
• Example Skills - различные паттерны рабочих процессов
• Partner Skills Directory - скиллы партнёров (Asana, Atlassian, Canva, Figma, Sentry, Zapier и другие)

Эти репозитории поддерживаются в актуальном состоянии. Клонируйте, адаптируйте под свой сценарий и используйте как шаблоны. Актуальный набор - в репозитории github.com/anthropics/skills.

Об этом переводе

Это перевод официального руководства Anthropic «The Complete Guide to Building Skills for Claude» на русский язык, выполненный командой ENGRAM для русскоязычных читателей. Все права на оригинальный материал принадлежат Anthropic. Формулировки продукта, названия эндпоинтов и примеры кода сохранены как в первоисточнике, чтобы ими можно было пользоваться на практике.

• Оригинал (PDF): The Complete Guide to Building Skills for Claude - resources.anthropic.com
• Документация Claude: docs.claude.com

Если заметили неточность в переводе - напишите нам, поправим.

Что дальше

Практика по теме - в гайдах Академии:

• Как создать свой скилл в Claude Code - собираем первый скилл по шагам.
• Как безопасно установить чужой скилл - что проверить перед запуском.
• Как подключить MCP к Claude Code - доступ к сервисам, поверх которого работают скиллы.
• Как установить Claude Code в VS Code - с нуля, если ещё не поставили.