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

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

## Что такое плагин?

### Основные понятия

Плагин Claude Code — это директория с определённой файловой структурой, которая может добавлять следующие компоненты:

| Компонент | Описание | Формат файлов |
|-----------|----------|---------------|
| **Commands (Команды)** | Пользовательские слэш-команды | Файлы `.md` |
| **Agents (Агенты)** | Субагенты для специализированных задач | Файлы `.md` |
| **Skills (Навыки)** | Переиспользуемые знания и способности | Директория + `SKILL.md` |
| **Hooks (Хуки)** | Автоматизация по событиям | `hooks.json` |

### Зачем нужны плагины?

- **Стандартизация для команды**: превращение стандартов кодирования и критериев ревью в исполняемые команды

- **Автоматизация рабочих процессов**: автоматизация повторяющихся задач — коммиты, деплой, ревью

- **Обмен знаниями**: совместное использование лучших практик и экспертизы в команде

- **Настройка под проект**: адаптация поведения Claude под потребности проекта

## Структура директории плагина

```
my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Обязательно: манифест плагина
├── commands/                 # Слэш-команды (файлы .md)
│   ├── review.md
│   └── deploy.md
├── agents/                   # Определения субагентов (файлы .md)
│   └── code-reviewer.md
├── skills/                   # Навыки агента (поддиректории)
│   └── coding-standards/
│       └── SKILL.md
├── hooks/
│   └── hooks.json           # Конфигурация обработчиков событий
├── .mcp.json                # Определения MCP-серверов (необязательно)
└── scripts/                 # Вспомогательные скрипты (необязательно)
```

## Быстрый старт

### Установка плагина

```bash
# Установка из маркетплейса
/plugin install plugin-name@claude-code-marketplace

# Установка из локальной директории
claude --plugin-dir /path/to/my-plugin
```

### Мастер создания плагина

```bash
/plugin-dev:create-plugin
```

Эта команда проведёт вас через 8 этапов создания полноценного плагина.

## Создание пользовательских команд

### Базовый формат команды

Создайте файл `.md` в директории `commands/`:

```markdown
---
description: Выполнить ревью кода
argument-hint: [file-path]
allowed-tools: Read, Bash(git:*)
---

Проведи ревью качества кода файла: @$1

Обрати внимание на:
1. Читаемость кода
2. Потенциальные баги
3. Проблемы производительности
4. Уязвимости безопасности
```

### Конфигурация YAML frontmatter

| Поле | Описание | Пример |
|------|----------|--------|
| `description` | Описание команды (отображается в /help) | `Выполнить ревью кода` |
| `argument-hint` | Подсказка по параметрам | `[file-path] [options]` |
| `allowed-tools` | Разрешённые инструменты | `Read, Bash(git:*)` |
| `model` | Указание модели | `opus` или `sonnet` |

### Использование динамических параметров

- `$1`, `$2`, `$3`... — позиционные параметры

- `$ARGUMENTS` — все параметры

- `@path/to/file` — ссылка на файл

- `!`command`` — выполнение Bash-команды

### Примеры команд

**Команда ревью кода** (`commands/review.md`):

```markdown
---
description: Полное ревью кода
argument-hint: [file-or-directory]
allowed-tools: Read, Grep, Glob
model: opus
---

Проведи полное ревью кода @$1.

Чеклист:
- [ ] Соответствует ли стиль кода стандартам проекта
- [ ] Есть ли потенциальные проблемы безопасности
- [ ] Достаточна ли обработка ошибок
- [ ] Нужно ли добавить тесты

Если указана директория, сначала используй инструмент Glob для поиска всех релевантных файлов.
```

**Команда умного коммита** (`commands/commit.md`):

```markdown
---
description: Умная генерация коммита и фиксация
allowed-tools: Bash(git:*)
---

1. Выполни `git status` для просмотра изменений
2. Выполни `git diff --staged` для анализа подготовленных изменений
3. Сгенерируй стандартное сообщение коммита на основе изменений
4. Выполни `git commit`

Формат сообщения коммита:
- feat: новая функциональность
- fix: исправление бага
- docs: обновление документации
- refactor: рефакторинг
- test: связанное с тестированием
```

## Создание пользовательских агентов

### Формат определения агента

Создайте файл `.md` в директории `agents/`:

```markdown
---
description: Специализированный агент для ревью кода
model: opus
tools: Read, Grep, Glob
---

Ты — профессиональный агент для ревью кода. Твоя задача:

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

Всегда будь конструктивен и конкретен.
```

### Типы агентов

