Создание навыков для плагинов Claude Code

Текст

---
name: skill-development
description: Этот скилл следует использовать, когда пользователь хочет «создать скилл», «добавить скилл в плагин», «написать новый скилл», «улучшить описание скилла», «организовать содержимое скилла» или нуждается в рекомендациях по структуре скилла, постепенному раскрытию информации (progressive disclosure) и лучшим практикам разработки скиллов для плагинов Claude Code.
version: 0.1.0
---

Разработка скиллов для плагинов Claude Code

Этот скилл даёт рекомендации по созданию эффективных скиллов для плагинов Claude Code.

О скиллах

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

Что дают скиллы

1. Специализированные рабочие процессы — многошаговые процедуры для конкретных областей
2. Интеграции с инструментами — инструкции по работе с определёнными форматами файлов или API
3. Экспертиза в предметной области — знания, специфичные для компании, схемы, бизнес-логика
4. Вложенные ресурсы — скрипты, справочные материалы и ресурсы для сложных и повторяющихся задач

Устройство скилла

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

skill-name/
├── SKILL.md (обязательно)
│   ├── Метаданные YAML-шапки (обязательно)
│   │   ├── name: (обязательно)
│   │   └── description: (обязательно)
│   └── Инструкции в Markdown (обязательно)
└── Вложенные ресурсы (необязательно)
    ├── scripts/          - Исполняемый код (Python/Bash и т. п.)
    ├── references/       - Документация, которую подгружают в контекст по мере необходимости
    └── assets/           - Файлы, используемые в результате (шаблоны, значки, шрифты и т. п.)

SKILL.md (обязателен)

Качество метаданных: name и description в YAML-шапке определяют, когда Claude будет использовать скилл. Конкретно опиши, что делает скилл и когда его использовать. Пиши от третьего лица (например, «Этот скилл следует использовать, когда…», а не «Используй этот скилл, когда…»).

Вложенные ресурсы (необязательны)

Скрипты (scripts/)

Исполняемый код (Python/Bash и т. п.) для задач, которым нужна детерминированная надёжность или которые приходится переписывать снова и снова.

• Когда включать: когда один и тот же код переписывают многократно или нужна детерминированная надёжность
• Пример: scripts/rotate_pdf.py для задач поворота PDF
• Преимущества: экономят токены, детерминированы, могут выполняться без загрузки в контекст
• Примечание: Claude всё равно может понадобиться читать скрипты, чтобы вносить правки или подстраивать их под окружение

Справочные материалы (references/)

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

• Когда включать: для документации, на которую Claude должен ссылаться в работе
• Примеры: references/finance.md для финансовых схем, references/mnda.md для шаблона NDA компании, references/policies.md для политик компании, references/api_docs.md для спецификаций API
• Случаи применения: схемы баз данных, документация API, знания предметной области, политики компании, подробные руководства по рабочим процессам
• Преимущества: SKILL.md остаётся компактным, а материалы загружаются, только когда Claude решает, что они нужны
• Лучшая практика: если файлы большие (>10 тыс. слов), добавь в SKILL.md шаблоны поиска через grep
• Избегай дублирования: информация должна жить либо в SKILL.md, либо в справочных файлах, но не в обоих местах. Для подробной информации предпочитай справочные файлы, если только она не является по-настоящему основной для скилла: так SKILL.md остаётся компактным, а информация находится без перегрузки контекстного окна. Оставляй в SKILL.md только важнейшие процедурные инструкции и указания по рабочему процессу; подробные справочные материалы, схемы и примеры перенеси в справочные файлы.

Ресурсы (assets/)

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

• Когда включать: когда скиллу нужны файлы, которые будут использованы в итоговом результате
• Примеры: assets/logo.png для элементов бренда, assets/slides.pptx для шаблонов PowerPoint, assets/frontend-template/ для заготовок HTML/React, assets/font.ttf для типографики
• Случаи применения: шаблоны, изображения, значки, шаблонный код, шрифты, образцы документов, которые копируются или изменяются
• Преимущества: отделяют ресурсы результата от документации, позволяют Claude использовать файлы без загрузки в контекст

