SpyBara
Go Premium

plugins/manifest-reference.md 2026-09-24 22:57 UTC to 2026-09-25 23:58 UTC

This page contains 710 additions and 0 deletions.

2026
Fri 25 23:58

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

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

Манифест плагина — это файл plugin.json в директории .claude-plugin/ плагина. Он содержит метаданные плагина и значения userConfig, которые Claude Code запрашивает у пользователя. Он также объявляет любой компонент, который вы определяете встроенным образом или храните вне его расположения по умолчанию.

Этот справочник предназначен для создателей плагинов и для владельцев маркетплейсов, которые размещают поля компонентов в записи маркетплейса.

Начните с раздела, который соответствует тому, что вы ищете:

Файл манифеста

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

Напишите манифест, когда вам нужны метаданные, компонент вне его директории по умолчанию, userConfig или встроенное определение компонента.

Сохраните манифест в .claude-plugin/plugin.json в корне плагина. Поместите все остальные файлы плагина в корень плагина, а не внутри .claude-plugin/. Это включает skills/, commands/ и hooks/.

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

{
  "name": "deploy-tools",
  "displayName": "Deploy Tools",
  "version": "1.2.0",
  "description": "Deployment commands, a review agent, and a status monitor",
  "author": {
    "name": "Example Team",
    "email": "dev@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/docs/deploy-tools",
  "repository": "https://github.com/example/deploy-tools",
  "license": "MIT",
  "keywords": ["deployment", "ci"],
  "defaultEnabled": true,
  "dependencies": ["secrets-vault"],
  "metadata": { "catalogId": "cat-123" },
  "skills": ["./extra-skills/"],
  "commands": {
    "status": {
      "source": "./commands/status.md",
      "description": "Show the current deployment status"
    },
    "about": {
      "content": "Explain what the deploy-tools plugin provides.",
      "description": "Describe this plugin"
    }
  },
  "agents": ["./agents/reviewer.md"],
  "hooks": "./config/extra-hooks.json",
  "mcpServers": {
    "deploy-api": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  },
  "lspServers": "./.lsp.json",
  "outputStyles": "./styles/",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./config/monitors.json"
  },
  "userConfig": {
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for the deployment API",
      "sensitive": true
    }
  }
}

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

Нераспознанный ключ верхнего уровня удаляется, а нераспознанный ключ внутри опции userConfig, записи channels, конфигурации lspServers или записи monitors отклоняется:

  • Поля верхнего уровня: поле удаляется и плагин загружается. claude plugin validate сообщает о каждом нераспознанном поле верхнего уровня как о предупреждении
  • Строгие объекты: опции userConfig, записи channels, конфигурации lspServers и записи monitors являются строгими. Неизвестный ключ внутри одного из них — это ошибка, и плагин не загружается

Проверка манифеста

claude plugin validate — это авторитетная проверка манифеста. Запустите его из вашей оболочки для директории плагина:

claude plugin validate ./my-plugin

Команда сообщает один из этих результатов:

  • Validation passed: манифест загружается
  • Validation passed with warnings: манифест загружается, но валидатор нашел что-то для исправления, например неизвестное поле верхнего уровня, которое Claude Code удаляет, name, который не в kebab-case, или отсутствующие version, description или author. Передайте --strict, чтобы превратить предупреждения в ошибки в CI
  • Validation failed: манифест имеет несоответствие типов, путь, который отсутствует или выходит за пределы корня плагина, или неизвестный ключ внутри опции userConfig, записи channels, конфигурации lspServers или записи monitors. Claude Code сообщает о той же проблеме при загрузке плагина

Поля

Таблица перечисляет ключи верхнего уровня в plugin.json. name — единственный обязательный ключ. Где имя поля является ссылкой, связанный раздел содержит его полные правила.

Для ключей компонентов, таких как commands и hooks, Формы путей компонентов показывает каждую принятую форму с примером, и каждый путь следует правилам путей для префикса ./, расширений и содержания.

