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

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

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

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

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

• Поле: таблица Поля дает тип каждого поля, является ли оно обязательным, его значение по умолчанию и что оно принимает. Правила путей охватывает префикс ./ и содержание для каждого пути компонента
• Опция userConfig или запись channels: схемы Конфигурация пользователя и Каналы
• ${CLAUDE_PLUGIN_ROOT} или другая переменная, на которую может ссылаться плагин: Переменные окружения
• Где находятся файлы каждого компонента: Стандартное расположение
• Сообщение от claude plugin validate: на странице устранения неполадок перечислены все сообщения с их исправлениями и ссылками на соответствующие разделы этой страницы

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

Манифест является необязательным. Без него 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, Формы путей компонентов показывает каждую принятую форму с примером, и каждый путь следует правилам путей для префикса ./, расширений и содержания.

В столбце 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, и запись, которая устанавливает оба или ни один, не проходит проверку. Остальные поля в этой таблице являются необязательными:

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

{
  "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 принимает одну из этих форм:

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

`lspServers`

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

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

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

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

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

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

`monitors`

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

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

Этот встроенный массив объявляет один монитор, который запускается в первый раз, когда запускается 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 сами.

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

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

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

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

Каналы

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

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

Этот манифест привязывает канал к 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} удаляется, если вы не передадите --keep-data.

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

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

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

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

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

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

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

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

• Добавить компоненты к плагину: что каждый компонент делает во время выполнения, с примером, который проходит проверку
• Справочник маркетплейса: поля записи, которые маркетплейс может установить для вашего плагина
• Справочник команд плагина: флаги и вывод claude plugin validate
• Устранение неполадок плагинов: каждое сообщение проверки с его исправлением