Создание 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

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

Разработка более сложных 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

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

По мере внесения изменений в ваш 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

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

• Claude.ai: claude.ai/settings/plugins/submit
• Console: platform.claude.com/plugins/submit

Когда ваш plugin будет указан, вы сможете иметь собственный 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: интеграция внешних инструментов