Принцип проектирования: постепенное раскрытие (progressive disclosure)

Скиллы используют трёхуровневую систему загрузки, чтобы эффективно расходовать контекст:

1. Метаданные (name + description) — всегда в контексте (~100 слов)
2. Тело SKILL.md — когда срабатывает скилл (<5 тыс. слов)
3. Вложенные ресурсы — по мере необходимости для Claude (без ограничений*)

*Без ограничений, потому что скрипты можно выполнять, не читая их в контекстное окно.

Процесс создания скилла

Чтобы создать скилл, выполни шаги «Процесса создания скилла» по порядку, пропуская их только тогда, когда есть явная причина, почему они не применимы.

Шаг 1. Пойми скилл на конкретных примерах

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

Чтобы создать эффективный скилл, чётко пойми конкретные примеры того, как он будет использоваться. Это понимание может прийти из прямых примеров пользователя или из сгенерированных примеров, проверенных обратной связью пользователя.

Например, при создании скилла-редактора изображений уместны такие вопросы:

• «Какие функции должен поддерживать скилл-редактор изображений? Редактирование, поворот, что-то ещё?»
• «Можешь привести несколько примеров того, как будет использоваться этот скилл?»
• «Я могу представить, что пользователи будут просить что-то вроде „Убери красные глаза на этом изображении“ или „Поверни это изображение“. Какие ещё способы использования ты себе представляешь?»
• «Что скажет пользователь, чтобы сработал этот скилл?»

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

Заверши этот шаг, когда появится чёткое понимание, какие функции должен поддерживать скилл.

Шаг 2. Спланируй повторно используемое содержимое скилла

Чтобы превратить конкретные примеры в эффективный скилл, проанализируй каждый пример:

1. Продумай, как выполнить пример с нуля
2. Определи, какие скрипты, справочные материалы и ресурсы пригодились бы при многократном выполнении этих процессов

Пример: при создании скилла pdf-editor для запросов вроде «Помоги повернуть этот PDF» анализ показывает:

1. Для поворота PDF каждый раз приходится переписывать один и тот же код
2. Было бы полезно хранить в скилле скрипт scripts/rotate_pdf.py

Пример: при проектировании скилла frontend-webapp-builder для запросов вроде «Сделай мне приложение со списком дел» или «Сделай мне дашборд для отслеживания моих шагов» анализ показывает:

1. Для написания фронтенд-приложения каждый раз нужен один и тот же шаблонный HTML/React-код
2. Было бы полезно хранить в скилле шаблон assets/hello-world/ с файлами шаблонного проекта на HTML/React

Пример: при создании скилла big-query для запросов вроде «Сколько пользователей зашло сегодня?» анализ показывает:

1. Для запросов к BigQuery каждый раз приходится заново выяснять схемы таблиц и связи между ними
2. Было бы полезно хранить в скилле файл references/schema.md с описанием схем таблиц

Для плагинов Claude Code: при создании скилла по хукам анализ показывает:

1. Разработчикам постоянно нужно проверять hooks.json и тестировать скрипты хуков
2. Полезны утилиты scripts/validate-hook-schema.sh и scripts/test-hook.sh
3. references/patterns.md для подробных схем хуков, чтобы не раздувать SKILL.md

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

Шаг 3. Создай структуру скилла

Для плагинов Claude Code создай структуру каталогов скилла:

mkdir -p plugin-name/skills/skill-name/{references,examples,scripts}
touch plugin-name/skills/skill-name/SKILL.md

Примечание: в отличие от универсального skill-creator, который использует init_skill.py, скиллы плагинов создаются прямо в каталоге skills/ плагина по более простой ручной структуре.

