Создание plugins

Создавайте пользовательские plugins для расширения Claude Code с помощью skills, agents, hooks и MCP servers.

Plugins позволяют расширить Claude Code пользовательской функциональностью, которая может быть общей для проектов и команд. Это руководство охватывает создание собственных plugins с skills, agents, hooks и MCP servers.

Ищете установку существующих plugins? См. Обнаружение и установка plugins. Для полных технических спецификаций см. Справочник plugins.

Когда использовать plugins в сравнении с автономной конфигурацией

Claude Code поддерживает два способа добавления пользовательских skills, agents и hooks:

Используйте автономную конфигурацию когда:

• Вы настраиваете Claude Code для одного проекта
• Конфигурация личная и не требует совместного использования
• Вы экспериментируете с skills или hooks перед их упаковкой
• Вы хотите короткие имена skills, такие как /hello или /deploy

Используйте plugins когда:

• Вы хотите поделиться функциональностью с вашей командой или сообществом
• Вам нужны одинаковые skills/agents в нескольких проектах
• Вы хотите контроль версий и простые обновления для ваших расширений
• Вы распространяете через marketplace
• Вы согласны с пространством имён skills, такими как /my-plugin:hello (пространство имён предотвращает конфликты между plugins)

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

Этот быстрый старт проведёт вас через создание plugin с пользовательским skill. Вы создадите манифест (файл конфигурации, который определяет ваш plugin), добавите skill и протестируете его локально, используя флаг --plugin-dir.

Предварительные требования

• Claude Code установлен и аутентифицирован

Создайте ваш первый plugin

mkdir my-first-plugin

mkdir my-first-plugin/.claude-plugin

{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}

mkdir -p my-first-plugin/skills/hello

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

claude --plugin-dir ./my-first-plugin

/my-first-plugin:hello

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

/my-first-plugin:hello Alex

Вы успешно создали и протестировали plugin с этими ключевыми компонентами:

• Манифест plugin (.claude-plugin/plugin.json): описывает метаданные вашего plugin
• Директория skills (skills/): содержит ваши пользовательские skills
• Аргументы skill ($ARGUMENTS): захватывает пользовательский ввод для динамического поведения

Разработка plugin в вашей директории skills

Вместо передачи --plugin-dir при каждом запуске, вы можете сохранить plugin в вашей директории skills и позволить Claude Code загружать его автоматически. claude plugin init создаёт каркас:

claude plugin init my-tool

Это создаёт ~/.claude/skills/my-tool/ с манифестом .claude-plugin/plugin.json и стартовым SKILL.md. На следующем сеансе он загружается как my-tool@skills-dir без marketplace или шага установки.

Для правил автозагрузки, личной и проектной области, требования доверия рабочей области и способов обновления или удаления, см. Skills-directory plugins.

Обзор структуры plugin

Вы создали plugin с skill, но plugins могут включать намного больше: пользовательские agents, hooks, MCP servers, LSP servers и фоновые мониторы.

Plugin, который поставляется ровно с одним skill, может поместить SKILL.md непосредственно в корень plugin вместо создания директории skills/. Claude Code загружает его как один skill и использует поле frontmatter name для имени вызова. Используйте макет skills/ для plugins, которые могут расширяться до более чем одного skill.

Разработка более сложных plugins

Когда вы будете комфортно чувствовать себя с базовыми plugins, вы сможете создавать более сложные расширения.

Добавьте Skills в ваш plugin

Plugins могут включать Agent Skills для расширения возможностей Claude. Skills вызываются моделью: Claude автоматически использует их на основе контекста задачи.

Добавьте директорию skills/ в корень вашего plugin с папками Skill, содержащими файлы SKILL.md:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── code-review/
        └── SKILL.md

Каждый SKILL.md содержит YAML frontmatter и инструкции. Включите description чтобы Claude знал, когда использовать skill:

---
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

После установки plugin запустите /reload-plugins для загрузки Skills. Для полного руководства по созданию Skill, включая прогрессивное раскрытие и ограничения инструментов, см. Agent Skills.

