Зачем это нужно#

Готовые плагины не всегда покрывают ваши задачи. Создание своего плагина позволяет:

• 🎯 Автоматизировать повторяющиеся рабочие процессы
• 👥 Делиться инструментами с командой
• 📦 Упаковать знания и практики в переносимый формат
• 🏪 Опубликовать плагин для сообщества

В этом уроке мы создадим плагин с нуля, используя материалы из плагина plugin-dev.

Шаг 1: Создаём структуру папок#

# Создаём папку плагина
mkdir -p my-awesome-plugin/.claude-plugin
mkdir -p my-awesome-plugin/commands
mkdir -p my-awesome-plugin/agents
mkdir -p my-awesome-plugin/skills/my-skill
mkdir -p my-awesome-plugin/hooks

Получится такая структура:

my-awesome-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
├── skills/
│   └── my-skill/
└── hooks/

Шаг 2: Создаём манифест (plugin.json)#

Файл .claude-plugin/plugin.json — это «паспорт» вашего плагина:

{
  "name": "my-awesome-plugin",
  "version": "1.0.0",
  "description": "Плагин для автоматизации моих рабочих процессов",
  "author": {
    "name": "Ваше Имя",
    "email": "you@example.com"
  },
  "keywords": ["automation", "workflow"]
}

Доступные поля манифеста#

Шаг 3: Создаём команду (Command)#

Команда — это слэш-команда, которую пользователь вводит в Claude Code (например, /my-plugin:hello).

Создайте файл commands/hello.md:

---
name: hello
description: Приветствует пользователя и показывает информацию о проекте
---

# Команда Hello

Выполни следующие действия:

1. Поприветствуй пользователя дружелюбным сообщением
2. Покажи текущую дату и время
3. Если есть файл README.md — кратко опиши проект
4. Предложи, с чего начать работу

Будь дружелюбным и позитивным!

Frontmatter — заголовок команды#

Блок между --- и --- называется frontmatter (метаданные). Он содержит:

• name — имя команды (как будет вызываться)
• description — описание (отображается в подсказках)

Команда с аргументами#

Создайте commands/review-file.md:

---
name: review-file
description: Проверяет указанный файл на ошибки и стиль
---

# Ревью файла

Пользователь хочет проверить файл: $ARGUMENTS

Выполни следующие проверки:
1. Синтаксические ошибки
2. Стилевые несоответствия
3. Потенциальные проблемы безопасности
4. Предложения по улучшению

Покажи результат в виде структурированного отчёта.

$ARGUMENTS — специальная переменная, которая содержит текст после команды. Если пользователь введёт /my-plugin:review-file src/app.js, то $ARGUMENTS будет равен src/app.js.

Шаг 4: Создаём агента (Agent)#

Агент — это специализированный помощник, который Claude Code может вызвать для решения конкретной задачи. В отличие от команды, агент работает в своём собственном контексте.

Создайте файл agents/code-checker.md:

---
name: code-checker
description: Специализированный агент для проверки качества кода
---

# Агент проверки качества кода

Ты — эксперт по качеству кода. Твоя задача:

1. Проанализируй предоставленный код
2. Найди потенциальные ошибки
3. Проверь соблюдение лучших практик
4. Предложи конкретные улучшения

## Правила работы

- Всегда объясняй **почему** что-то является проблемой
- Приводи примеры правильного кода
- Сортируй замечания по критичности: 🔴 критично, 🟡 важно, 🟢 рекомендация

Шаг 5: Создаём навык (Skill)#

Навык (Skill) — это база знаний, которую Claude Code автоматически загружает при необходимости. В отличие от команды, навык не вызывается напрямую — Claude сам обращается к нему, когда тема релевантна.

Создайте файл skills/my-skill/SKILL.md:

---
name: Мой навык стилей кодирования
description: Используй этот навык, когда пользователь просит написать или проверить код на Python
version: 0.1.0
---

# Стиль кодирования Python

## Правила

1. Используй type hints для всех функций
2. Docstrings в формате Google
3. Максимальная длина строки — 88 символов (формат Black)
4. Импорты сортируй с помощью isort

## Пример хорошего кода

```python
def calculate_total(items: list[dict], tax_rate: float = 0.1) -> float:
    """Рассчитывает общую сумму с учётом налога.

    Args:
        items: Список товаров с полем 'price'.
        tax_rate: Ставка налога (по умолчанию 10%).

    Returns:
        Общая сумма с налогом.
    """
    subtotal = sum(item["price"] for item in items)
    return subtotal * (1 + tax_rate)

## Шаг 6: Добавляем хуки

Создайте файл `hooks/hooks.json`:

```json
{
  "description": "Хуки для проверки качества кода",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Проверь, что файл содержит комментарии и не содержит захардкоженных паролей или API-ключей. Верни 'approve' если всё в порядке или 'deny' с объяснением.",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

Шаг 7: Тестируем плагин#

# Запускаем Claude Code с нашим плагином
claude --plugin-dir ./my-awesome-plugin

# Внутри Claude Code пробуем команды:
> /my-awesome-plugin:hello
> /my-awesome-plugin:review-file src/main.py

Для отладки:

claude --plugin-dir ./my-awesome-plugin --debug

Сравнение компонентов плагина#

Итоги урока#

• Плагин создаётся из папки с манифестом plugin.json и компонентами
• Команды — это Markdown-файлы с инструкциями для Claude, вызываемые через /
• Агенты — специализированные помощники для сложных задач
• Навыки — базы знаний, загружаемые автоматически
• Хуки — автоматические проверки при событиях
• $ARGUMENTS передаёт аргументы команды
• Тестируйте плагин с --plugin-dir и отлаживайте с --debug