Шаг 4. Отредактируй скилл

Редактируя (новый или существующий) скилл, помни, что он создаётся для использования другим экземпляром Claude. Сосредоточься на информации, которая будет полезна и неочевидна для Claude. Подумай, какие процедурные знания, детали предметной области или повторно используемые ресурсы помогут другому экземпляру Claude эффективнее выполнять эти задачи.

Начни с повторно используемого содержимого скилла

Начни реализацию с повторно используемых ресурсов, определённых выше: файлов scripts/, references/ и assets/. Учти, что для этого шага может потребоваться ввод от пользователя. Например, при реализации скилла brand-guidelines пользователю может понадобиться предоставить элементы бренда или шаблоны для assets/ либо документацию для references/.

Кроме того, удали все файлы и каталоги примеров, не нужные скиллу. Создавай только те каталоги, которые действительно нужны (references/, examples/, scripts/).

Обнови SKILL.md

Стиль письма: пиши весь скилл в повелительной форме или инфинитиве (инструкции, начинающиеся с глагола), а не от второго лица. Используй объективный, поучающий язык (например, «Чтобы выполнить X, сделай Y», а не «Тебе следует сделать X» и не «Если тебе нужно сделать X»). Это сохраняет единообразие и ясность для восприятия ИИ.

Описание (шапка): используй формат третьего лица с конкретными фразами-триггерами:

---
name: Название скилла
description: Этот скилл следует использовать, когда пользователь просит «конкретная фраза 1», «конкретная фраза 2», «конкретная фраза 3». Включи точные фразы, которые скажут пользователи и после которых должен сработать этот скилл. Будь конкретен и точен.
version: 0.1.0
---

Примеры хороших описаний:

description: Этот скилл следует использовать, когда пользователь просит «создать хук», «добавить хук PreToolUse», «проверять использование инструментов», «реализовать хуки на основе промтов» или упоминает события хуков (PreToolUse, PostToolUse, Stop).

Примеры плохих описаний:

description: Используй этот скилл при работе с хуками.  # Неверное лицо, расплывчато
description: Загружай, когда пользователю нужна помощь с хуками.  # Не третье лицо
description: Даёт рекомендации по хукам.  # Нет фраз-триггеров

Чтобы завершить тело SKILL.md, ответь на следующие вопросы:

1. Какова цель скилла, в нескольких предложениях?
2. Когда нужно использовать скилл? (Укажи это в description в шапке с конкретными триггерами)
3. Как на практике Claude должен использовать скилл? На всё повторно используемое содержимое скилла, разработанное выше, нужно сослаться, чтобы Claude знал, как им пользоваться.

Держи SKILL.md компактным: ориентируйся на 1 500–2 000 слов в теле. Подробное содержимое перенеси в references/:

• Подробные схемы → references/patterns.md
• Продвинутые приёмы → references/advanced.md
• Руководства по миграции → references/migration.md
• Справочники по API → references/api-reference.md

Ссылки на ресурсы в SKILL.md:

## Дополнительные ресурсы

### Справочные файлы

Подробные схемы и приёмы см. в:
- **`references/patterns.md`** - Типовые схемы
- **`references/advanced.md`** - Продвинутые сценарии

### Файлы с примерами

Рабочие примеры в `examples/`:
- **`example-script.sh`** - Рабочий пример

Шаг 5. Проверь и протестируй

Для скиллов плагинов проверка отличается от проверки универсальных скиллов:

1. Проверь структуру: каталог скилла в plugin-name/skills/skill-name/
2. Проверь SKILL.md: есть шапка с name и description
3. Проверь фразы-триггеры: описание включает конкретные запросы пользователей
4. Проверь стиль письма: тело написано в повелительной форме/инфинитиве, а не от второго лица
5. Проверь постепенное раскрытие: SKILL.md компактен (~1 500–2 000 слов), подробное содержимое лежит в references/
6. Проверь ссылки: все упомянутые файлы существуют
7. Проверь примеры: примеры полны и верны
8. Протестируй скрипты: скрипты исполняемые и работают правильно