Поле Тип Описание
$schema String URL JSON Schema для автодополнения редактора. Claude Code игнорирует его при загрузке
name String Идентификатор плагина, обязательный. Используйте kebab-case. Каждый компонент находится в пространстве имен под ним
displayName String Имя, показываемое в UI вместо name
version String Строка версии. Установка ее удерживает пользователей на этой версии, пока вы не измените ее
description String Краткое объяснение того, что предоставляет плагин
author Object name, который является обязательным, плюс необязательные email и url
homepage String URL документации. Должен анализироваться как URL, иначе плагин не загружается
repository String URL исходного репозитория. Не проверяется
license String Идентификатор SPDX, такой как MIT или Apache-2.0
keywords Array of strings Теги обнаружения
metadata Object Объект произвольной формы для ваших собственных данных. Claude Code не читает его
defaultEnabled Boolean Включен ли плагин при запуске, когда пользователь не установил его. По умолчанию true
dependencies Array of strings or objects Плагины, которые должны быть включены для работы этого
settings Object Параметры, которые Claude Code применяет при включении плагина. Действуют только agent и subagentStatusLine
userConfig Object Значения, которые Claude Code запрашивает у пользователя при включении плагина
channels Array of objects Каналы сообщений, которые предоставляет плагин, каждый привязан к одному из его MCP серверов
skills Path, or array of paths Директории для сканирования skills, каждая — директория папок <name>/SKILL.md или одна папка, содержащая SKILL.md напрямую. "." обозначает корень плагина. Добавляет к сканированию по умолчанию skills/
commands Path, array of paths, or object Плоские файлы команд .md, директории с ними или объект-карта имени команды на source или content. Заменяет сканирование по умолчанию commands/
agents Path, or array of paths Файлы агентов .md. Директории не принимаются. Заменяет сканирование по умолчанию agents/
hooks Path, object, or array of either Файлы hook .json или встроенная конфигурация hook. Загружаются вместе с hooks/hooks.json
mcpServers Path, object, or array of either Файлы конфигурации MCP .json, пакеты .mcpb или .dxt, или встроенные конфигурации серверов с ключами по имени. Загружаются вместе с .mcp.json; имя сервера, объявленное позже, заменяет более раннее
lspServers Path, object, or array of either Файлы конфигурации LSP .json или встроенные конфигурации серверов с ключами по имени. Загружаются вместе с .lsp.json
outputStyles Path, or array of paths Файлы стилей вывода или директории. Заменяет сканирование по умолчанию output-styles/
workflows Path, or array of paths Файлы Workflow .js или директории. Заменяет сканирование по умолчанию workflows/
experimental Object Контейнер для themes, monitors и evals, чья форма манифеста может еще измениться
experimental.themes Path, or array of paths Файлы тем или директории. Заменяет сканирование по умолчанию themes/. Ключ themes верхнего уровня все еще загружается с предупреждением claude plugin validate
experimental.monitors Path, or inline array Файл .json, содержащий массив monitors, или сам массив. По умолчанию monitors/monitors.json. Ключ monitors верхнего уровня все еще загружается с предупреждением claude plugin validate. Мониторы работают только в интерактивных сеансах и не на Amazon Bedrock, Google Cloud's Agent Platform или Microsoft Foundry
experimental.evals Path, or array of paths Директория, которая содержит eval cases плагина, когда это не директория по умолчанию evals/. claude plugin eval --eval-dir переопределяет ее

В столбце Type путь — это строка относительно корня плагина, например "./custom/commands".

`name`

Идентификатор плагина. Он должен быть непустым, без пробелов, @, :, разделителей пути, управляющих символов или символов двунаправленного форматирования; используйте kebab-case.

Claude Code помещает каждый компонент в пространство имен под ним, поэтому агент reviewer в плагине deploy-tools появляется как deploy-tools:reviewer.

`displayName`

Имя, показываемое в UI вместо name. Оно может содержать пробелы и любой регистр, и оно не используется для пространства имен или поиска.

Для плагина, установленного из маркетплейса, displayName в записи маркетплейса имеет приоритет над этим значением.

`version`

Строка версии, не проверяемая против semver. Установка ее закрепляет плагин на этой версии, пока вы не измените ее; см. Версии и обновления. Плагин с command source, плагин из маркетплейса, размещенного на claude.ai, и плагин загруженный на месте из маркетплейса, добавленного как локальная директория, не закреплены этим полем.

`metadata`

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

`defaultEnabled`

