SpyBara
Go Premium

plugins-reference.md 2026-09-11 23:01 UTC to 2026-09-12 03:02 UTC

This page contains 136 additions and 68 deletions.

2026
Thu 10 23:00 Sat 12 03:02 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

Справочник по plugins

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

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

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

Skills

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

Расположение: директория skills/ или commands/ в корне плагина, или один файл SKILL.md в корне плагина

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

Структура skill:

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

Skills и commands автоматически обнаруживаются при установке плагина.

Если плагин не имеет директории skills/ и не имеет поля манифеста skills, то SKILL.md в корне плагина загружается как один skill. Установите поле frontmatter name для управления именем вызова skill. Без него Claude Code возвращается к имени директории установки, которое для плагинов, установленных из marketplace, является строкой версии, которая меняется при каждом обновлении. Для плагинов, которые поставляют более одного skill, используйте макет директории skills/, показанный выше.

В skills и commands плагинов логические поля frontmatter, такие как disable-model-invocation, принимают yes, no, on, off, 1 и 0 в любом регистре букв, в дополнение к true и false. До версии v2.1.218 Claude Code распознавал только true и false.

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

Agents

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

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

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

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

---
name: agent-name
description: What this agent specializes in and when Claude should invoke it
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Detailed system prompt for the agent describing its role, expertise, and behavior.

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

Claude Code загружает агента плагина даже когда его frontmatter не имеет name или не анализируется:

  • Нет name: Claude Code называет агента по имени файла, поэтому agents/reviewer.md в плагине с именем my-plugin загружается как my-plugin:reviewer
  • Frontmatter, который не анализируется: Claude Code называет агента по имени файла, использует Agent from my-plugin plugin в качестве его описания и игнорирует каждое поле в файле

В отличие от этого, Claude Code пропускает файл проекта, пользователя или управляемого агента, frontmatter которого не имеет name или не анализируется.

Чтобы найти файлы в директории agents/ плагина по умолчанию, frontmatter которых не анализируется, запустите claude plugin validate. Путь, который вы передаёте, зависит от того, имеет ли плагин манифест, и оба примера используют ./my-plugin в качестве директории плагина:

  • Плагин с манифестом: claude plugin validate ./my-plugin
  • Плагин без манифеста: claude plugin validate ./my-plugin/agents. Требует Claude Code v2.1.233 или позже.

Агенты появляются в @-mention typeahead под их scoped именем, таким как my-plugin:code-reviewer, после включения плагина.

Для полной информации см. 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:

