Добавление компонентов в плагин

​

Изучите каталог плагинов

• Skill для проверки и команду about
• Subagent для проверки безопасности
• Hook, который форматирует файлы после редактирования Claude, и папку scripts/, которую он вызывает
• Монитор логов
• Стиль вывода и цветовую тему
• Workflow для аудита маршрутов
• Исполняемый файл hello-plugin
• Параметры по умолчанию
• Локальный MCP сервер и языковой сервер Go

​

Добавление каждого вида компонента

​

Skills

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── review/
        └── SKILL.md

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

• Имя команды: /<plugin>:<directory>, поэтому skills/review/SKILL.md в my-plugin — это /my-plugin:review. Если вы установите name в frontmatter, он заменит последний сегмент, и префикс плагина остаётся. См. как skill получает имя команды
• Кто вызывает: Claude, пользователь или оба, контролируется frontmatter. См. Control who invokes a skill

• Дополнительные директории: перечислите их в ключе манифеста skills. Они добавляются к сканированию по умолчанию skills/, а не заменяют его, в отличие от commands и agents
• Один skill в корне плагина: без директории skills/ и без ключа манифеста skills, SKILL.md в корне плагина загружается как один skill. Установите name в его frontmatter, потому что иначе установка из marketplace назовёт skill по его директории кэша, а не по вашему плагину

​

Команды

​

Определение команд в манифесте

{
  "name": "my-plugin",
  "commands": {
    "about": {
      "content": "Summarize what this repository does in three sentences.",
      "description": "Summarize the repository"
    }
  }
}

​

Агенты

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

​

Организация агентов в подпапках

• Frontmatter name: он заменяет только имя файла, поэтому name: audit в agents/review/security.md загружается как my-plugin:review:audit
• Манифест agents поле: файл, который вы там перечислите, загружается без имён подпапок, поэтому "agents": "./custom/review/security.md" загружается как my-plugin:security

​

Поля frontmatter в агентах плагина

• Поддерживаемые поля: name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, omitClaudeMd, isolation, color и ключ cacheTtl из experimental. Единственное допустимое значение isolation — это "worktree". См. поддерживаемые поля frontmatter для того, что делает каждое
• Игнорируемые поля: permissionMode, hooks, mcpServers и initialPrompt. Файл агента не может добавлять hooks или MCP серверы самостоятельно, поэтому добавляйте их как плагин hooks и MCP серверы вместо этого
• Frontmatter, который не парсится: агент всё ещё загружается со всеми полями, игнорируемыми. Он назван по имени файла, и его описание читается как Agent from my-plugin plugin. Запустите claude plugin validate в вашей оболочке, чтобы найти эти файлы

​

Hooks

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

​

Когда запускаются hooks плагина

​

Окружение, кавычки и соответствие инструментам MCP

• Окружение: каждый процесс hook получает CLAUDE_PLUGIN_ROOT и CLAUDE_PLUGIN_DATA в своём окружении, плюс CLAUDE_PLUGIN_OPTION_<KEY> для каждого значения конфигурации пользователя, поэтому ваш скрипт может читать их оттуда
• Кавычки: когда command не имеет args, он запускается через оболочку, поэтому оберните путь ${CLAUDE_PLUGIN_ROOT} в двойные кавычки, как пример hooks/hooks.json под Hooks делает, чтобы сохранить развёрнутый путь одним словом оболочки. Когда вы передаёте args вместо этого, каждый элемент передаётся как один аргумент без оболочки и не нуждается в кавычках. См. exec form and shell form
• Соответствие собственным инструментам MCP плагина: инструмент из MCP сервера, который объявляет этот плагин, назван mcp__plugin_<plugin>_<server>__<tool>, поэтому напишите это полное имя в matcher. Matcher только на имя сервера никогда не запускается. См. Match MCP tools

​

MCP серверы

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

​

Достижение пользователей на claude.ai и Cowork

​

Имена серверов, имена инструментов и перезагрузки