Используй агента skill-reviewer:

Спроси: «Проверь мой скилл и посмотри, соответствует ли он лучшим практикам»

Агент skill-reviewer проверит качество описания, организацию содержимого и постепенное раскрытие.

Шаг 6. Улучшай итерациями

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

Порядок итерации:

1. Используй скилл на реальных задачах
2. Замечай затруднения и неэффективность
3. Определи, как нужно обновить SKILL.md или вложенные ресурсы
4. Внеси изменения и проверь снова

Типичные улучшения:

• Усилить фразы-триггеры в описании
• Перенести длинные разделы из SKILL.md в references/
• Добавить недостающие примеры или скрипты
• Уточнить двусмысленные инструкции
• Добавить обработку граничных случаев

Особенности плагинов

Расположение скиллов в плагинах

Скиллы плагина лежат в каталоге плагина skills/:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── references/
        ├── examples/
        └── scripts/

Автообнаружение

Claude Code автоматически обнаруживает скиллы:

• Просматривает каталог skills/
• Находит подкаталоги, содержащие SKILL.md
• Метаданные скилла (name + description) загружает всегда
• Тело SKILL.md загружает при срабатывании скилла
• Справочные материалы и примеры загружает по необходимости

Упаковка не нужна

Скиллы плагинов распространяются как часть плагина, а не отдельными ZIP-файлами. Пользователи получают скиллы при установке плагина.

Тестирование в плагинах

Проверяй скиллы, установив плагин локально:

# Test with --plugin-dir
cc --plugin-dir /path/to/plugin

# Ask questions that should trigger the skill
# Verify skill loads correctly

Примеры из plugin-dev

Изучай скиллы этого плагина как примеры лучших практик:

Скилл hook-development:

• Отличные фразы-триггеры: «создать хук», «добавить хук PreToolUse» и др.
• Компактный SKILL.md (1 651 слово)
• 3 файла в references/ с подробным содержимым
• 3 примера рабочих хуков в examples/
• 3 утилиты в scripts/

Скилл agent-development:

• Сильные триггеры: «создать агента», «шапка агента» и др.
• Сфокусированный SKILL.md (1 438 слов)
• В references лежит промт для ИИ-генерации из Claude Code
• Полные примеры агентов

Скилл plugin-settings:

• Конкретные триггеры: «настройки плагина», «файлы .local.md», «YAML-шапка»
• В references показаны реальные реализации (multi-agent-swarm, ralph-loop)
• Рабочие скрипты разбора

Каждый демонстрирует постепенное раскрытие и сильные триггеры.

Постепенное раскрытие на практике

Что кладут в SKILL.md

Включай (всегда загружается при срабатывании скилла):

• Основные понятия и обзор
• Важнейшие процедуры и рабочие процессы
• Краткие справочные таблицы
• Указатели на references/examples/scripts
• Самые частые сценарии использования

Держи в пределах 3 000 слов, в идеале 1 500–2 000 слов

Что кладут в references/

Переноси в references/ (загружается по необходимости):

• Подробные схемы и продвинутые приёмы
• Исчерпывающую документацию по API
• Руководства по миграции
• Граничные случаи и устранение неполадок
• Обширные примеры и пошаговые разборы

Каждый справочный файл может быть большим (2 000–5 000+ слов)

Что кладут в examples/

Рабочие примеры кода:

• Полные запускаемые скрипты
• Файлы конфигурации
• Файлы-шаблоны
• Примеры использования из практики

Пользователи могут копировать и адаптировать их напрямую

Что кладут в scripts/

Служебные скрипты:

• Инструменты проверки
• Помощники для тестирования
• Утилиты разбора
• Скрипты автоматизации