Включен ли плагин при запуске, когда пользователь не установил его в enabledPlugins. По умолчанию true. Плагин, от которого зависит включенный плагин, запускается включенным независимо. То же поле в записи маркетплейса переопределяет это.

После того как запись enabledPlugins пользователя написана, она сохраняется при обновлениях плагина, поэтому изменение defaultEnabled в более позднем выпуске не изменяет параметр для существующего пользователя.

`dependencies`

Плагины, которые должны быть включены для работы этого. Каждая запись — это "name", "name@marketplace" или { "name": "...", "marketplace": "...", "version": "..." }. Простые имена разрешаются против собственного маркетплейса этого плагина. См. ограничения зависимостей.

`settings`

Параметры, которые Claude Code применяет при включении плагина. Действуют только agent и subagentStatusLine; другие ключи удаляются при загрузке. settings.json в корне плагина имеет приоритет над этим ключом. См. Параметры по умолчанию.

Формы путей компонентов

Каждый ключ компонента принимает путь относительно корня плагина. hooks, mcpServers, lspServers и experimental.monitors также принимают встроенную конфигурацию, commands также принимает объект-карту, и mcpServers также принимает пути пакетов MCP и URL. Примеры, которые следуют, показывают каждую принятую форму один раз. Для того, что каждый компонент делает во время выполнения, см. Компоненты плагина.

Поля только с путями

agents, skills, outputStyles, workflows и experimental.themes принимают один путь или массив путей. Записи agents должны быть файлами .md, а записи skills должны быть директориями. Остальные три принимают директорию или файл.

{
  "agents": ["./custom-agents/reviewer.md", "./custom-agents/tester.md"],
  "skills": ["./extra-skills/", "."],
  "outputStyles": "./styles/"
}

`commands`

commands принимает путь, массив путей или объект-карту. Путь обозначает плоский файл команды .md или директорию. В объект-карте каждый ключ становится именем команды после префикса плагина. Например, "about" в плагине deploy-tools запускается как /deploy-tools:about.

Каждое значение устанавливает ровно один из source или content, и запись, которая устанавливает оба или ни один, не проходит проверку. Остальные поля в этой таблице являются необязательными:

Поле Тип Описание
source string Путь к файлу Markdown команды относительно корня плагина
content string Встроенный Markdown для тела команды вместо source
description string Описание, показываемое для команды
argumentHint string Подсказка аргумента, показываемая после имени команды, например [file]
model string Модель по умолчанию для команды
allowedTools array of strings Инструменты, которые команда может использовать без запроса

Эта карта объявляет одну команду из файла и одну из встроенного содержимого:

{
  "commands": {
    "status": { "source": "./commands/status.md", "argumentHint": "[env]" },
    "about": { "content": "Explain what this plugin provides." }
  }
}

`hooks`

hooks принимает путь файла .json, встроенный объект hooks в той же форме, что и hooks в settings.json, или массив, смешивающий оба. Для событий hook и полей обработчика см. справочник hooks.

Claude Code объединяет все, что вы объявляете, с hooks/hooks.json, когда этот файл существует.

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

`mcpServers`

mcpServers принимает путь файла .json, путь пакета MCP или URL, встроенную карту или массив, смешивающий их. Для полей конфигурации сервера см. MCP серверы, предоставляемые плагином.

Claude Code загружает .mcp.json в корне плагина первым, затем каждую объявленную форму по порядку. Имя сервера, объявленное позже, заменяет более раннее.

Значение mcpServers принимает одну из этих форм:

Форма Пример значения Что делает Claude Code
Путь файла .json "./mcp/servers.json" Читает файл как карту mcpServers
Путь пакета MCP "./bundle.mcpb" Извлекает пакет .mcpb или .dxt в .mcpb-cache/ в корне плагина и читает его конфигурацию сервера
URL пакета MCP "https://example.com/server.mcpb" Загружает пакет в .mcpb-cache/, затем читает его
Встроенная карта { "deploy-api": { "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"] } } Использует карту как конфигурации серверов с ключами по имени

Путь пакета или URL должен заканчиваться на .mcpb или .dxt. Любое другое расширение не проходит проверку.

`lspServers`

lspServers принимает путь файла .json, встроенную карту имени сервера на конфигурацию или массив любого из них.