• Имя сервера: plugin:<plugin>:<server>, поэтому сервер db в my-plugin — это plugin:my-plugin:db в /mcp. Используйте ту же форму для именования сервера в hook mcp_tool
• Имена инструментов: mcp__plugin_<plugin>_<server>__<tool>, поэтому инструмент query на том сервере db — это mcp__plugin_my-plugin_db__query. Это имя, которое нужно использовать в правилах разрешений и matchers hook
• Подстановка: ${CLAUDE_PLUGIN_ROOT} и другие переменные пути подставляются в command, args и env. Кавычки не нужны в args, потому что каждый элемент передаётся как один аргумент
• Перезагрузка: когда пользователь запускает /reload-plugins и перезагрузка применяется, сервер, конфигурация которого не изменилась, сохраняет своё соединение. Сервер, конфигурация которого изменилась, переподключается, и тот, который вы удалили, отключается

​

Включение упакованного MCPB сервера

{
  "name": "my-plugin",
  "mcpServers": "./servers/db.mcpb"
}

​

LSP серверы

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

• Отсутствующий двоичный файл: Claude Code запускает command по имени из PATH пользователя. Когда двоичный файл там не находится, сервер не запускается и claude --debug логирует LSP server <name> failed to start
• Конфликты расширений: когда два включённых сервера претендуют на одно и то же расширение, первый зарегистрированный обрабатывает эти файлы, а другой не используется для них, независимо от того, поступают ли серверы из одного плагина или двух. Вкладка Errors в /plugin показывает предупреждение LSP server "<name>" is not used for <ext> files

​

Исполняемые файлы

#!/bin/bash
echo "hello from my-plugin"

​

Параметры по умолчанию

{
  "agent": "security-reviewer"
}

• Файл над манифестом: когда оба существуют и settings.json устанавливает по крайней мере один поддерживаемый ключ, settings.json применяется и settings манифеста игнорируется
• Параметры пользователя над значениями по умолчанию плагина: во всех источниках параметров значения по умолчанию плагина — это самый низкий уровень, поэтому собственный agent пользователя в ~/.claude/settings.json переопределяет ваш
• Два плагина устанавливают один и тот же ключ: значение из плагина, загруженного последним, применяется, и claude --debug логирует overrides setting

​

Темы и стили вывода

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

​

Каналы

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

​

Мониторы

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

• Только интерактивные сессии: мониторы плагина запускаются в интерактивной сессии и никогда в неинтерактивном режиме с флагом -p. Они также запускаются только там, где доступен инструмент Monitor
• Нет конфигурации пользователя: command получает переменные пути и ${ENV_VAR} из окружения, но никогда ${user_config.*}. Монитор, который ссылается на один, не запускается, и процессы монитора также не получают CLAUDE_PLUGIN_OPTION_<KEY>
• Отключение во время сессии: если вы отключите плагин во время сессии, Claude Code не останавливает мониторы, которые уже работают. Они останавливаются, когда сессия заканчивается

​

Запрос значений конфигурации у пользователя

{
  "name": "my-plugin",
  "userConfig": {
    "api_url": {
      "type": "string",
      "title": "API URL",
      "description": "Base URL of your team's API"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for your team's API",
      "sensitive": true
    }
  }
}

​

Когда появляется диалог конфигурации

• Устанавливает плагин в /plugin
• Запускает /plugin install <plugin>@<marketplace> внутри сессии
• Включает плагин из вкладки Installed в /plugin

​

Ссылка на пути плагина и хранение данных

• ${CLAUDE_PLUGIN_ROOT}: директория установки плагина. Каждая версия имеет свою собственную директорию кэша, поэтому путь изменяется при обновлении плагина. Не пишите состояние там
• ${CLAUDE_PLUGIN_DATA}: директория, которая выживает обновления, для node_modules, виртуальных окружений и кэшей. Она разрешается в ~/.claude/plugins/data/<id>/ и создаётся при первой ссылке
• ${CLAUDE_PROJECT_DIR}: корень проекта, то же значение, которое получают hooks

​

Установка зависимостей в директорию данных

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

​

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

• Plugin manifest reference: поля plugin.json, правила пути и стандартная раскладка
• Test plugins with evals: проверьте, что компоненты, которые вы добавили, изменяют поведение Claude так, как вы намеревались
• Publish and distribute a plugin: версионируйте плагин и поместите его в marketplace
• Troubleshoot plugins: что делать, когда компонент не загружается или hook не запускается