Событие Когда оно срабатывает
SessionStart Когда сеанс начинается или возобновляется
Setup Когда вы запускаете Claude Code с --init-only, или с --init или --maintenance в режиме -p. Для одноразовой подготовки в CI или скриптах
UserPromptSubmit Когда вы отправляете запрос, прежде чем Claude его обработает
UserPromptExpansion Когда команда, введённая пользователем, расширяется в запрос, прежде чем она достигнет Claude. Может заблокировать расширение
PreToolUse Перед выполнением вызова инструмента. Может заблокировать его
PermissionRequest Когда вызов инструмента требует решения о разрешении
PermissionDenied Когда автоматический режим отклоняет вызов инструмента, включая отклонения без вердикта классификатора. Используйте JSON hookSpecificOutput.retry: true, чтобы сообщить модели, что она может повторить попытку отклонённого вызова инструмента. Claude Code игнорирует retry, когда классификатор не выдал вердикт
PostToolUse После успешного выполнения вызова инструмента
PostToolUseFailure После неудачного выполнения вызова инструмента
PostToolBatch После разрешения полного пакета параллельных вызовов инструментов, перед следующим вызовом модели
Notification Когда Claude Code отправляет уведомление
MessageDisplay Во время отображения текста сообщения помощника
SubagentStart Когда порождается подагент
SubagentStop Когда подагент завершает работу
TaskCreated Когда задача создаётся через TaskCreate
TaskCompleted Когда задача отмечается как завершённая
Stop Когда Claude завершает ответ
StopFailure Когда ход завершается из-за ошибки API
TeammateIdle Когда товарищ по команде команды агентов собирается перейти в режим ожидания
InstructionsLoaded Когда файл CLAUDE.md или .claude/rules/*.md загружается в контекст. Срабатывает при запуске сеанса и когда файлы ленивой загрузки загружаются во время сеанса
ConfigChange Когда файл конфигурации изменяется во время сеанса
CwdChanged Когда рабочий каталог изменяется, например когда Claude выполняет команду cd. Полезно для реактивного управления окружением с помощью инструментов, таких как direnv
DirectoryAdded Когда рабочий каталог добавляется в середине сеанса через /add-dir или запрос управления SDK register_repo_root
FileChanged Когда наблюдаемый файл изменяется на диске. Поле matcher указывает, какие имена файлов отслеживать
WorktreeCreate Когда worktree создаётся через --worktree, isolation: "worktree", или для фонового сеанса. Заменяет поведение git по умолчанию
WorktreeRemove Когда worktree удаляется при выходе из сеанса, когда подагент завершает работу, или когда вы удаляете фоновый сеанс
PreCompact Перед компактизацией контекста
PostCompact После завершения компактизации контекста
PreModelSwitch Перед тем как Claude Code применяет переключение модели, которое вы или клиент запросили. Может заблокировать переключение
PostModelSwitch После изменения модели сеанса, включая изменения, которые Claude Code делает самостоятельно, такие как восстановление модели при возобновлении сеанса
Elicitation Когда сервер MCP запрашивает ввод пользователя во время вызова инструмента
ElicitationResult После того как пользователь отвечает на запрос MCP, перед отправкой ответа обратно на сервер
SessionEnd Когда сеанс завершается

Типы hooks:

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

Hooks, которые нацелены на собственный bundled MCP сервер плагина, должны использовать его scoped имена. Матчеры инструментов и поля if принимают scoped имя инструмента mcp__plugin_<plugin-name>_<server-name>__<tool>, и поле server hook mcp_tool принимает plugin:<plugin-name>:<server-name>. Матчер, написанный для простого ключа сервера, никогда не срабатывает. См. Match MCP tools и Plugin-provided MCP servers.

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"]
    }
  }
}

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

  • Серверы MCP плагинов запускаются автоматически при включении плагина
  • Серверы появляются как стандартные MCP инструменты в наборе инструментов Claude
  • Серверы плагинов могут быть настроены независимо от пользовательских MCP серверов
  • Если вы запустите /reload-plugins в середине сеанса, Claude Code сохраняет живые соединения серверов, конфигурация которых не изменилась

LSP servers

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

Расположение: .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"
      }
    }
  }
}

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

Поле Описание
command Бинарный файл LSP для выполнения (должен быть в PATH)
extensionToLanguage Отображает расширения файлов на идентификаторы языков

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

Поле Описание
args Аргументы командной строки для LSP сервера
transport Транспорт коммуникации: stdio (по умолчанию) или socket. Claude Code принимает socket, но запускает каждый сервер через stdio, поэтому правила протокола stdout применяются ко всем серверам
env Переменные окружения для установки при запуске сервера
initializationOptions Опции, передаваемые серверу при инициализации
settings Параметры, передаваемые через workspace/didChangeConfiguration
workspaceFolder Путь папки рабочего пространства для сервера
startupTimeout Максимальное время ожидания запуска сервера (миллисекунды)
shutdownTimeout Максимальное время ожидания корректного завершения (миллисекунды). Когда истекает время ожидания, Claude Code завершает процесс сервера. Если не установлено, время ожидания не применяется
restartOnCrash Следует ли перезапустить сервер после его сбоя. По умолчанию true. Установите false, чтобы оставить упавший сервер остановленным вместо его перезапуска
maxRestarts Максимальное количество попыток перезапуска перед отказом
diagnostics Следует ли отправлять диагностику в контекст Claude после редактирования (по умолчанию true). Установите false, чтобы сохранить навигацию по коду, но подавить автоматическое внедрение диагностики

restartOnCrash и shutdownTimeout требуют Claude Code v2.1.205 или позже. До версии v2.1.205 схема конфигурации принимала обе опции, но установка любой из них вызывала пропуск этого LSP сервера Claude Code при запуске, с причиной видимой только в выводе claude --debug.

Несколько серверов для одного расширения: когда более одного включённого LSP сервера объявляет одно и то же расширение файла в extensionToLanguage, независимо от того, поступают ли серверы из одного плагина или из разных плагинов, первый зарегистрированный сервер обрабатывает файлы с этим расширением, а остальные никогда не запускаются. Интерфейс /plugin показывает предупреждение, называющее плагин, чей сервер активен.

Серверы, которые не инициализируются: Claude Code пропускает сервер, конфигурация которого недействительна, например отсутствует command или extensionToLanguage, и остальные настроенные серверы всё ещё запускаются. Запустите claude --debug, чтобы увидеть, почему сервер был пропущен.

Пропущенный сервер не заявляет свои расширения файлов, поэтому другой действительный сервер, который объявляет то же расширение, из того же или другого плагина, всё ещё обрабатывает эти файлы.

Отправляйте вывод логов в stderr, а не stdout: Claude Code читает stdout сервера только как сообщения протокола и принимает заголовки сообщений до 64 КиБ и тело сообщения до 32 МиБ. Claude Code отключает сервер, который превышает любой лимит или записывает вывод, не являющийся протоколом, в stdout, и считает отключение сбоем для restartOnCrash и maxRestarts. Когда вы запускаете с --debug, Claude Code записывает ошибку, называющую причину, в журнал отладки.

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

Плагин Языковой сервер Команда установки
pyright-lsp Pyright (Python) pip install pyright или npm install -g pyright
typescript-lsp TypeScript Language Server npm install -g typescript-language-server typescript
rust-analyzer-lsp rust-analyzer See rust-analyzer installation

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

Monitors

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

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

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

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

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

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

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

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

Поле Описание
name Идентификатор, уникальный в пределах плагина. Предотвращает дублирование процессов при перезагрузке плагина или повторном вызове skill
command Shell команда, запускаемая как постоянный фоновый процесс в рабочей директории сеанса
description Краткое резюме того, что отслеживается. Показывается в панели задач и в сводках уведомлений

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

Поле Описание
when Управляет тем, когда запускается монитор. "always" запускает его при запуске сеанса и при перезагрузке плагина и является значением по умолчанию. "on-skill-invoke:<skill-name>" запускает его в первый раз, когда именованный skill в этом плагине отправляется

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

Команда монитора command не может ссылаться на значения ${user_config.*}. Команда запускается через shell, поэтому Claude Code отклоняет монитор с error вместо подстановки значения. Процессы мониторов не получают переменные окружения CLAUDE_PLUGIN_OPTION_<KEY>, поэтому скрипт монитора должен читать значение из файла конфигурации, который он владеет.

Если вы отключите плагин в середине сеанса, Claude Code не останавливает мониторы, которые уже запущены; они останавливаются при завершении сеанса.

Themes

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

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

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

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

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

Область Файл параметров Вариант использования
user ~/.claude/settings.json Личные плагины, доступные во всех проектах (по умолчанию)
project .claude/settings.json Командные плагины, общие через систему контроля версий
local .claude/settings.local.json Плагины, специфичные для проекта, игнорируются в .gitignore, когда Claude Code сохраняет параметр в него
managed Managed settings Управляемые плагины (только для чтения, только обновление)

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

Плагины каталога skills

Любая папка в каталоге skills, содержащая манифест .claude-plugin/plugin.json, загружается как плагин с именем <name>@skills-dir в следующем сеансе без marketplace и без этапа установки. Создайте его с помощью plugin init. В отличие от скопированной установки из marketplace, плагин обнаруживается на месте, а не копируется в кэш плагинов.

Дерево каталога skills поддерживает три различных вещи:

Что у вас есть Что это такое
<skills-dir>/foo/SKILL.md без манифеста Обычный skill с именем foo
<skills-dir>/foo/.claude-plugin/plugin.json Плагин foo@skills-dir, который может содержать свои собственные skills, agents, hooks и многое другое
<plugin>/skills/bar/SKILL.md Skill bar, упакованный внутри плагина

Выберите, откуда загружается плагин

Каталог skills Область Загружает
~/.claude/skills/ личный В каждом проекте, так как это расположение только ваше
<cwd>/.claude/skills/ проект Только после того, как вы примете диалог доверия рабочей области для этой папки

Плагин с областью проекта проверяется в репозитории и доступен каждому сотруднику, который его клонирует. Поскольку это содержимое поступает из репозитория, а не от вас, оно загружается только после того же шлюза доверия, который управляет правилами разрешения проекта в .claude/settings.json, поэтому доверие к родительской папке или запуск с -p недостаточно, и компоненты, которые выполняют код, имеют дополнительные ограничения:

Плагины с личной областью не имеют никаких из этих ограничений.

Редактируйте, перезагружайте и отключайте плагин каталога skills

Изменения, которые вы вносите в SKILL.md skill, вступают в силу немедленно в текущем сеансе. Изменения в других компонентах плагина, таких как hooks/, .mcp.json, agents/ и output-styles/, не вступают. Запустите /reload-plugins или перезагрузите Claude Code, чтобы их подхватить. См. Обнаружение живых изменений.

Чтобы остановить загрузку плагина каталога skills, удалите его папку или отключите его по имени. Нет этапа uninstall, потому что ничего не было установлено из marketplace.

claude plugin disable my-tool@skills-dir

Плагины, синхронизированные с claude.ai

В Cowork и облачных сеансах Claude Code загружает плагины, включённые для вашей учётной записи claude.ai, в ~/.claude/plugins/synced/ в собственной среде сеанса и загружает каждый как <name>@synced, без marketplace и без записи об установке. Claude Code не загружает их в сеансах, которые вы запускаете в собственном терминале. Внутри этой среды Cowork или облачной среды claude plugin list показывает загруженные копии под заголовком Synced from claude.ai. До версии 2.1.239 Claude Code загружал эти плагины как <name>@inline, идентификатор, который используют плагины --plugin-dir.

Управляйте синхронизированным плагином по ID <name>@synced, который выводит claude plugin list:

  • Отключить один: в синхронизированном сеансе запустите claude plugin disable <name>@synced или попросите Claude запустить это. Claude Code сохраняет выбор как "<name>@synced": false в enabledPlugins этой среды на уровне пользователя. Чтобы включить плагин обратно, запустите claude plugin enable <name>@synced в том же сеансе. Чтобы исключить плагин из всех синхронизированных сеансов, отключите его для вашей учётной записи claude.ai. Чтобы исключить его из синхронизированных сеансов одного проекта в каждой среде, установите "<name>@synced": false под enabledPlugins в файле .claude/settings.json этого проекта.
  • Управляйте самим плагином на claude.ai: claude plugin install, update и uninstall не применяются к синхронизированному плагину. Чтобы удалить его, отключите плагин для вашей учётной записи claude.ai; следующий синхронизированный сеанс начнётся без него.

Когда включённый плагин из любого другого источника, такой как установка из marketplace, плагин каталога навыков или плагин --plugin-dir, совпадает по имени с синхронизированным плагином, Claude Code загружает этот плагин и сообщает, что синхронизированная копия не загружена. Чтобы использовать копию с claude.ai, отключите свою копию. До версии 2.1.239 Claude Code загружал синхронизированную копию вместо установки из marketplace с тем же именем.

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

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

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

Полная схема 

{
  "name": "plugin-name",
  "displayName": "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"],
  "metadata": { "catalogId": "cat-123", "tier": "pro" },
  "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",
    "evals": "quality/evals"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

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

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

Поле Тип Описание Пример
name string Уникальный идентификатор в kebab-case без пробелов, управляющих символов или символов двунаправленного форматирования. Когда запись на маркетплейсе указывает плагин под другим именем, имя записи маркетплейса — это то, что используют ключи enabledPlugins и /plugin "deployment-tools"

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

Нераспознанные поля

Claude Code игнорирует поля верхнего уровня, которые он не распознаёт. Вы можете сохранить метаданные из другой экосистемы в plugin.json, и плагин всё равно загрузится. Это позволяет практично поддерживать один манифест, который одновременно служит манифестом расширения VS Code или Cursor, package.json npm или манифестом пакета MCPB/DXT.

claude plugin validate сообщает о нераспознанных полях как о предупреждениях, а не об ошибках. Если поле отличается на один или два символа от распознанного, предупреждение предлагает вероятное предполагаемое имя. Плагин только с предупреждениями о нераспознанных полях всё равно проходит валидацию и загружается во время выполнения.

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

  • Большинство полей: плагин не загружается. Например, значение keywords, которое является строкой вместо массива, является ошибкой загрузки, и claude plugin validate сообщает об этом.
  • experimental и metadata: Claude Code игнорирует значение, которое не является объектом, и claude plugin validate сообщает предупреждение.

Передайте --strict, чтобы рассматривать предупреждения как ошибки. Используйте это в CI, чтобы перехватить опечатку в имени поля или поле, оставшееся от манифеста другого инструмента перед публикацией, даже если плагин загружался бы во время выполнения.

claude plugin validate ./my-plugin --strict

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

Поле Тип Описание Пример
$schema string URL JSON Schema для автодополнения и валидации редактора. Claude Code игнорирует это поле во время загрузки. "https://json.schemastore.org/claude-code-plugin-manifest.json"
displayName string Читаемое имя, отображаемое в средстве выбора /plugin и других поверхностях пользовательского интерфейса. Для плагина, установленного с маркетплейса, displayName в записи маркетплейса имеет приоритет над этим значением. Когда имя отображения не установлено ни в одном месте, пользователи видят name. В отличие от name, может содержать пробелы и любой регистр. Не используется для пространства имён или поиска. "Deployment Tools"
version string Необязательно. Семантическая версия. Установка этого параметра закрепляет плагин на этой строке версии, поэтому пользователи получают обновления только при её изменении, за исключением источника command; см. Управление версиями. Если также установлено в записи маркетплейса, plugin.json имеет приоритет. Если опущено, версия берётся из следующего источника в Управлении версиями. "2.1.0"
description string Краткое объяснение назначения плагина "Deployment automation tools"
author object Информация об авторе {"name": "Dev Team", "email": "dev@company.com"}
homepage string URL документации "https://docs.example.com"
repository string URL исходного кода "https://github.com/user/plugin"
license string Идентификатор лицензии "MIT", "Apache-2.0"
keywords array Теги обнаружения ["deployment", "ci-cd"]
metadata object Объект произвольной формы для ваших собственных данных, таких как поля прав доступа или каталога. Claude Code не читает его, поэтому значения никогда не влияют на поведение плагина. Claude Code игнорирует значение, которое не является объектом, и claude plugin validate сообщает об этом как о предупреждении. До версии 2.1.222 Claude Code рассматривал ключ как нераспознанное поле. {"catalogId": "cat-123"}
defaultEnabled boolean Включен ли плагин в состояние по умолчанию, когда пользователь не установил его. По умолчанию true. См. Включение по умолчанию. false

Включение по умолчанию

Установите defaultEnabled: false в plugin.json, чтобы доставить плагин, который устанавливается отключённым. Пользователь включает его с помощью claude plugin enable <plugin> или интерфейса /plugin. Используйте это для плагинов, которые добавляют стоимость или область, в которую пользователь должен явно согласиться, например для плагина, который подключается к внешнему сервису.

defaultEnabled — это резервный вариант, когда ничто другое не определило состояние плагина. Два фактора имеют приоритет над ним:

  • Параметр пользователя: запись для плагина в enabledPlugins в любой области параметров. После записи она сохраняется при обновлениях и переустановках плагина, поэтому изменение defaultEnabled в более позднем выпуске не переключает существующего пользователя.
  • Требование зависимости: когда плагин требуется другим активным плагином, Claude Code записывает true для него во время установки или включения. Это даёт ему явный параметр, поэтому его собственное значение по умолчанию больше не применяется. См. Включение или отключение плагина с зависимостями.

То же поле может появиться в записи маркетплейса плагина, где оно имеет приоритет над значением в plugin.json. См. Необязательные поля плагина.

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

Поле Тип Описание Пример
skills string|array Пользовательские каталоги skills, содержащие <name>/SKILL.md. Добавляет к сканированию по умолчанию skills/. См. Правила поведения пути для исключения корня маркетплейса "./custom/skills/"
commands string|array Пользовательские плоские файлы .md skills или каталоги (заменяет значение по умолчанию commands/) "./custom/cmd.md" или ["./cmd1.md"]
agents string|array Пользовательские файлы агентов (заменяет значение по умолчанию agents/) "./custom/agents/reviewer.md"
workflows string|array Пользовательские файлы workflow скриптов или каталоги (заменяет значение по умолчанию workflows/) "./custom/workflows/"
hooks string|array|object Пути конфигурации hooks или встроенная конфигурация "./my-extra-hooks.json"
mcpServers string|array|object Пути конфигурации MCP или встроенная конфигурация "./my-extra-mcp-config.json"
outputStyles string|array Пользовательские файлы стилей вывода/каталоги (заменяет значение по умолчанию output-styles/) "./styles/"
lspServers string|array|object Конфигурации Language Server Protocol для интеллекта кода (перейти к определению, найти ссылки и т. д.) "./.lsp.json"
experimental.themes string|array Файлы цветовых тем/каталоги (заменяет значение по умолчанию themes/). См. Темы "./themes/"
experimental.monitors string|array Конфигурации фонового Monitor, которые запускаются автоматически при активном плагине. См. Мониторы "./monitors.json"
experimental.evals string|array Каталог ниже корня плагина, который содержит тестовые случаи eval плагина, когда это не каталог по умолчанию evals/. claude plugin eval --eval-dir переопределяет его "quality/evals"
userConfig object Значения, настраиваемые пользователем, запрашиваемые при включении. См. Конфигурация пользователя См. ниже
channels array Объявления каналов для внедрения сообщений (стиль Telegram, Slack, Discord). См. Каналы См. ниже
dependencies array Другие плагины, которые требует этот плагин, опционально с ограничениями версии semver. См. Ограничение версий зависимостей плагина [{ "name": "secrets-vault", "version": "~2.1.0" }]

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

Компоненты под ключом 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
    }
  }
}

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

Поле Обязательно Описание
type Да Одно из string, number, boolean, directory или file
title Да Метка, отображаемая в диалоговом окне конфигурации
description Да Справочный текст, отображаемый под полем
sensitive Нет Если true, скрывает ввод и сохраняет значение в защищённом хранилище вместо settings.json
required Нет Если true, валидация не пройдёт, когда поле пусто
default Нет Значение, используемое, когда пользователь ничего не предоставляет
multiple Нет Для типа string, разрешить массив строк
min / max Нет Границы для типа number

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

Поля, которые работают в оболочке, отклоняют ${user_config.*}: подстановка настроенного значения в команду оболочки позволила бы оболочке запустить всё, что содержит это значение, поэтому компонент не работает с ошибкой. Каждое отклонённое поле имеет альтернативный способ передачи значения:

Отклонённое поле Как передать значение
Команды hooks в форме оболочки Используйте форму exec с args или прочитайте CLAUDE_PLUGIN_OPTION_<KEY> из окружения hooks
Команды Monitor Прочитайте значение из файла конфигурации в скрипте
MCP headersHelper Прочитайте значение из файла конфигурации в скрипте

До версии 2.1.207 эти поля подставляли значения ${user_config.KEY}; обновите плагины, которые полагались на это.

Нечувствительные значения хранятся под ключом pluginConfigs в вашем пользовательском settings.json как pluginConfigs[<plugin-id>].options.

На macOS Claude Code хранит чувствительные значения в macOS Keychain, переходя на ~/.claude/.credentials.json, когда Keychain отклоняет запись. На платформах без поддерживаемого keychain он хранит их в ~/.claude/.credentials.json. Хранилище Keychain совместно используется с токенами OAuth и имеет приблизительный общий лимит в 2 КБ, поэтому держите чувствительные значения небольшими.

Claude Code читает все значения pluginConfigs только из трёх источников параметров:

  • Параметры пользователя: ~/.claude/settings.json, файл, в который записывает приглашение во время включения
  • --settings: флаг CLI или встроенные параметры SDK
  • Управляемые параметры: контролируемая организацией политика

Когда более одного источника устанавливает один и тот же ключ, управляемые параметры имеют приоритет, затем --settings, затем параметры пользователя. Единственный источник, который вы можете удалить из этого списка, — это параметры пользователя: передайте --setting-sources без user, и Claude Code пропустит их. Управляемые параметры и --settings остаются тем, что вы передали. Опция settingSources SDK устанавливает тот же список.

Записи в .claude/settings.json или .claude/settings.local.json проекта игнорируются. Оба файла находятся в рабочей области, поэтому клонированный репозиторий может предоставить значения там, и эти значения будут поступать в команды hooks плагина, конфигурации MCP серверов, команды LSP и команды мониторов. До версии 2.1.207 эти записи читались. Ограничение специфично для pluginConfigs: enabledPlugins по-прежнему учитывает параметры проекта и локальные параметры.

Каналы

Поле 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 для каждого канала использует ту же схему, что и поле верхнего уровня, позволяя плагину запрашивать токены ботов или идентификаторы владельцев при включении плагина.

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

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

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

Когда плагин имеет как папку по умолчанию, так и соответствующий ключ манифеста, Claude Code предупреждает об игнорируемой папке в claude plugin list и в представлении деталей /plugin. Плагин всё равно загружается с использованием путей манифеста. Claude Code не предупреждает, когда ключ манифеста указывает на папку по умолчанию, например "commands": ["./commands/deploy.md"], потому что этот путь явно называет папку.

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

  • Все пути должны быть относительны к корню плагина и начинаться с ./, за исключением того, что поле skills также принимает "."
    • Оба "." и "./" обозначают сам корень плагина
    • До версии 2.1.221 "." не прошёл валидацию манифеста и плагин не загружался, поэтому используйте "./" для поддержки более ранних версий
  • Компоненты из пользовательских путей используют те же правила именования и пространства имён
  • Несколько путей можно указать как массивы
  • Путь skill может указывать на каталог, который содержит SKILL.md непосредственно, например "skills": ["."] для корня плагина
    • Claude Code берёт имя вызова skill из поля frontmatter name в SKILL.md, поэтому имя остаётся стабильным независимо от того, как называется каталог установки
    • Если name не установлено в frontmatter, Claude Code переходит на имя каталога по умолчанию

Плагин, который имеет SKILL.md в своём корне, не имеет подкаталога skills/ и не имеет поля манифеста skills, автоматически загружается как плагин с одним skill. Вам не нужно устанавливать "skills": ["./"] в plugin.json для этого макета.

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

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

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

Claude Code предоставляет три переменные для ссылки на пути:

Переменная Разрешается в Используйте для
${CLAUDE_PLUGIN_ROOT} Абсолютный путь к каталогу установки плагина Скрипты, двоичные файлы и файлы конфигурации, поставляемые с плагином
${CLAUDE_PLUGIN_DATA} Постоянный каталог, который сохраняется при обновлениях плагина, создаётся при первой ссылке Установленные зависимости, такие как node_modules или виртуальные окружения Python, сгенерированный код и кэши
${CLAUDE_PROJECT_DIR} Корень проекта Локальные скрипты и файлы конфигурации проекта

Все три экспортируются как переменные окружения в процессы hooks и в подпроцессы MCP и LSP серверов. Какие поля подставляют их встроенно, зависит от компонента плагина:

Компонент плагина Поля, где разрешаются заполнители
Содержимое skill и agent Везде, где появляется заполнитель
Команды hook и monitor Везде, где появляется заполнитель
MCP stdio серверы command, args, env
MCP http, sse, ws серверы url, headers, headersHelper
LSP серверы command, args, env, workspaceFolder

В командах hooks используйте форму exec с args, чтобы каждый путь передавался как один аргумент без кавычек. В hooks в форме оболочки и командах мониторов оберните переменные в двойные кавычки, как в "${CLAUDE_PROJECT_DIR}/scripts/server.sh". Этот hook в форме оболочки запускает скрипт, поставляемый с плагином:

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

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

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

Для плагина с источником command Claude Code может перезагрузить сам плагин.

MCP серверы также могут вызвать запрос roots/list для чтения рабочих каталогов сеанса во время выполнения. См. что возвращает roots/list и когда Claude Code уведомляет сервер об изменениях.

Постоянный каталог данных

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

Обычное использование — установка зависимостей языка один раз и их повторное использование в сеансах и обновлениях плагина. Используйте его для зависимостей Python, зависимостей, заблокированных с помощью Yarn или pnpm, и пакетов, чьи скрипты жизненного цикла должны работать. Для плагина, установленного с маркетплейса, вам может вообще не понадобиться: Claude Code автоматически устанавливает подходящие зависимости пакета Node.js при кэшировании плагина.

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

Этот 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 на время сеанса.
  • Через marketplace, установленные для будущих сеансов.

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

Для скопированных плагинов каждая установленная версия представляет собой отдельный каталог в кеше, сгруппированный по marketplace и плагину и названный по разрешённой версии, с собственной копией файлов плагина и зависимостей пакетов Node.js. Зависимость, разрешённая из тега релиза, получает имя каталога с суффиксом commit-SHA.

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

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

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

Зависимости пакетов Node.js

Когда Claude Code копирует плагин в кеш, он также устанавливает зависимости пакетов Node.js плагина там, чтобы hooks и MCP серверы плагина могли их загружать. Этот раздел охватывает пакеты npm и Bun, которые плагин объявляет в своём собственном package.json. Для плагинов, которые зависят от других плагинов, см. версии зависимостей плагинов.

Claude Code запускает установку внутри скопированного каталога версии каждый раз, когда создаёт его: при установке плагина, когда Claude Code обновляет плагин до новой версии, и при запуске сеанса, когда включённый плагин ещё не кеширован, например на новой машине. Установка запускается только когда корневой каталог плагина содержит как package.json, так и поддерживаемый файл блокировки:

Файл блокировки Команда
bun.lock или bun.lockb bun install --frozen-lockfile --ignore-scripts
npm-shrinkwrap.json или package-lock.json npm ci --ignore-scripts

Если плагин содержит более одного из этих файлов блокировки, Claude Code использует первое совпадение, проверяя по порядку: bun.lock, bun.lockb, npm-shrinkwrap.json, package-lock.json. Claude Code пропускает yarn.lock и pnpm-lock.yaml, потому что Yarn и pnpm поддерживают хуки конфигурации во время разрешения, которые обходят --ignore-scripts.

Поставляйте файл блокировки npm для максимального охвата. Claude Code запускает менеджер пакетов файла блокировки из PATH пользователя и не переходит на другой файл блокировки, если он отсутствует. Для плагина, распространяемого через источник npm, используйте npm-shrinkwrap.json; npm исключает package-lock.json из опубликованных пакетов.

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

  • Замороженное разрешение: Bun и npm устанавливают ровно то, что закреплено в файле блокировки, и выходят с ошибкой, а не переразрешают версии, когда package.json и файл блокировки не совпадают.
  • Без скриптов жизненного цикла: --ignore-scripts предотвращает запуск скриптов preinstall, install и postinstall, поэтому зависимости, которые собирают нативные модули в этих скриптах, загружаются, но не компилируются во время этой установки.
  • Тайм-аут 60 секунд: Claude Code останавливает установку, которая работает дольше, и рассматривает её как неудачную.

Получение самого плагина из источника npm запускает npm install с включёнными скриптами жизненного цикла, прежде чем запустится эта установка зависимостей.

Неудачная или пропущенная установка никогда не блокирует плагин. Когда установка не удаётся или Claude Code пропускает файл блокировки yarn или pnpm, он записывает причину как предупреждение в выходе отладки. Плагин с package.json и без файла блокировки пропускается без записи в журнал. Истёкшая по времени установка может оставить частичное дерево node_modules в кешированной копии.

Вы не можете отключить автоматическую установку; никакая настройка или переменная окружения её не отключает. В ограниченных сетях см. требования к сетевому доступу для хостов, которые нужно разрешить.

Для зависимостей, которые автоматическая установка не может предоставить, таких как пакеты, которым нужны скрипты жизненного цикла для сборки, зависимости Python или плагин, заблокированный Yarn или pnpm, установите их из hook в каталог постоянных данных.

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

Claude Code не позволяет плагину ссылаться на файлы вне его собственного каталога. Он отклоняет путь компонента, который разрешается вне корня плагина, независимо от того, объявлен ли путь в plugin.json или в записи marketplace. Это охватывает путь, который указывает вне плагина в том виде, в котором он написан, например ../shared-utils, и символическую ссылку, которая ведёт вне плагина, кроме ссылок в одном marketplace.

На macOS и Linux Claude Code также отклоняет путь компонента, который содержит обратную косую черту где-либо в нём, даже когда путь остаётся внутри плагина. Компоненты, объявленные с путями обратной косой черты, поэтому загружаются только на Windows. Пишите пути компонентов с прямыми косыми чертами, например ./commands/deploy.md.

Когда Claude Code отклоняет путь, он сообщает об ошибке path escapes plugin directory и загружает плагин без этого компонента.

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

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

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

Для плагинов, установленных с --plugin-dir, из локального пути или из command источника в режиме copy, сохраняются только символические ссылки, которые разрешаются в собственном каталоге плагина. Все остальные пропускаются.

Следующая команда создаёт ссылку из плагина marketplace на общий skill, определённый плагином-соседом. На Windows используйте mklink /D из командной строки с повышенными привилегиями или включите режим разработчика:

ln -s ../../shared-plugin/skills/foo ./skills/foo

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

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

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

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/                   # Определения подагентов
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── workflows/                # Скрипты рабочих процессов
│   └── release-audit.js
├── output-styles/            # Определения стилей вывода
│   └── terse.md
├── themes/                   # Определения цветовых тем
│   └── dracula.json
├── monitors/                 # Конфигурации фоновых мониторов
│   └── monitors.json
├── hooks/                    # Конфигурации hooks
│   ├── hooks.json           # Основная конфигурация hooks
│   └── security-hooks.json  # Дополнительные hooks
├── bin/                      # Исполняемые файлы плагина, добавленные в PATH
│   └── my-tool               # Вызывается как простая команда в инструменте Bash
├── settings.json            # Параметры по умолчанию для плагина
├── .mcp.json                # Определения MCP-сервера
├── .lsp.json                # Конфигурации LSP-сервера
├── scripts/                 # Скрипты hooks и утилиты
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Файл лицензии
└── CHANGELOG.md             # История версий

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

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

Компонент Расположение по умолчанию Назначение
Манифест .claude-plugin/plugin.json Метаданные и конфигурация плагина (опционально)
Skills skills/ Skills со структурой <name>/SKILL.md
Команды commands/ Skills как плоские файлы Markdown. Используйте skills/ для новых плагинов
Агенты agents/ Файлы Markdown подагентов
Рабочие процессы workflows/ Файлы скриптов Workflow
Стили вывода output-styles/ Определения стилей вывода
Темы themes/ Определения цветовых тем
Hooks hooks/hooks.json Конфигурация hooks
MCP-серверы .mcp.json Определения MCP-сервера
LSP-серверы .lsp.json Конфигурации языковых серверов
Мониторы monitors/monitors.json Конфигурации фоновых мониторов
Исполняемые файлы bin/ Исполняемые файлы, добавленные в PATH инструмента Bash и вызываемые как простые команды при включении плагина. Вы не можете включить этот каталог в плагин, который вы распространяете через параметры организации claude.ai
Параметры settings.json Конфигурация по умолчанию, применяемая при включении плагина. Поддерживаются только ключи agent и subagentStatusLine

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

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

plugin init

Создайте новый плагин в ~/.claude/skills/<name>/. На следующей сессии Claude Code он загружается автоматически как <name>@skills-dir и появляется в /plugin и claude plugin list без необходимости установки.

См. Skills-directory plugins для требований к области действия и доверию.

claude plugin init <name> [options]

Команда принимает эти аргументы:

  • <name>: Имя плагина. Становится пространством имён навыка и именем каталога в ~/.claude/skills/, поэтому не может содержать пробелы или разделители пути.

Команда принимает эти опции:

Опция Описание По умолчанию
--description <text> Описание в манифесте
--author <name> Имя автора git config user.name
--author-email <email> Email автора git config user.email
--with <components...> Также создайте папки компонентов. Допустимые значения: skills, agents, hooks, mcp, lsp, output-style, channel
-f, --force Перезаписать существующий .claude-plugin/ в целевом месте
-h, --help Показать справку по команде

claude plugin new является псевдонимом для этой команды.

Каждое значение --with добавляет стартовый файл для этого компонента, готовый к редактированию:

Компонент Что создаётся
skills Дополнительный навык с пространством имён <name>:example рядом с навыком по умолчанию
agents Определение подагента agents/
hooks hooks/hooks.json с примером обработчика события
mcp .mcp.json с примерами HTTP и stdio серверов
lsp Пример языкового сервера .lsp.json
output-style output-styles/<name>.md, который применяется автоматически, пока плагин включен
channel Основанный на MCP канал: stdio сервер (server.ts), его .mcp.json и package.json

Созданный плагин использует источник @skills-dir вместо маркетплейса. Администраторы могут заблокировать этот источник с помощью strictKnownMarketplaces или добавив {"source": "skills-dir"} в blockedMarketplaces в управляемых параметрах. При блокировке plugin init завершается с ошибкой перед записью.

Эти примеры показывают распространённые вызовы:

# Создать минимальный плагин
claude plugin init my-helper

# Создать с папками навыков и хуков
claude plugin init my-helper --with skills hooks

# Перезаписать существующий скаффолд
claude plugin init my-helper --force

plugin install

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

claude plugin install <plugin> [options]

Команда принимает эти аргументы:

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

Команда принимает эти опции:

Опция Описание По умолчанию
-s, --scope <scope> Область установки: user, project или local user
--config <key=value> Установить опцию userConfig, объявленную в манифесте плагина. Повторите флаг для установки нескольких опций
-y, --yes Принять команду, которую объявляет маркетплейс плагина, без подтверждения: команду, которая создаёт плагин с источником command, или headersHelper, который аутентифицирует загрузку архива. Принятие headersHelper требует Claude Code v2.1.238 или позже. Claude Code всё равно выводит команду первой. Требуется, когда stdin или stdout не является TTY. Не имеет эффекта внутри сессии Claude Code, поэтому запустите команду из вашего собственного терминала
--json Вывести результат как один объект JSON на последней строке stdout вместо удобочитаемого сообщения для использования в скриптах. См. Формат результата JSON. Требует Claude Code v2.1.268 или позже
-h, --help Показать справку по команде

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

С --json последняя строка stdout — это один объект JSON. Разбирайте только эту строку, потому что Claude Code выводит любую команду, которую объявляет маркетплейс, перед ней. Три поля всегда присутствуют:

  • command: подкоманда, которая была запущена, например install
  • outcome: ok или failed
  • message: удобочитаемое описание результата

Другие поля, такие как pluginId, scope и failureCode, появляются только когда они применимы. Опция --json на plugin uninstall, plugin update, plugin enable и plugin disable выводит тот же объект с собственными полями этой подкоманды. Ошибка использования, такая как недопустимый --scope, не выводит строку результата и выходит с кодом 1 с причиной на stderr.

Эти примеры показывают распространённые вызовы:

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

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

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

plugin uninstall

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

claude plugin uninstall <plugin> [options]

Команда принимает эти аргументы:

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

Команда принимает эти опции:

Опция Описание По умолчанию
-s, --scope <scope> Удалить из области: user, project или local user
--keep-data Сохранить каталог постоянных данных плагина
--prune Также удалить автоматически установленные зависимости, которые не требуются другим плагинам. См. plugin prune
-y, --yes Пропустить подтверждение --prune. Требуется, когда stdin или stdout не является TTY
--json Вывести результат как один объект JSON на последней строке stdout в том же формате, что и plugin install --json. Не может быть объединено с --prune. Требует Claude Code v2.1.268 или позже
-h, --help Показать справку по команде

claude plugin remove и claude plugin rm являются псевдонимами для этой команды.

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

plugin prune

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

claude plugin prune [options]

Команда принимает эти опции:

Опция Описание По умолчанию
-s, --scope <scope> Очистить в области: user, project или local user
--dry-run Список того, что будет удалено, без фактического удаления
-y, --yes Пропустить подтверждение. Требуется, когда stdin или stdout не является TTY
-h, --help Показать справку по команде

claude plugin autoremove является псевдонимом для этой команды.

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

plugin enable

Включите отключённый плагин. Когда целевой плагин установлен из маркетплейса и объявляет зависимости, Claude Code включает их транзитивно в той же области. Команда завершается с ошибкой при условиях, которые перечисляет Enable or disable a plugin with dependencies.

claude plugin enable <plugin> [options]

Команда принимает эти аргументы:

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

Команда принимает эти опции:

Опция Описание По умолчанию
-s, --scope <scope> Область для включения: user, project или local. Если опущено, Claude Code определяет область, где установлен плагин Автоопределение
--json Вывести результат как один объект JSON на последней строке stdout в том же формате, что и plugin install --json. Требует Claude Code v2.1.268 или позже
-h, --help Показать справку по команде

plugin disable

Отключите плагин без его удаления. Когда целевой плагин установлен из маркетплейса, команда завершается с ошибкой, если другой включённый плагин зависит от него. Сообщение об ошибке включает цепочку команд, которая сначала отключает каждый зависимый плагин.

claude plugin disable [plugin] [options]

Команда принимает эти аргументы:

  • [plugin]: Имя плагина или plugin-name@marketplace-name. Опционально при использовании --all

Команда принимает эти опции:

Опция Описание По умолчанию
-a, --all Отключить все включённые плагины. Не может быть объединено с --scope
-s, --scope <scope> Область для отключения: user, project или local. Если опущено, Claude Code определяет область, где установлен плагин Автоопределение
--json Вывести результат как один объект JSON на последней строке stdout в том же формате, что и plugin install --json. Требует Claude Code v2.1.268 или позже
-h, --help Показать справку по команде

plugin update

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

claude plugin update <plugin> [options]

Команда принимает эти аргументы:

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

Команда принимает эти опции:

Опция Описание По умолчанию
-s, --scope <scope> Область для обновления: user, project, local или managed user
-y, --yes Принять команду, которую объявляет маркетплейс плагина, без подтверждения: команду, которая создаёт плагин с источником command, или headersHelper, который аутентифицирует загрузку архива. Принятие headersHelper требует Claude Code v2.1.238 или позже. Claude Code всё равно выводит команду первой. Требуется, когда stdin или stdout не является TTY. Не имеет эффекта внутри сессии Claude Code, поэтому запустите команду из вашего собственного терминала
--json Вывести результат как один объект JSON на последней строке stdout в том же формате, что и plugin install --json. Требует Claude Code v2.1.268 или позже
-h, --help Показать справку по команде

plugin list

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

claude plugin list [options]

Команда принимает эти опции:

Опция Описание По умолчанию
--json Вывести как JSON. Строка плагина с проблемами загрузки или предупреждениями авторства содержит массивы строк errors или notes. На Claude Code v2.1.268 или позже параллельные массивы errorDetails и noteDetails дают каждой записи диагностический type и названия, на которые она ссылается, такие как плагин, маркетплейс, сервер или файл
--available Включить доступные плагины из маркетплейсов. Требует --json
-h, --help Показать справку по команде

В интерактивной сессии /plugin list выводит похожий список встроенным образом, но охватывает только плагины, установленные из маркетплейса:

  • Плагины, загруженные из каталогов навыков, появляются в интерфейсе /plugin и в claude plugin list, но не в выводе встроенного /plugin list.
  • На Claude Code v2.1.239 или позже плагины, синхронизированные из claude.ai, появляются в claude plugin list при запуске в окружении, где синхронизированная сессия их загрузила. Они не появляются в выводе встроенного /plugin list.
  • Плагины, загруженные для сессии с --plugin-dir или --plugin-url, появляются в интерфейсе /plugin и в claude plugin list только когда тот же флаг предшествует подкоманде, как в claude --plugin-dir <dir> plugin list. Только имя флага указывает их местоположение, поэтому простой claude plugin list не может их найти, в отличие от синхронизированных плагинов и плагинов из каталога навыков, чьи фиксированные каталоги сканирует Claude Code.

Интерактивная форма принимает --enabled или --disabled для отображения только плагинов в этом состоянии и ls как сокращение для list.

plugin details

Показать инвентарь компонентов плагина и прогнозируемую стоимость в токенах. Вывод выводит список всех компонентов, которые вносит плагин, сгруппированных как Skills, Agents, Hooks, MCP серверы и LSP серверы, вместе с оценкой того, сколько токенов он добавляет к каждой сессии. Группа Skills включает записи как skills/, так и commands/.

claude plugin details <name>

Команда принимает эти аргументы:

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

Команда принимает эти опции:

Опция Описание По умолчанию
-h, --help Показать справку по команде

Вывод показывает две цифры стоимости для каждого компонента:

  • Always-on: токены, добавляемые к каждой сессии текстом списка плагина, такие как описания навыков, описания агентов и имена команд, независимо от того, срабатывает ли какой-либо компонент.
  • On-invoke: токены, которые стоит компонент при срабатывании. Показано для каждого компонента отдельно, а не как итог плагина, потому что типичная сессия вызывает только подмножество компонентов.

Этот пример показывает, как выглядит вывод для плагина с двумя навыками:

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  SessionStart  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

Итог always-on вычисляется через API count_tokens для вашей активной модели. Числа для каждого компонента пропорционально масштабируются от этого итога. Если API недоступен, команда возвращается к оценке на основе символов.

plugin validate

Проверьте плагин или маркетплейс на синтаксические и схемные ошибки перед публикацией.

Команда выходит с кодом 0 при успешной валидации, 1 при неудаче и 2 при неудаче самого запуска валидации, например когда переданный путь нечитаем.

claude plugin validate <path> [options]

Команда принимает эти аргументы:

Команда принимает эти опции:

Опция Описание По умолчанию
--strict Рассматривать предупреждения как ошибки и выходить с кодом 1 при них. Используйте в CI для перехвата проблем, которые допускает среда выполнения, такие как unrecognized fields
--json Вывести отчёт валидации как один объект JSON с теми же кодами выхода. Требует Claude Code v2.1.259 или позже
-h, --help Показать справку по команде

С --json Claude Code записывает отчёт в stdout как один объект JSON с этими полями верхнего уровня:

  • success: тот же вердикт, который даёт код выхода
  • strict: рассматривала ли запуск предупреждения как ошибки
  • target: разрешённый путь, который Claude Code валидировал
  • manifest: собственный результат манифеста или null для запуска без манифеста
  • contents: результаты для каждого файла, каждый называет свой file и несёт массивы errors, warnings и notes

При выходе с кодом 2 команда ничего не записывает в stdout; сообщение об ошибке идёт в stderr.

В интерактивной сессии /plugin validate <path> запускает те же проверки встроенным образом.

plugin eval

Запустите eval cases плагина и выведите оценённые результаты. Требует Claude Code v2.1.269 или позже. Каждый случай — это подсказка плюс оценщики; Claude Code запускает его несколько раз в изолированной сессии только с целевым плагином загруженным, и по умолчанию также без плагина, чтобы отчёт показал разницу. См. Test plugins with evals для формата случаев, оценщиков, результатов и использования в CI.

claude plugin eval [target] [options]

Опциональный target — это каталог плагина, один файл prompt.md или case.yaml, установленный плагин как name или name@marketplace, или name@skills-dir, и по умолчанию текущий каталог. Поместите его перед --tag, --allow-tools и --json.

Эта таблица выводит опции, которые используют большинство запусков. Запустите claude plugin eval --help для полного набора, включая --case, --tag, --output-dir, --report, --allow-real-servers, --keep-temp и --verbose.

Опция Описание По умолчанию
--runs <n> Запусков на случай на ветвь Каждого случая runs, иначе 3
-j, --concurrency <n> Сессии агентов для запуска одновременно, от 1 до 8. Они делят ваш лимит скорости 1
--model <model> Модель для тестируемого агента Каждого случая model, иначе ANTHROPIC_MODEL если установлено, иначе по умолчанию Claude Code
--judge-model <model> Модель для оценщиков llm и baseline Маленькая быстрая модель
--ablation <mode> none или with-without. См. Compare against a no-plugin baseline with-without когда плагин разрешается, иначе none
--threshold <0..1> Выход 1 если какой-либо случай оценивается ниже этого 1.0
--max-cost-usd <usd> Остановиться перед следующим запуском после достижения расходов этого, выход 2 и вывести частичные результаты Нет потолка
--allow-tools <tools...> Предоставить инструменты сверх набора только для чтения, такие как Bash, Write, Edit или "mcp__plugin_<plugin>_<server>__*". См. Grant tools
--scaffold Запустить scaffold_script каждого случая Выключено
--trust-plugin Пропустить подсказку доверия при первом запуске, для CI. См. What a run can access Выключено
--mocks <mode> record или off. См. Mock MCP servers record
--eval-dir <dir> Каталог ниже плагина, который содержит случаи experimental.evals манифеста, иначе evals
--json [path] Вывести документ результата в stdout или записать его в путь .json
--no-publish Держать отчёт HTML локально
-h, --help Показать справку по команде

Команда выходит с кодом 0 когда каждый случай соответствует пороговому значению, 1 при неудачном случае, ошибке загрузки или недоверенном каталоге плагина, 2 при частичном запуске, 130 при прерывании и 143 при завершении. См. Run evals in CI.

plugin eval init

Создайте набор eval для плагина в текущем каталоге. Требует Claude Code v2.1.269 или позже. В терминале это запускает интервью по авторству, которое читает плагин, предлагает случаи и оценщики, пилотирует их и записывает файлы. С --bare или без терминала, оно записывает пустой шаблон одного случая вместо этого. Запустите из интерактивной сессии Claude Code, оно выводит инструкции интервью для этой сессии, чтобы следовать, а не записывать шаблон. См. Create your first eval suite.

claude plugin eval init [name] [options]

Опциональный name — это имя случая: интервью не нуждается в нём, в то время как --bare и путь шаблона без терминала требуют его. Он принимает эти опции:

Опция Описание По умолчанию
--bare Записать пустой prompt.md и graders/criteria.md для <name> вместо запуска интервью
-i, --interactive Требовать интервью. Завершается с ошибкой без терминала вместо записи шаблона
--eval-dir <dir> Каталог ниже текущего каталога для записи случаев в experimental.evals манифеста, иначе evals
-h, --help Показать справку по команде

plugin tag

Создайте тег выпуска git для плагина. По умолчанию команда помечает плагин в текущем каталоге; передайте путь для пометки плагина в другом месте. См. Tag plugin releases.

claude plugin tag [path] [options]

Команда принимает эти аргументы:

  • [path]: Путь к каталогу плагина. По умолчанию текущий каталог.

Команда принимает эти опции:

Опция Описание По умолчанию
--push Отправить тег на удалённый репозиторий после создания
--dry-run Вывести то, что будет помечено, без создания тега
-f, --force Создать тег даже если рабочее дерево грязное или тег уже существует
-m, --message <msg> Сообщение аннотации тега. Используйте %s как заполнитель для версии
--remote <name> Удалённый репозиторий для отправки с --push origin
-h, --help Показать справку по команде

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

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

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

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

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

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

Проблема Причина Решение
Плагин не загружается Неверный plugin.json Запустите claude plugin validate ./my-plugin или /plugin validate ./my-plugin, где ./my-plugin — это директория вашего плагина, чтобы проверить plugin.json, hooks/hooks.json и frontmatter skills, agents и commands в директориях плагина по умолчанию на синтаксические и схемные ошибки. См. Validate a plugin or a directory without a manifest для информации о том, что охватывает запуск
Skills не отображаются Неправильная структура директории Убедитесь, что skills/ или commands/ находится в корне плагина, а не внутри .claude-plugin/
Hooks не срабатывают Скрипт не исполняемый Запустите chmod +x script.sh
MCP сервер не работает Отсутствует ${CLAUDE_PLUGIN_ROOT} Используйте переменную для всех путей плагина
Ошибки пути Используются абсолютные пути Сделайте пути относительными, начиная с ./; см. Path behavior rules, которые охватывают исключение "." в поле skills
LSP Executable not found in $PATH Языковой сервер не установлен Установите бинарный файл (например, npm install -g typescript-language-server typescript)

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

Ошибки валидации манифеста:

  • Invalid JSON syntax: Unexpected token } in JSON at position 142: проверьте наличие пропущенных запятых, лишних запятых или неэкранированных строк
  • Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined: отсутствует обязательное поле
  • Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: ошибка синтаксиса JSON. До версии 2.1.246 Claude Code также выдавал эту ошибку для plugin.json, сохранённого как UTF-8 с начальной меткой порядка байтов (BOM), даже когда 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 в записи marketplace

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

Скрипт 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 соответствует вашим инструментам: "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/.

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

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

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

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

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

Для каждого типа источника, кроме command, Claude Code разрешает версию из первого из следующих установленных параметров:

  1. Поле version в plugin.json плагина
  2. Поле version в записи плагина на marketplace в marketplace.json
  3. SHA коммита git источника плагина для источников github, url, git-subdir и relative-path в marketplace, размещённом на git
  4. Дайджест SHA-256 для archive источников: пин sha256 в записи marketplace или дайджест загруженного файла, когда вы не устанавливаете пин. Claude Code сокращает его до первых 12 символов
  5. unknown для источников npm или локальных каталогов, не находящихся в репозитории git

Для command источника Claude Code всегда выводит версию из того, что произвёл команда: 12-символный хеш содержимого самостоятельно или добавленный к версии plugin.json как <version>-<hash>, когда он установлен. Claude Code игнорирует поле version записи marketplace для источников command. Команда, чей хешированный вывод изменяется, поэтому создаёт новую версию, даже когда строка авторской версии остаётся той же. В режиме ссылки хеш охватывает реальный путь напечатанного каталога и его записи верхнего уровня, а не содержимое файла.

Для этих типов источников это даёт вам три способа версионирования плагина:

Подход Как Поведение обновления Лучше всего для
Явная версия Установите "version": "2.1.0" в plugin.json Пользователи получают обновления только при изменении этого поля. Отправка новых коммитов без изменения этого поля не имеет эффекта, и /plugin update сообщает "already at the latest version". Опубликованные плагины со стабильными циклами выпуска
Версия Commit-SHA Опустите version из plugin.json и записи marketplace Пользователи получают обновления всякий раз, когда изменяется разрешённый коммит источника Внутренние или командные плагины в активной разработке
Версия Digest Используйте archive источник и опустите version из plugin.json и записи marketplace С пином sha256 пользователи получают обновления при изменении пина. Без него пользователи получают обновления всякий раз, когда изменяются байты размещённого zip-файла Плагины, опубликованные как zip-файлы на статическом сервере или репозитории артефактов

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

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

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