| Тип | Назначение | Пример |
|-----|------------|--------|
| Ревью-агент | Ревью кода, ревью PR | `code-reviewer` |
| Тестовый агент | Генерация и запуск тестов | `test-generator` |
| Документационный агент | Генерация документации | `doc-writer` |
| Агент рефакторинга | Рефакторинг кода | `refactorer` |

## Создание навыков

### Структура директории навыков

```
skills/
└── coding-standards/
    ├── SKILL.md              # Обязательно: определение навыка
    ├── references/           # Справочные материалы
    │   └── style-guide.md
    └── examples/             # Примеры кода
        └── good-practices.md
```

### Формат SKILL.md

```markdown
# Навык стандартов кодирования

## Обзор
Этот навык содержит стандарты кодирования и лучшие практики команды.

## Содержание знаний

### Соглашения об именовании
- Переменные: camelCase
- Константы: UPPER_SNAKE_CASE
- Классы: PascalCase
- Файлы: kebab-case

### Стиль кода
- Отступ 2 пробела
- Максимальная длина строки 100 символов
- Использование точки с запятой

### Обработка ошибок
- Всегда использовать try-catch
- Логировать ошибки
- Предоставлять осмысленные сообщения об ошибках
```

## Создание хуков

### Формат hooks.json

```json
{
  "hooks": [
    {
      "event": "on_commit",
      "command": "npm run lint",
      "description": "Проверка lint перед коммитом"
    },
    {
      "event": "on_file_change",
      "pattern": "*.ts",
      "command": "npm run typecheck",
      "description": "Проверка типов при изменении TypeScript-файлов"
    }
  ]
}
```

### Поддерживаемые события

| Событие | Момент срабатывания |
|---------|---------------------|
| `on_commit` | При коммите кода |
| `on_file_change` | При изменении файла |
| `on_session_start` | При начале сессии |
| `on_command` | При выполнении команды |

## Манифест плагина

### Формат plugin.json

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Мой пользовательский плагин",
  "author": "Your Name",
  "components": {
    "commands": ["commands/*.md"],
    "agents": ["agents/*.md"],
    "skills": ["skills/*/SKILL.md"],
    "hooks": "hooks/hooks.json"
  },
  "mcpServers": ".mcp.json"
}
```

## Практические примеры

### Пример 1: Плагин командного ревью кода

```
team-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── review-pr.md          # Команда ревью PR
│   ├── security-check.md     # Команда проверки безопасности
│   └── perf-audit.md         # Команда аудита производительности
├── agents/
│   ├── security-reviewer.md  # Агент проверки безопасности
│   └── perf-analyzer.md      # Агент анализа производительности
└── skills/
    └── team-standards/
        └── SKILL.md          # Навык командных стандартов
```

### Пример 2: Плагин автоматизации деплоя

```
deploy-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── deploy-staging.md     # Деплой в тестовую среду
│   ├── deploy-prod.md        # Деплой в продакшен
│   └── rollback.md           # Команда отката
├── hooks/
│   └── hooks.json            # Хуки предварительной проверки деплоя
└── .mcp.json                 # Конфигурация Kubernetes MCP
```

## Лучшие практики

### Проектирование команд

1. **Единственная ответственность**: каждая команда делает только одну вещь

2. **Понятное описание**: description должен быть кратким и ясным

3. **Документация параметров**: используйте argument-hint для описания параметров

4. **Минимальные привилегии**: allowed-tools содержит только необходимые инструменты

5. **Обработка ошибок**: учитывайте сценарии неудач

### Организация плагина

1. **Модульность**: связанная функциональность группируется вместе

2. **Переиспользуемость**: навыки должны быть доступны нескольким командам

3. **Документация**: добавьте README и инструкции по использованию

4. **Управление версиями**: используйте семантическое версионирование

### Вопросы безопасности

1. **Не хардкодьте ключи**: используйте переменные окружения

2. **Ограничивайте доступ к файлам**: обращайтесь только к необходимым путям

3. **Валидируйте входные данные**: проверяйте параметры

4. **Журнал аудита**: логируйте чувствительные операции

## Отладка плагинов

```bash
# Просмотр статуса загруженных плагинов
/plugin list

# Просмотр деталей команды
/help my-command

# Тестирование команды
/my-command test-argument
```

## Следующие шаги

- Изучите [MCP-серверы](/docs/advanced/mcp) для расширения внешних интеграций

- Смотрите [Советы по CLI](/docs/usage/cli-tips) для повышения эффективности

- Исследуйте [Советы по рабочим процессам](/docs/usage/workflow-tips) для оптимизации процесса разработки