Добавьте LSP servers в ваш plugin

LSP (Language Server Protocol) plugins дают Claude интеллект кода в реальном времени. Если вам нужна поддержка языка, который не имеет официального LSP plugin, вы можете создать свой собственный, добавив файл .lsp.json в ваш plugin:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Пользователи, устанавливающие ваш plugin, должны иметь двоичный файл языкового сервера, установленный на их машине.

Для полных опций конфигурации LSP см. LSP servers.

Добавьте фоновые мониторы в ваш plugin

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

Добавьте файл monitors/monitors.json в корень plugin с массивом записей монитора:

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

Каждая строка stdout из command доставляется Claude как уведомление во время сеанса. Для полной схемы, включая триггер when и подстановку переменных, см. Monitors.

Поставляйте параметры по умолчанию с вашим plugin

Plugins могут включать файл settings.json в корне plugin для применения конфигурации по умолчанию при включении plugin. В настоящее время поддерживаются только ключи agent и subagentStatusLine.

Установка agent активирует один из пользовательских agents plugin в качестве основного потока, применяя его системный prompt, ограничения инструментов и модель. Это позволяет plugin изменить поведение Claude Code по умолчанию при включении.

{
  "agent": "security-reviewer"
}

Этот пример активирует agent security-reviewer, определённый в директории agents/ plugin. Параметры из settings.json имеют приоритет над settings, объявленными в plugin.json. Неизвестные ключи молча игнорируются.

Организуйте сложные plugins

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

Протестируйте ваши plugins локально

Используйте флаг --plugin-dir для тестирования plugins во время разработки. Это загружает ваш plugin напрямую без необходимости установки.

claude --plugin-dir ./my-plugin

Флаг также принимает архив .zip директории plugin, для которого требуется Claude Code v2.1.128 или более поздняя версия.

claude --plugin-dir ./my-plugin.zip

Когда --plugin-dir plugin имеет то же имя, что и установленный marketplace plugin, локальная копия имеет приоритет для этого сеанса. Это позволяет вам протестировать изменения plugin, который у вас уже установлен, без необходимости его предварительной деинсталляции. Исключением являются plugins, которые управляемые параметры принудительно включают или отключают: --plugin-dir не может переопределить эти параметры.

По мере внесения изменений в ваш plugin запустите /reload-plugins для применения обновлений без перезагрузки. Это перезагружает plugins, skills, agents, hooks, plugin MCP servers и plugin LSP servers. Протестируйте компоненты вашего plugin:

• Попробуйте ваши skills с /plugin-name:skill-name
• Проверьте, что agents появляются в /agents
• Убедитесь, что hooks работают как ожидается

Чтобы протестировать plugin, который уже упакован как архив .zip и размещён по URL-адресу, например артефакт сборки CI, используйте вместо этого --plugin-url. Claude Code загружает архив при запуске и загружает его только для этого сеанса. Если загрузка не удаётся или архив недействителен, Claude Code сообщает об ошибке загрузки plugin и запускается без него. Те же соображения доверия применяются как для любого источника plugin: указывайте этот флаг только на архивы, которыми вы управляете или которым доверяете.

Чтобы загружать несколько plugins, повторите флаг для каждого URL:

claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip

Или передайте разделённые пробелами URL-адреса как один аргумент в кавычках:

claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip"

Отладка проблем plugin

Если ваш plugin не работает как ожидается:

1. Проверьте структуру: Убедитесь, что ваши директории находятся в корне plugin, а не внутри .claude-plugin/
2. Протестируйте компоненты отдельно: Проверьте каждый skill, agent и hook отдельно
3. Используйте инструменты валидации и отладки: См. Инструменты отладки и разработки для команд CLI и методов troubleshooting

Поделитесь вашими plugins

Когда ваш plugin готов к совместному использованию:

