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

​

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

​

Skills

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

• Skills и команды автоматически обнаруживаются при установке плагина
• Claude может вызывать их автоматически на основе контекста задачи
• Skills могут включать вспомогательные файлы рядом с SKILL.md

​

Agents

---
name: agent-name
description: Что специализирует этот агент и когда Claude должен его вызвать
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Подробное системное приглашение для агента, описывающее его роль, опыт и поведение.

• Агенты появляются в интерфейсе @-mention typeahead под их областью видимости, такой как my-plugin:code-reviewer, после включения плагина
• Claude может вызывать агентов автоматически на основе контекста задачи
• Агенты могут быть вызваны вручную пользователями
• Плагины agents работают наряду со встроенными agents Claude

​

Hooks

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

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

​

MCP servers

{
  "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
• Возможности сервера беспрепятственно интегрируются с существующими инструментами Claude
• Серверы плагина можно настраивать независимо от серверов MCP пользователя

​

LSP servers

• Мгновенная диагностика: Claude видит ошибки и предупреждения сразу после каждого редактирования
• Навигация по коду: переход к определению, поиск ссылок и информация при наведении
• Осведомлённость о языке: информация о типах и документация для символов кода

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

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

​

Monitors

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

​

Themes

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

​

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

​

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

​

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

• Серверы MCP, которые он объявляет, проходят через то же одобрение для каждого сервера что и проект .mcp.json
• Серверы LSP запускаются только после того, как вы доверяете рабочей области
• Фоновые monitors не загружаются

​

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

claude plugin disable my-tool@skills-dir

​

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

​

Полная схема

{
  "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"],
  "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"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

​

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

​

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

claude plugin validate ./my-plugin --strict

​

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

​

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

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

​

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

​

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

​

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

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

​

Каналы

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

​

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

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

• Все пути должны быть относительны к корню плагина и начинаться с ./
• Компоненты из пользовательских путей используют те же правила именования и пространства имён
• Несколько путей можно указать как массивы
• Когда путь skill указывает на каталог, который содержит SKILL.md напрямую, например "skills": ["./"], указывающий на корень плагина, поле frontmatter name в SKILL.md определяет имя вызова skill. Это обеспечивает стабильное имя независимо от каталога установки. Если name не установлен в frontmatter, в качестве резервного варианта используется имя каталога.

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

​

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

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

​

Каталог постоянных данных

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

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

​

Кэширование плагина и разрешение файлов

• Через claude --plugin-dir или claude --plugin-url, на время сеанса.
• Через маркетплейс, установленный для будущих сеансов.

​

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

​

Совместное использование файлов в маркетплейсе с помощью символических ссылок

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

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

​

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

​

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

​

plugin init

claude plugin init <name> [options]

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

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

# Создайте с папками skill и hook
claude plugin init my-helper --with skills hooks

# Перезаписать существующий scaffold
claude plugin init my-helper --force

​

plugin install

claude plugin install <plugin> [options]

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

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

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

# Установить в локальную область (игнорируется git)
claude plugin install formatter@my-marketplace --scope local

​

plugin uninstall

claude plugin uninstall <plugin> [options]

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

​

plugin prune

claude plugin prune [options]

​

plugin enable

claude plugin enable <plugin> [options]

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

​

plugin disable

claude plugin disable <plugin> [options]

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

​

plugin update

claude plugin update <plugin> [options]

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

​

plugin list

claude plugin list [options]

​

plugin details

claude plugin details <name>

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

• 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)  (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.

​

plugin tag

claude plugin tag [options]

​

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

​

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

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

​

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

​

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

• Invalid JSON syntax: Unexpected token } in JSON at position 142: проверьте наличие пропущенных запятых, лишних запятых или неквотированных строк
• Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required: отсутствует обязательное поле
• Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: ошибка синтаксиса 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 в записи маркетплейса

​

Устранение неполадок 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

1. Проверьте, что имя события правильное (чувствительно к регистру): PostToolUse, а не postToolUse
2. Проверьте, что шаблон сопоставления соответствует вашим инструментам: "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. Проверьте наличие тайм-аутов соединения в выводе отладки

​

Ошибки структуры каталога

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← Только манифест здесь
├── commands/            ← На уровне корня
├── agents/              ← На уровне корня
└── hooks/               ← На уровне корня

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

​

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

​

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

1. Поле version в plugin.json плагина
2. Поле version в записи плагина на маркетплейсе в marketplace.json
3. SHA коммита git источника плагина для источников github, url, git-subdir и relative-path в маркетплейсе, размещённом на git
4. unknown для источников npm или локальных каталогов, не находящихся в репозитории git

​

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

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