Справочник по плагинам

Полный технический справочник по системе плагинов Claude Code, включая схемы, команды CLI и спецификации компонентов.

Этот справочник содержит полные технические спецификации для системы плагинов Claude Code, включая схемы компонентов, команды CLI и инструменты разработки.

Плагин — это самостоятельный каталог компонентов, который расширяет Claude Code пользовательской функциональностью. Компоненты плагина включают skills, agents, hooks, MCP servers, LSP servers и monitors.

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

Skills

Плагины добавляют skills в Claude Code, создавая сочетания клавиш /name, которые вы или Claude можете вызвать.

Расположение: каталог skills/ или commands/ в корне плагина

Формат файла: Skills — это каталоги с SKILL.md; команды — это простые файлы markdown

Структура skill:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (опционально)
│   └── scripts/ (опционально)
└── code-reviewer/
    └── SKILL.md

Поведение интеграции:

• Skills и команды автоматически обнаруживаются при установке плагина
• Claude может вызывать их автоматически на основе контекста задачи
• Skills могут включать вспомогательные файлы рядом с SKILL.md

Для полной информации смотрите Skills.

Agents

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

Расположение: каталог agents/ в корне плагина

Формат файла: Файлы markdown, описывающие возможности агента

Структура агента:

---
name: agent-name
description: Что специализирует этот агент и когда Claude должен его вызвать
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Подробное системное приглашение для агента, описывающее его роль, опыт и поведение.

Плагины agents поддерживают поля frontmatter name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background и isolation. Единственное допустимое значение isolation — это "worktree". По соображениям безопасности hooks, mcpServers и permissionMode не поддерживаются для agents, поставляемых с плагинами.

Точки интеграции:

• Агенты появляются в интерфейсе /agents
• Claude может вызывать агентов автоматически на основе контекста задачи
• Агенты могут быть вызваны вручную пользователями
• Плагины agents работают наряду со встроенными agents Claude

Для полной информации смотрите Subagents.

Hooks

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

Расположение: hooks/hooks.json в корне плагина или встроенный в plugin.json

Формат: Конфигурация JSON с сопоставителями событий и действиями

Конфигурация hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

Плагины hooks реагируют на те же события жизненного цикла, что и определённые пользователем hooks:

Типы hook:

• command: выполнение команд оболочки или скриптов
• http: отправка JSON события как POST запроса на URL
• mcp_tool: вызов инструмента на настроенном MCP server
• prompt: оценка приглашения с помощью LLM (использует заполнитель $ARGUMENTS для контекста)
• agent: запуск проверки агента с инструментами для сложных задач проверки

MCP servers

Плагины могут включать серверы Model Context Protocol (MCP) для подключения Claude Code к внешним инструментам и сервисам.

Расположение: .mcp.json в корне плагина или встроенный в plugin.json

Формат: Стандартная конфигурация сервера MCP

Конфигурация сервера MCP:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

Поведение интеграции:

• Серверы MCP плагина запускаются автоматически при включении плагина
• Серверы отображаются как стандартные инструменты MCP в наборе инструментов Claude
• Возможности сервера беспрепятственно интегрируются с существующими инструментами Claude
• Серверы плагина можно настраивать независимо от серверов MCP пользователя

LSP servers

Плагины могут предоставлять серверы Language Server Protocol (LSP) для предоставления Claude интеллектуальной информации о коде в реальном времени при работе с вашей кодовой базой.

Интеграция LSP предоставляет:

• Мгновенная диагностика: Claude видит ошибки и предупреждения сразу после каждого редактирования
• Навигация по коду: переход к определению, поиск ссылок и информация при наведении
• Осведомлённость о языке: информация о типах и документация для символов кода

Расположение: .lsp.json в корне плагина или встроенный в plugin.json

Формат: Конфигурация JSON, сопоставляющая имена языковых серверов с их конфигурациями

Формат файла .lsp.json:

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

Встроенный в plugin.json:

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

Обязательные поля:

Опциональные поля:

Доступные плагины LSP:

Сначала установите языковой сервер, затем установите плагин из маркетплейса.

Monitors

Плагины могут объявлять фоновые monitors, которые Claude Code автоматически запускает при активации плагина. Каждый monitor запускает команду оболочки на протяжении всего сеанса и доставляет каждую строку stdout Claude как уведомление, чтобы Claude мог реагировать на записи журнала, изменения статуса или опрашиваемые события без необходимости просить запустить наблюдение.