1. Добавьте документацию: Включите README.md с инструкциями по установке и использованию
2. Выберите стратегию версионирования: Решите, устанавливать ли явную version или полагаться на SHA коммита git. См. управление версиями
3. Создайте или используйте marketplace: Распространяйте через plugin marketplaces для установки
4. Протестируйте с другими: Попросите членов команды протестировать plugin перед более широким распространением

Когда ваш plugin находится в marketplace, другие могут установить его, используя инструкции в Обнаружение и установка plugins. Чтобы сохранить plugin внутри вашей команды, разместите marketplace в приватном репозитории.

Отправьте ваш plugin на официальный marketplace сообщества

Anthropic поддерживает два публичных marketplace для plugins Claude Code:

• claude-plugins-official: курируемый набор plugins, поддерживаемый Anthropic. Зарегистрирован автоматически при первом запуске Claude Code в интерактивном режиме. Неинтерактивный скрипт, который запускается перед этим первым запуском, должен добавить его явно с помощью claude plugin marketplace add anthropics/claude-plugins-official.
• claude-community: публичный marketplace сообщества, где размещаются сторонние отправки после проверки. Пользователи добавляют его с помощью /plugin marketplace add anthropics/claude-plugins-community и устанавливают из него как @claude-community.

Чтобы отправить ваш plugin на проверку в marketplace сообщества, используйте одну из встроенных форм:

• claude.ai: claude.ai/admin-settings/directory/submissions/plugins/new
• Console: platform.claude.com/plugins/submit

Форма claude.ai требует организацию Team или Enterprise и доступ к управлению директорией; владельцы организации имеют этот доступ по умолчанию. Отдельные авторы, которые не являются частью организации Team или Enterprise, могут использовать форму Console вместо этого.

Запустите claude plugin validate локально перед отправкой. Конвейер проверки запускает ту же проверку для каждой отправки, а также автоматизированный скрининг безопасности.

Одобренные plugins закреплены на определённом коммите SHA в каталоге anthropics/claude-plugins-community, и CI автоматически обновляет закрепление по мере того, как вы отправляете новые коммиты в ваш репозиторий. Публичный каталог синхронизируется ночью из конвейера проверки, поэтому может быть задержка между одобрением и появлением вашего plugin в marketplace.json. Чтобы проверить, установлен ли ваш plugin, выполните поиск его имени в каталоге сообщества.

Официальный marketplace claude-plugins-official курируется отдельно. Anthropic решает, какие plugins включить по своему усмотрению. Нет процесса подачи заявки, и форма отправки не добавляет plugins в официальный marketplace.

Если Anthropic включит ваш plugin в официальный marketplace, ваш CLI может предложить пользователям Claude Code установить его. См. Рекомендуйте ваш plugin из вашего CLI.

Преобразование существующих конфигураций в plugins

Если у вас уже есть skills или hooks в вашей директории .claude/, вы можете преобразовать их в plugin для более лёгкого совместного использования и распространения.

Шаги миграции

mkdir -p my-plugin/.claude-plugin

{
"name": "my-plugin",
"description": "Migrated from standalone configuration",
"version": "1.0.0"
}

# Copy commands
cp -r .claude/commands my-plugin/

# Copy agents (if any)
cp -r .claude/agents my-plugin/

# Copy skills (if any)
cp -r .claude/skills my-plugin/

mkdir my-plugin/hooks

{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
}
]
}
}

claude --plugin-dir ./my-plugin

Что изменяется при миграции

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

Теперь, когда вы понимаете систему plugins Claude Code, вот предлагаемые пути для различных целей:

Для пользователей plugin

• Обнаружение и установка plugins: просмотр marketplaces и установка plugins
• Настройка team marketplaces: установка plugins на уровне репозитория для вашей команды

Для разработчиков plugin

• Создание и распространение marketplace: упаковка и совместное использование ваших plugins
• Справочник plugins: полные технические спецификации
• Углубитесь в конкретные компоненты plugin:
  • Skills: детали разработки skill
  • Subagents: конфигурация и возможности agent
  • Hooks: обработка событий и автоматизация
  • MCP: интеграция внешних инструментов