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

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

​

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

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

​

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

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

​

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

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 сообщает о той же проблеме при загрузке плагина

​

Поля

​

name

​

displayName

​

version

​

metadata

​

defaultEnabled

​

dependencies

​

settings

​

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

​

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

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

​

commands

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

​

hooks

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

​

mcpServers

​

lspServers

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

​

monitors

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

​

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

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

​

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

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

​

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

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

​

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

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

​

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

​

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

• ${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

​

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

​

Каналы

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

​

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

​

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

​

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

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

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

​

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

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

​

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

​

Как поля записи объединяются с 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

​

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

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

​

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

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