Должны быть исполняемыми и задокументированными

Требования к стилю письма

Повелительная форма / инфинитив

Пиши инструкциями, начинающимися с глагола, а не от второго лица:

Правильно (повелительная форма):

Чтобы создать хук, определи тип события.
Настрой MCP-сервер с аутентификацией.
Проверяй настройки перед использованием.

Неправильно (второе лицо):

Тебе следует создать хук, определив тип события.
Тебе нужно настроить MCP-сервер.
Ты должен проверить настройки перед использованием.

Третье лицо в описании

Описание в шапке должно быть написано от третьего лица:

Правильно:

description: Этот скилл следует использовать, когда пользователь просит «создать X», «настроить Y»...

Неправильно:

description: Используй этот скилл, когда хочешь создать X...
description: Загружай этот скилл, когда пользователь просит...

Объективный, поучающий язык

Сосредоточься на том, что делать, а не на том, кто должен это делать:

Правильно:

Разбери шапку с помощью sed.
Извлеки поля с помощью grep.
Проверь значения перед использованием.

Неправильно:

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

Чек-лист проверки

Перед завершением скилла:

Структура:

• [ ] Файл SKILL.md существует с корректной YAML-шапкой
• [ ] В шапке есть поля name и description
• [ ] Markdown-тело присутствует и содержательно
• [ ] Упомянутые файлы действительно существуют

Качество описания:

• [ ] Использует третье лицо («Этот скилл следует использовать, когда…»)
• [ ] Включает конкретные фразы-триггеры, которые скажут пользователи
• [ ] Перечисляет конкретные сценарии («создать X», «настроить Y»)
• [ ] Не расплывчатое и не общее

Качество содержимого:

• [ ] Тело SKILL.md написано в повелительной форме/инфинитиве
• [ ] Тело сфокусировано и компактно (идеально 1 500–2 000 слов, максимум <5 тыс.)
• [ ] Подробное содержимое перенесено в references/
• [ ] Примеры полны и работают
• [ ] Скрипты исполняемые и задокументированы

Постепенное раскрытие:

• [ ] Основные понятия в SKILL.md
• [ ] Подробная документация в references/
• [ ] Рабочий код в examples/
• [ ] Утилиты в scripts/
• [ ] SKILL.md ссылается на эти ресурсы

Тестирование:

• [ ] Скилл срабатывает на ожидаемые запросы пользователей
• [ ] Содержимое полезно для предполагаемых задач
• [ ] Информация не дублируется между файлами
• [ ] Справочные материалы загружаются при необходимости

Типичные ошибки, которых нужно избегать

Ошибка 1. Слабое описание триггеров

❌ Плохо:

description: Даёт рекомендации по работе с хуками.

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

✅ Хорошо:

description: Этот скилл следует использовать, когда пользователь просит «создать хук», «добавить хук PreToolUse», «проверять использование инструментов» или упоминает события хуков. Даёт исчерпывающие рекомендации по API хуков.

Почему хорошо: третье лицо, конкретные фразы, конкретные сценарии

Ошибка 2. Слишком много в SKILL.md

❌ Плохо:

skill-name/
└── SKILL.md  (8 000 слов — всё в одном файле)

Почему плохо: раздувает контекст при загрузке скилла, подробное содержимое загружается всегда

✅ Хорошо:

skill-name/
├── SKILL.md  (1 800 слов — основное)
└── references/
    ├── patterns.md (2 500 слов)
    └── advanced.md (3 700 слов)

Почему хорошо: постепенное раскрытие, подробное содержимое загружается только по необходимости

Ошибка 3. Письмо от второго лица

❌ Плохо:

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

Почему плохо: второе лицо, не повелительная форма

✅ Хорошо:

Начни с чтения файла конфигурации.
Проверь входные данные перед обработкой.
Используй инструмент grep для поиска по шаблонам.

Почему хорошо: повелительная форма, прямые инструкции