Плагины monitors используют тот же механизм, что и инструмент Monitor, и разделяют его ограничения доступности. Они работают только в интерактивных сеансах CLI, работают без песочницы на том же уровне доверия, что и hooks, и пропускаются на хостах, где инструмент Monitor недоступен.

Расположение: monitors/monitors.json в корне плагина или встроенный в plugin.json

Формат: Массив JSON записей monitor

Следующий monitors/monitors.json отслеживает конечную точку статуса развёртывания и локальный журнал ошибок:

[
  {
    "name": "deploy-status",
    "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

Для объявления monitors встроенным образом установите experimental.monitors в plugin.json на тот же массив. Для загрузки из пути, отличного от пути по умолчанию, установите experimental.monitors на строку относительного пути, такую как "./config/monitors.json". Monitors — это экспериментальный компонент.

Обязательные поля:

Опциональные поля:

Значение command поддерживает те же подстановки переменных, что и конфигурации серверов MCP и LSP: ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, ${user_config.*} и любой ${ENV_VAR} из окружения. Добавьте префикс команды с cd "${CLAUDE_PLUGIN_ROOT}" && , если скрипт должен работать из собственного каталога плагина.

Отключение плагина в середине сеанса не останавливает monitors, которые уже работают. Они останавливаются при завершении сеанса.

Themes

Плагины могут поставлять цветовые темы, которые появляются в /theme наряду со встроенными предустановками и локальными темами пользователя. Тема — это JSON файл в themes/ с предустановкой base и разреженной картой переопределений overrides цветовых токенов. Themes — это экспериментальный компонент.

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

Выбор темы плагина сохраняет custom:<plugin-name>:<slug> в конфигурации пользователя. Темы плагина доступны только для чтения; нажатие Ctrl+E на одной из них в /theme копирует её в ~/.claude/themes/, чтобы пользователь мог редактировать копию.

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

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

Плагины используют ту же систему областей, что и другие конфигурации Claude Code. Для инструкций по установке и флагов области смотрите Установка плагинов. Для полного объяснения областей смотрите Области конфигурации.

Схема манифеста плагина

Файл .claude-plugin/plugin.json определяет метаданные и конфигурацию вашего плагина. Этот раздел документирует все поддерживаемые поля и опции.

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

Полная схема

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Обязательные поля

Если вы включаете манифест, name — единственное обязательное поле.

Это имя используется для пространства имён компонентов. Например, в пользовательском интерфейсе агент agent-creator для плагина с именем plugin-dev будет отображаться как plugin-dev:agent-creator.

Поля метаданных

Поля пути компонента

Экспериментальные компоненты

Компоненты под ключом experimental, themes и monitors, имеют схему манифеста, которая может измениться между выпусками во время их стабилизации. Место, где вы их объявляете, — это отдельная миграция: верхний уровень всё ещё работает, claude plugin validate выдаёт предупреждение, и будущий выпуск потребует experimental.*.

Конфигурация пользователя

Поле userConfig объявляет значения, которые Claude Code запрашивает у пользователя при включении плагина. Используйте это вместо требования пользователям вручную редактировать settings.json.

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

Ключи должны быть допустимыми идентификаторами. Каждое значение поддерживает эти поля:

Каждое значение доступно для подстановки как ${user_config.KEY} в конфигурациях серверов MCP и LSP, командах hooks и командах monitors. Нечувствительные значения также могут быть подставлены в содержимое skills и agents. Все значения экспортируются в подпроцессы плагина как переменные окружения CLAUDE_PLUGIN_OPTION_<KEY>.

Нечувствительные значения хранятся в settings.json под pluginConfigs[<plugin-id>].options. Чувствительные значения переходят в системный keychain (или ~/.claude/.credentials.json, где keychain недоступен). Хранилище keychain общее с OAuth токенами и имеет приблизительный лимит 2 КБ, поэтому держите чувствительные значения небольшими.

Каналы

Поле channels позволяет плагину объявить один или несколько каналов сообщений, которые внедряют содержимое в разговор. Каждый канал привязывается к серверу MCP, который предоставляет плагин.

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

Поле server обязательно и должно соответствовать ключу в mcpServers плагина. Опциональный userConfig для каждого канала использует ту же схему, что и поле верхнего уровня, позволяя плагину запрашивать токены ботов или ID владельцев при включении плагина.

Правила поведения пути

Замена ли пользовательский путь или расширяет каталог по умолчанию плагина, зависит от поля:

• Заменяет по умолчанию: commands, agents, outputStyles, experimental.themes, experimental.monitors. Например, когда манифест указывает commands, каталог по умолчанию commands/ не сканируется. Чтобы сохранить по умолчанию и добавить больше, перечислите его явно: "commands": ["./commands/", "./extras/"]
• Добавляет к по умолчанию: skills. Каталог по умолчанию skills/ всегда сканируется, и каталоги, перечисленные в skills, загружаются вместе с ним
• Собственные правила слияния: hooks, MCP servers и LSP servers. Смотрите каждый раздел для того, как несколько источников объединяются

Для всех полей пути:

• Все пути должны быть относительны к корню плагина и начинаться с ./
• Компоненты из пользовательских путей используют те же правила именования и пространства имён
• Несколько путей можно указать как массивы
• Когда путь skill указывает на каталог, который содержит SKILL.md напрямую, например "skills": ["./"], указывающий на корень плагина, поле frontmatter name в SKILL.md определяет имя вызова skill. Это обеспечивает стабильное имя независимо от каталога установки. Если name не установлен в frontmatter, в качестве резервного варианта используется имя каталога.

Примеры путей:

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

Переменные окружения

Claude Code предоставляет две переменные для ссылки на пути плагина. Обе подставляются встроенно везде, где они появляются в содержимом skills, содержимом agents, командах hooks, командах monitors и конфигурациях серверов MCP или LSP. Обе также экспортируются как переменные окружения в процессы hooks и подпроцессы серверов MCP или LSP.

${CLAUDE_PLUGIN_ROOT}: абсолютный путь к каталогу установки вашего плагина. Используйте это для ссылки на скрипты, двоичные файлы и файлы конфигурации, поставляемые с плагином. Этот путь изменяется при обновлении плагина. Каталог предыдущей версии остаётся на диске примерно семь дней после обновления перед очисткой, но рассматривайте его как временный и не записывайте состояние здесь.

Когда плагин обновляется во время сеанса, команды hooks, monitors, серверы MCP и серверы LSP продолжают использовать путь предыдущей версии. Запустите /reload-plugins для переключения hooks, серверов MCP и серверов LSP на новый путь; monitors требуют перезагрузки сеанса.

${CLAUDE_PLUGIN_DATA}: постоянный каталог для состояния плагина, который сохраняется при обновлениях. Используйте это для установленных зависимостей, таких как node_modules или виртуальные окружения Python, сгенерированный код, кэши и любые другие файлы, которые должны сохраняться между версиями плагина. Каталог создаётся автоматически при первом обращении к этой переменной.

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

Каталог постоянных данных

Каталог ${CLAUDE_PLUGIN_DATA} разрешается в ~/.claude/plugins/data/{id}/, где {id} — это идентификатор плагина с символами вне a-z, A-Z, 0-9, _ и -, заменённые на -. Для плагина, установленного как formatter@my-marketplace, каталог — это ~/.claude/plugins/data/formatter-my-marketplace/.

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

Этот hook SessionStart устанавливает node_modules при первом запуске и снова всякий раз, когда обновление плагина включает изменённый package.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

diff выходит с ненулевым кодом, когда сохранённая копия отсутствует или отличается от поставляемой, охватывая как первый запуск, так и обновления, изменяющие зависимости. Если npm install не удаётся, завершающий rm удаляет скопированный манифест, чтобы следующий сеанс повторил попытку.

Скрипты, поставляемые в ${CLAUDE_PLUGIN_ROOT}, затем могут работать с сохранённым node_modules:

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

Каталог данных удаляется автоматически при удалении плагина из последней области, где он установлен. Интерфейс /plugin показывает размер каталога и запрашивает перед удалением. CLI удаляет по умолчанию; передайте --keep-data для сохранения.

Кэширование плагина и разрешение файлов

Плагины указываются одним из двух способов:

• Через claude --plugin-dir или claude --plugin-url, на время сеанса.
• Через маркетплейс, установленный для будущих сеансов.

В целях безопасности и проверки Claude Code копирует плагины маркетплейса в локальный кэш плагина пользователя (~/.claude/plugins/cache) вместо использования их на месте. Понимание этого поведения важно при разработке плагинов, которые ссылаются на внешние файлы.

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

Инструменты Glob и Grep Claude пропускают сиротские каталоги версий при поиске, поэтому результаты файлов не включают устаревший код плагина.

Ограничения обхода пути

Установленные плагины не могут ссылаться на файлы вне их каталога. Пути, которые выходят за пределы корня плагина (такие как ../shared-utils), не будут работать после установки, потому что эти внешние файлы не копируются в кэш.

Работа с внешними зависимостями

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

ln -s /path/to/shared-utils ./shared-utils

Это обеспечивает гибкость при сохранении преимуществ безопасности системы кэширования.

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

Стандартная раскладка плагина

Полный плагин следует этой структуре:

enterprise-plugin/
├── .claude-plugin/           # Каталог метаданных (опционально)
│   └── plugin.json             # манифест плагина
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills как плоские файлы .md
│   ├── status.md
│   └── logs.md
├── agents/                   # Определения subagent
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/            # Определения стиля вывода
│   └── terse.md
├── themes/                   # Определения цветовой темы
│   └── dracula.json
├── monitors/                 # Конфигурации фонового monitor
│   └── monitors.json
├── hooks/                    # Конфигурации hook
│   ├── hooks.json           # Основная конфигурация hook
│   └── security-hooks.json  # Дополнительные hooks
├── bin/                      # Исполняемые файлы плагина, добавленные в PATH
│   └── my-tool               # Вызываемый как голая команда в инструменте Bash
├── settings.json            # Параметры по умолчанию для плагина
├── .mcp.json                # Определения сервера MCP
├── .lsp.json                # Конфигурации сервера LSP
├── scripts/                 # Скрипты hook и утилиты
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Файл лицензии
└── CHANGELOG.md             # История версий

Файл CLAUDE.md в корне плагина не загружается как контекст проекта. Плагины предоставляют контекст через skills, agents и hooks, а не через CLAUDE.md. Чтобы отправить инструкции, которые загружаются в контекст Claude, поместите их в skill.

Справочник местоположений файлов

Справочник команд CLI

Claude Code предоставляет команды CLI для неинтерактивного управления плагинами, полезные для написания скриптов и автоматизации.

plugin install

Установите плагин из доступных маркетплейсов.

claude plugin install <plugin> [options]

Аргументы:

• <plugin>: Имя плагина или plugin-name@marketplace-name для конкретного маркетплейса

Опции:

Область определяет, в какой файл параметров добавляется установленный плагин. Например, --scope project записывает в enabledPlugins в .claude/settings.json, делая плагин доступным для всех, кто клонирует репозиторий проекта.

Примеры:

# Установить в область пользователя (по умолчанию)
claude plugin install formatter@my-marketplace

# Установить в область проекта (общее с командой)
claude plugin install formatter@my-marketplace --scope project

# Установить в локальную область (игнорируется git)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

Удалите установленный плагин.

claude plugin uninstall <plugin> [options]

Аргументы:

• <plugin>: Имя плагина или plugin-name@marketplace-name

Опции:

Псевдонимы: remove, rm

По умолчанию удаление из последней оставшейся области также удаляет каталог ${CLAUDE_PLUGIN_DATA} плагина. Используйте --keep-data для сохранения, например при переустановке после тестирования новой версии.

plugin prune

Удалите автоматически установленные зависимости плагинов, которые больше не требуются ни одному установленному плагину. Зависимости, которые Claude Code подтянул для удовлетворения поля dependencies другого плагина, удаляются; плагины, которые вы установили напрямую, никогда не затрагиваются.

claude plugin prune [options]

Опции:

Псевдонимы: autoremove

Команда выводит список потерянных зависимостей и запрашивает подтверждение перед их удалением. Чтобы удалить плагин и очистить его зависимости в один шаг, запустите claude plugin uninstall <plugin> --prune.

plugin enable

Включите отключённый плагин.

claude plugin enable <plugin> [options]

Аргументы:

• <plugin>: Имя плагина или plugin-name@marketplace-name

Опции:

plugin disable

Отключите плагин без его удаления.

claude plugin disable <plugin> [options]

Аргументы:

• <plugin>: Имя плагина или plugin-name@marketplace-name

Опции:

plugin update

Обновите плагин до последней версии.

claude plugin update <plugin> [options]

Аргументы:

• <plugin>: Имя плагина или plugin-name@marketplace-name

Опции:

plugin list

Список установленных плагинов с их версией, источником маркетплейса и статусом включения.

claude plugin list [options]

Опции:

plugin tag

Создайте тег выпуска git для плагина в текущем каталоге. Запустите из папки плагина. См. Теги выпусков плагинов.

claude plugin tag [options]

Опции:

Инструменты отладки и разработки

Команды отладки

Используйте claude --debug для просмотра деталей загрузки плагина:

Это показывает:

• Какие плагины загружаются
• Любые ошибки в манифестах плагинов
• Регистрацию skill, agent и hook
• Инициализацию сервера MCP

Распространённые проблемы

Примеры сообщений об ошибках

Ошибки проверки манифеста:

• Invalid JSON syntax: Unexpected token } in JSON at position 142: проверьте наличие пропущенных запятых, лишних запятых или неквотированных строк
• Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required: отсутствует обязательное поле
• Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: ошибка синтаксиса JSON

Ошибки загрузки плагина:

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: путь команды существует, но не содержит действительных файлов команд
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: путь source в marketplace.json указывает на несуществующий каталог
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: удалите дублирующиеся определения компонентов или удалите strict: false в записи маркетплейса

Устранение неполадок Hook

Скрипт hook не выполняется:

1. Проверьте, что скрипт исполняемый: chmod +x ./scripts/your-script.sh
2. Проверьте строку shebang: Первая строка должна быть #!/bin/bash или #!/usr/bin/env bash
3. Проверьте, что путь использует ${CLAUDE_PLUGIN_ROOT}: "command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"
4. Протестируйте скрипт вручную: ./scripts/your-script.sh

Hook не срабатывает на ожидаемых событиях:

1. Проверьте, что имя события правильное (чувствительно к регистру): PostToolUse, а не postToolUse
2. Проверьте, что шаблон сопоставления соответствует вашим инструментам: "matcher": "Write|Edit" для операций с файлами
3. Подтвердите, что тип hook действителен: command, http, mcp_tool, prompt или agent

Устранение неполадок сервера MCP

Сервер не запускается:

1. Проверьте, что команда существует и исполняемая
2. Проверьте, что все пути используют переменную ${CLAUDE_PLUGIN_ROOT}
3. Проверьте журналы сервера MCP: claude --debug показывает ошибки инициализации
4. Протестируйте сервер вручную вне Claude Code

Инструменты сервера не отображаются:

1. Убедитесь, что сервер правильно настроен в .mcp.json или plugin.json
2. Проверьте, что сервер правильно реализует протокол MCP
3. Проверьте наличие тайм-аутов соединения в выводе отладки

Ошибки структуры каталога

Симптомы: Плагин загружается, но компоненты (skills, agents, hooks) отсутствуют.

Правильная структура: Компоненты должны быть в корне плагина, а не внутри .claude-plugin/. Только plugin.json должен быть в .claude-plugin/.

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← Только манифест здесь
├── commands/            ← На уровне корня
├── agents/              ← На уровне корня
└── hooks/               ← На уровне корня

Если ваши компоненты находятся внутри .claude-plugin/, переместите их в корень плагина.

Контрольный список отладки:

1. Запустите claude --debug и ищите сообщения "loading plugin"
2. Проверьте, что каждый каталог компонента указан в выводе отладки
3. Проверьте, что разрешения файлов позволяют читать файлы плагина

Справочник по распространению и версионированию

Управление версиями

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

Версия определяется из первого из следующих параметров, который установлен:

1. Поле version в plugin.json плагина
2. Поле version в записи плагина на маркетплейсе в marketplace.json
3. SHA коммита git источника плагина для источников github, url, git-subdir и relative-path в маркетплейсе, размещённом на git
4. unknown для источников npm или локальных каталогов, не находящихся в репозитории git

Это дает вам два способа версионирования плагина:

Если вы используете явные версии, следуйте семантическому версионированию (MAJOR.MINOR.PATCH): обновляйте MAJOR для критических изменений, MINOR для новых функций, PATCH для исправлений ошибок. Документируйте изменения в CHANGELOG.md.

Смотрите также

• Плагины - Учебные материалы и практическое использование
• Маркетплейсы плагинов - Создание и управление маркетплейсами
• Skills - Детали разработки skills
• Subagents - Конфигурация и возможности агентов
• Hooks - Обработка событий и автоматизация
• MCP - Интеграция внешних инструментов
• Параметры - Опции конфигурации для плагинов