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

​

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

​

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
---

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

• Агенты появляются в интерфейсе /agents
• 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
• 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"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

• Серверы 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"
      }
    }
  }
}

​

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

​

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

​

Полная схема

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json"
}

​

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

​

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

​

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

​

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

{
  "userConfig": {
    "api_endpoint": {
      "description": "Your team's API endpoint",
      "sensitive": false
    },
    "api_token": {
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

​

Каналы

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": { "description": "Telegram bot token", "sensitive": true },
        "owner_id": { "description": "Your Telegram user ID", "sensitive": false }
      }
    }
  ]
}

​

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

• Если существует commands/, он загружается в дополнение к пользовательским путям команд
• Все пути должны быть относительны к корню плагина и начинаться с ./
• Команды из пользовательских путей используют те же правила именования и пространства имён
• Несколько путей можно указать как массивы для гибкости

{
  "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, на время сеанса.
• Через маркетплейс, установленный для будущих сеансов.

​

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

​

Работа с внешними зависимостями

# Внутри каталога вашего плагина
ln -s /path/to/shared-utils ./shared-utils

​

Структура каталога плагина

​

Стандартная раскладка плагина

enterprise-plugin/
├── .claude-plugin/           # Каталог метаданных (опционально)
│   └── plugin.json             # манифест плагина
├── commands/                 # Местоположение команды по умолчанию
│   ├── status.md
│   └── logs.md
├── agents/                   # Местоположение агента по умолчанию
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                   # Skills агента
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # Конфигурации hook
│   ├── hooks.json           # Основная конфигурация hook
│   └── security-hooks.json  # Дополнительные hooks
├── settings.json            # Параметры по умолчанию для плагина
├── .mcp.json                # Определения сервера MCP
├── .lsp.json                # Конфигурации сервера LSP
├── scripts/                 # Скрипты hook и утилиты
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Файл лицензии
└── CHANGELOG.md             # История версий

​

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

​

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

​

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 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

​

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

​

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

• Какие плагины загружаются
• Любые ошибки в манифестах плагинов
• Регистрацию команд, агентов и hooks
• Инициализацию сервера 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, 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. Проверьте, что разрешения файлов позволяют читать файлы плагина

​

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

​

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

{
  "name": "my-plugin",
  "version": "2.1.0"
}

• MAJOR: Критические изменения (несовместимые изменения API)
• MINOR: Новые функции (обратно совместимые дополнения)
• PATCH: Исправления ошибок (обратно совместимые исправления)

• Начните с 1.0.0 для вашего первого стабильного выпуска
• Обновите версию в plugin.json перед распространением изменений
• Документируйте изменения в файле CHANGELOG.md
• Используйте предварительные версии, такие как 2.0.0-beta.1, для тестирования

​

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

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