Ошибка 4. Нет ссылок на ресурсы

❌ Плохо:

# SKILL.md

[Основное содержимое]

[Нет упоминаний references/ или examples/]

Почему плохо: Claude не знает, что справочные материалы существуют

✅ Хорошо:

# SKILL.md

[Основное содержимое]

## Дополнительные ресурсы

### Справочные файлы
- **`references/patterns.md`** - Подробные схемы
- **`references/advanced.md`** - Продвинутые приёмы

### Примеры
- **`examples/script.sh`** - Рабочий пример

Почему хорошо: Claude знает, где искать дополнительную информацию

Краткая справка

Минимальный скилл

skill-name/
└── SKILL.md

Подходит для: простых знаний, когда сложные ресурсы не нужны

Стандартный скилл (рекомендуется)

skill-name/
├── SKILL.md
├── references/
│   └── detailed-guide.md
└── examples/
    └── working-example.sh

Подходит для: большинства скиллов плагинов с подробной документацией

Полный скилл

skill-name/
├── SKILL.md
├── references/
│   ├── patterns.md
│   └── advanced.md
├── examples/
│   ├── example1.sh
│   └── example2.json
└── scripts/
    └── validate.sh

Подходит для: сложных областей с утилитами проверки

Краткая сводка лучших практик

✅ ДЕЛАЙ:

• Используй третье лицо в описании («Этот скилл следует использовать, когда…»)
• Включай конкретные фразы-триггеры («создать X», «настроить Y»)
• Держи SKILL.md компактным (1 500–2 000 слов)
• Используй постепенное раскрытие (переноси детали в references/)
• Пиши в повелительной форме/инфинитиве
• Чётко ссылайся на вспомогательные файлы
• Приводи рабочие примеры
• Создавай служебные скрипты для типовых операций
• Изучай скиллы plugin-dev как образцы

❌ НЕ ДЕЛАЙ:

• Не используй второе лицо нигде
• Не оставляй расплывчатые условия срабатывания
• Не клади всё в SKILL.md (>3 000 слов без references/)
• Не пиши от второго лица («Тебе следует…»)
• Не оставляй ресурсы без ссылок
• Не включай сломанные или неполные примеры
• Не пропускай проверку

Дополнительные ресурсы

Изучи эти скиллы

Скиллы plugin-dev демонстрируют лучшие практики:

• ../hook-development/ — постепенное раскрытие, утилиты
• ../agent-development/ — создание с помощью ИИ, справочные материалы
• ../mcp-integration/ — исчерпывающие справочные материалы
• ../plugin-settings/ — примеры из практики
• ../command-development/ — чёткие критические понятия
• ../plugin-structure/ — хорошая организация

Справочные файлы

Полная методология skill-creator:

• **references/skill-creator-original.md** — полное оригинальное содержимое skill-creator

Порядок реализации

Чтобы создать скилл для своего плагина:

1. Пойми сценарии использования: определи конкретные примеры использования скилла
2. Спланируй ресурсы: определи, какие скрипты/справочные материалы/примеры нужны
3. Создай структуру: mkdir -p skills/skill-name/{references,examples,scripts}
4. Напиши SKILL.md:
5. Шапка с описанием от третьего лица и фразами-триггерами
6. Компактное тело (1 500–2 000 слов) в повелительной форме
7. Ссылки на вспомогательные файлы
8. Добавь ресурсы: создай references/, examples/, scripts/ по необходимости
9. Проверь: описание, стиль письма, организацию
10. Протестируй: убедись, что скилл загружается на ожидаемые триггеры
11. Улучшай итерациями: дорабатывай по итогам использования

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

Перевод: iiuniversitet. Оригинал: https://github.com/anthropics/claude-plugins-official/tree/main/plugins/plugin-dev/skills/skill-development, лицензия Apache-2.0. Изменения: перевод на русский язык.