Claude Code загружает .lsp.json в корне плагина первым, затем каждую объявленную конфигурацию по порядку. Имя сервера, объявленное позже, заменяет более раннее.

Каждая конфигурация сервера — это строгий объект с этими полями. Неизвестный ключ не проходит проверку.

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

Эта встроенная конфигурация запускает gopls для файлов .go:

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

Для языковых серверов, которые Anthropic публикует как плагины, и того, как серверы ведут себя во время выполнения, см. Интеллект кода.

`monitors`

experimental.monitors принимает путь файла .json или встроенный массив. Когда вы опускаете ключ, Claude Code загружает monitors/monitors.json, если он существует.

Каждая запись — это строгий объект с этими полями.

Поле Обязательное Описание
name Yes Идентификатор, уникальный в пределах плагина
command Yes Команда оболочки, которую Claude Code запускает как постоянный фоновый процесс в директории работы сеанса
description Yes Краткое резюме, показываемое в панели задач и сводках уведомлений
when No С "always", по умолчанию, монитор запускается при запуске сеанса и при перезагрузке плагина. С "on-skill-invoke:<skill>", он запускается в первый раз, когда запускается этот skill

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

{
  "experimental": {
    "monitors": [
      {
        "name": "deploy-status",
        "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
        "description": "Deployment status changes",
        "when": "on-skill-invoke:deploy"
      }
    ]
  }
}

Команда монитора command не может ссылаться на ${user_config.*}. См. Поля, которые работают через оболочку.

Правила путей

Каждый путь компонента в манифесте относителен корню плагина и должен начинаться с ./. Путь, такой как commands/foo.md, не проходит проверку. skills и mcpServers каждый принимают одну форму вне этого правила:

  • skills: также принимает ".". Оба "." и "./" обозначают корень плагина. До v2.1.221 "." не проходил проверку манифеста, поэтому используйте "./", когда плагин должен загружаться на более ранних версиях
  • mcpServers: также принимает URL пакета https://

Содержание и существование

Каждый путь компонента должен разрешаться внутри корня плагина и должен существовать. claude plugin validate не проверяет пути outputStyles, lspServers, monitors или themes, поэтому плохой путь в этих полях не загружается только при загрузке плагина:

  • Содержание: путь, который разрешается вне корня плагина, не загружается, и вкладка /plugin Errors показывает <component> path escapes plugin directory: <path>. Путь, содержащий .., — обычный случай, и claude plugin validate сообщает об этом как Path contains ".." which could be a path traversal attempt
  • Существование: путь, который не существует, не загружается, и вкладка /plugin Errors показывает <component> path not found: <path>. claude plugin validate сообщает об этом как Path not found

Как каждый ключ объединяется с его расположением по умолчанию

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

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

Если плагин имеет папку по умолчанию, такую как commands/, и также устанавливает ключ манифеста, который ее заменяет, Claude Code загружает пути манифеста, а не папку. claude plugin list и интерфейс /plugin затем показывают предупреждение Default <folder>/ folder is ignored because the manifest sets "<key>".

Чтобы избежать предупреждения, установите ключ на путь внутри этой папки: "commands": ["./commands/deploy.md"] обозначает файл в папке по умолчанию и не производит предупреждение.

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

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

Ключи — это идентификаторы, состоящие из букв, цифр и подчеркиваний, и не могут начинаться с цифры.

Каждое значение — это строгий объект с этими полями. Неизвестный ключ не проходит проверку.

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

Каждая опция каждого включенного плагина также появляется как строка в панели /config, кроме sensitive опций и multiple списков. Строки /config требуют Claude Code v2.1.269 или позже.

Этот userConfig объявляет конечную точку и замаскированный токен:

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

Ограничить поле фиксированными опциями

Установите options на поле userConfig, чтобы пользователи выбирали его значение из фиксированного списка.

Чтобы ограничить поле tone тремя опциями, перечислите их в options и установите default на одну из них:

{
  "userConfig": {
    "tone": {
      "type": "string",
      "title": "Tone",
      "description": "Voice for generated replies",
      "options": ["neutral", "warm", "formal"],
      "default": "neutral"
    }
  }
}

Если вы объявляете options на любом поле, пользователи на версиях Claude Code до v2.1.271 не могут загрузить плагин.

options применяется к полю string, которое не является multiple или sensitive. Установите default на одно из перечисленных значений или установите required: true, чтобы пользователь выбрал одно. Каждая опция — это простая метка от 1 до 64 символов, и claude plugin validate, который вы запускаете в вашей оболочке, сообщает обо всем остальном, что он отклоняет. Плагин, чьи options нарушают эти правила, не загружается.

Где сохраняются значения

Нечувствительные значения сохраняются в pluginConfigs в settings.json пользователя. Чувствительные значения идут в безопасное хранилище учетных данных платформы вместо этого. На странице параметров указано, из каких файлов параметров читается pluginConfigs.

Ссылка на сохраненное значение

Ссылайтесь на сохраненное значение, где плагин его нужен, в одной из двух форм:

  • ${user_config.KEY}: подставляется в конфигурацию MCP сервера, конфигурацию LSP сервера, exec-form hook args и содержимое skill и agent. В содержимом skill и agent подставляются только нечувствительные значения, и чувствительное значение там становится заполнителем
  • CLAUDE_PLUGIN_OPTION_<KEY>: экспортируется в процессы hook для каждой опции, с <KEY> в верхнем регистре. Shell-form hook читает $CLAUDE_PLUGIN_OPTION_API_TOKEN для api_token

Поля, которые работают через оболочку

Shell-form hook команды, команды монитора и MCP headersHelper отклоняют ${user_config.*}. Компонент, который ссылается на него в одном из этих полей, не работает с ошибкой вместо запуска, потому что значение поля передается оболочке, которая переанализирует подставленное значение.

Таблица показывает, как значение может достичь каждого из этих полей вместо этого.

Поле Как значение может достичь его
Shell-form hook команды Используйте exec form с args или читайте CLAUDE_PLUGIN_OPTION_<KEY> из окружения hook
Команды монитора Не через Claude Code. Процессы монитора не получают CLAUDE_PLUGIN_OPTION_<KEY>, поэтому скрипт монитора должен получить значение самостоятельно
MCP headersHelper Не через Claude Code. Окружение помощника содержит CLAUDE_PLUGIN_ROOT, CLAUDE_CODE_MCP_SERVER_NAME и CLAUDE_CODE_MCP_SERVER_URL, но не значения опций, поэтому скрипт помощника должен получить значение самостоятельно

Каналы

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

Каждая запись — это строгий объект, привязанный к одному из MCP серверов плагина, с этими полями:

Поле Обязательное Описание
server Yes Ключ MCP сервера в mcpServers этого плагина, к которому привязан канал
displayName No Имя, показываемое в заголовке диалога конфигурации. По умолчанию имя сервера
userConfig No Опции для запроса, в той же форме, что и верхнего уровня userConfig. Сохраненные значения подставляются в ссылки ${user_config.KEY} в env сервера

Этот манифест привязывает канал к MCP серверу telegram плагина и запрашивает токен бота, который подставляется в env сервера:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "displayName": "Telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

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

Claude Code предоставляет три переменные пути компонентам плагина. Ссылайтесь на них как ${NAME} в полях, перечисленных в Где каждая переменная разрешается, и читайте их как переменные окружения в процессах, которые их получают.

Переменная Разрешается в Используйте для
${CLAUDE_PLUGIN_ROOT} Абсолютный путь установленной версии плагина Скрипты, бинарные файлы и файлы конфигурации, поставляемые с плагином
${CLAUDE_PLUGIN_DATA} ~/.claude/plugins/data/<id>/, создается при первой ссылке и сохраняется при обновлениях плагина. <id> — это идентификатор плагина с каждым символом, отличным от буквы, цифры, _ или -, замененным на - Установленные зависимости, такие как node_modules, сгенерированный код и кэши
${CLAUDE_PROJECT_DIR} Корень проекта Скрипты и файлы конфигурации, локальные для проекта

${CLAUDE_PLUGIN_ROOT} изменяется при обновлении плагина, поэтому не записывайте состояние туда. Для того, где корень перемещается и когда старая директория очищается, см. страницу загрузки.

Когда вы удаляете плагин из последнего места, где он установлен, директория ${CLAUDE_PLUGIN_DATA} удаляется, если вы не передадите --keep-data.

Где каждая переменная разрешается

В каждом компоненте плагина ссылки ${...} разрешаются встроенным образом в определенных полях, и некоторые компоненты также получают переменные в окружении их процесса:

Компонент плагина Поля, где ${...} разрешается Экспортируется в процесс
Команды Hook Где угодно в command и args CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DATA, CLAUDE_PROJECT_DIR и CLAUDE_PLUGIN_OPTION_<KEY>
Команды монитора Где угодно в command Не экспортируется
MCP stdio серверы command, args, env CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DATA
MCP http, sse, ws серверы url, headers, headersHelper Не применимо
LSP серверы command, args, env, workspaceFolder CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DATA, CLAUDE_PROJECT_DIR
Содержимое Skill, команды и агента Где угодно в теле Markdown Не применимо

Переменные отсутствуют в окружении команд, которые Claude запускает через инструмент Bash, в основном сеансе или в подагенте. В содержимом skill, команды и агента напишите ссылку ${...} в теле Markdown вместо этого, и Claude Code подставляет путь встроенным образом при загрузке содержимого.

Кавычки и разделители пути

Сохраняйте каждый подставленный путь одним аргументом:

  • Команды Hook: используйте exec form с args, чтобы каждый путь был одним аргументом без кавычек
  • Shell-form hooks и команды монитора: оберните переменную в двойные кавычки, чтобы путь с пробелами оставался одним словом

Этот shell-form hook запускает скрипт, поставляемый с плагином:

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

На Windows подставленные пути используют прямые слэши, поэтому оболочка не читает обратные слэши как экранирование.

Стандартное расположение

Каждый тип компонента имеет расположение по умолчанию в корне плагина, используемое, когда манифест не указывает иное.

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

Плагин, который использует каждое расположение по умолчанию, плюс папку scripts/, которую вызывают его hooks, расположен следующим образом:

deploy-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── deploy/
│       └── SKILL.md
├── commands/
│   └── status.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
├── monitors/
│   └── monitors.json
├── output-styles/
│   └── terse.md
├── themes/
│   └── dracula.json
├── workflows/
│   └── release-audit.js
├── bin/
│   └── deploy-tool
├── scripts/
│   └── format.sh
├── settings.json
├── .mcp.json
└── .lsp.json

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

CLAUDE.md в корне плагина не загружается как контекст, и claude plugin validate предупреждает, когда находит его. Чтобы включить инструкции, которые загружаются в контекст Claude, поместите их в skill.

Записи маркетплейса и манифест

Запись маркетплейса принимает каждое поле на этой странице наряду с его собственными полями, включая strict.

Поле strict решает, может ли запись добавлять компоненты к плагину, который имеет свой plugin.json. По умолчанию true.

Как поля записи объединяются с `plugin.json`

Запись либо служит манифестом, добавляет компоненты к нему, либо конфликтует с ним:

  • Нет plugin.json: запись — это манифест, независимо от strict. Hooks записи загружаются только в встроенной форме объекта. Для пути файла или массива там вкладка /plugin Errors показывает ошибку not yet supported in a marketplace entry
  • plugin.json присутствует, strict не установлен или true: Claude Code загружает манифест и добавляет commands, agents, skills, outputStyles и themes записи к нему. Для hooks, matchers записи для события заменяют matchers манифеста для того же события, и события, которые объявляет только манифест, сохраняют свои
  • plugin.json присутствует, strict: false: запись, которая объявляет любой из commands, agents, skills, hooks, outputStyles или themes, — это конфликт, и плагин не загружается с Plugin <name> has conflicting manifests

Когда запись маркетплейса, чей source — корень маркетплейса, перечисляет определенные поддиректории skills, загружаются только эти поддиректории, и директория по умолчанию skills/ плагина не сканируется. Ключ skills в манифесте вместо этого добавляет к по умолчанию.

Приоритет метаданных

Некоторые поля метаданных имеют фиксированный приоритет независимо от strict:

  • defaultEnabled и поля отображения: defaultEnabled записи и ее поля отображения, такие как displayName, переопределяют манифеста
  • version: version манифеста переопределяет запись
  • name: когда запись перечисляет плагин под другим name, чем манифест, enabledPlugins использует имя записи, и компоненты находятся в пространстве имен под именем манифеста

Для полной таблицы приоритета см. Строгий режим.

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