# Формат плагина

Источник: https://svedum.ru/docs/customize/plugin-format

> Из чего собирают плагин для каталога «Сведума» — навыки, правила, сценарии и подключения, манифест, иконка — и как проверить его у себя.

Плагин — папка с навыками, правилами, сценариями и подключениями и манифестом
`.svedum-plugin/plugin.json`. Здесь — что в неё класть и как проверить плагин у себя;
как отправить его в каталог → [Публикация плагина](https://svedum.ru/docs/customize/publish-plugin)

## Что можно опубликовать

| Часть       | Где лежит               | Что это                                                                                              |
| ----------- | ----------------------- | ---------------------------------------------------------------------------------------------------- |
| Навыки      | `skills/<имя>/SKILL.md` | Инструкции для типовых задач, `description` во frontmatter обязателен. → [Навыки](https://svedum.ru/docs/customize/skills) |
| Правила     | `rules/*.mdc`           | Как работать в области плагина. → [Правила](https://svedum.ru/docs/customize/rules)                                        |
| Сценарии    | `playbooks/*.md`        | Пошаговые сценарии работы                                                                            |
| Подключения | `mcp.json`              | Удалённые MCP-серверы по `https`. → [Подключения](https://svedum.ru/docs/customize/connections)                            |

**Пока не принимаем:** исполняемый код и локальные (stdio) MCP-серверы, пакеты через
`npx`/`uvx`, hooks, `inProcess`, вход через сессию «Сведума» (`auth.session`) и
OAuth-клиенты «Сведума» (`clientRef`), `systemAdminOnly`.

## Раскладка

```text
my-plugin/
├── .svedum-plugin/
│   ├── plugin.json      манифест
│   └── icon.svg         иконка (или icon.png)
├── skills/
│   └── crm/SKILL.md
├── rules/               *.mdc
├── playbooks/           *.md
├── mcp.json
├── assets/              картинки
└── README.md
```

В каталог попадают только эти папки и файлы. Остальное в репозитории — CI, исходники
сервера, тесты — не берётся.

### Манифест

```json title=".svedum-plugin/plugin.json"
{
  "name": "my-crm",
  "version": "1.0.0",
  "description": "Клиенты, сделки и задачи из CRM.",
  "author": { "name": "ООО «Пример»", "email": "dev@example.ru" },
  "homepage": "https://example.ru/crm",
  "auth": {
    "token": {
      "header": { "name": "Authorization", "value": "Bearer {token}" },
      "docsUrl": "https://crm.example.ru/settings/api"
    }
  }
}
```

* **`name`** — строчная латиница, цифры, точка и дефис. Имена, начинающиеся с `svedum`, и
  имена плагинов «Сведума» зарезервированы; имя, занятое другим автором, не пройдёт.
* **`auth.token`** — пользователь вставит свой токен API, а «Сведум» подставит его в
  заголовок вместо `{token}`. `docsUrl` — страница, где взять токен; ссылка появится рядом
  с полем ввода. Если сервер сам проводит вход по OAuth, блок `auth` не нужен.

### Иконка

Иконку магазин показывает на карточке плагина, в списке установленных и в подключениях.
Положите её в `.svedum-plugin/icon.svg` или `.svedum-plugin/icon.png`:

* **квадрат** — фон и рисунок целиком, углы магазин скруглит сам;
* **PNG** — от 96×96 px, лучше 256×256; **SVG** — с `viewBox`;
* **до 32 КБ**;
* SVG — один файл: без скриптов, без внешних картинок, шрифтов и ссылок.

Без иконки заявка не пройдёт автоматическую проверку. После «Проверить» иконка видна в
отчёте такой, какой её покажет магазин.

### Подключение

```json title="mcp.json"
{
  "mcpServers": {
    "crm": {
      "url": "https://mcp.crm.example.ru/mcp",
      "mutatingTools": ["create_deal", "update_contact"]
    }
  }
}
```

Отметьте инструменты, которые **меняют данные**: перечислите их в `mutatingTools` или
поставьте `readOnlyHint` у читающих инструментов на стороне сервера. Перед вызовом
пишущего инструмента пользователь подтверждает действие.

Назовите инструменты и их аргументы по-русски стандартным полем `title` в ответе
`tools/list`: инструмент — «Создание сделки», аргументы — «Клиент», «Сумма». В чате ход
агента читается по этим названиям («Создание сделки · CRM»), а карточка подтверждения
показывает аргументы полями с вашими подписями. Без `title` видны имена инструмента и
аргументов как есть.

## Проверить у себя

Перед отправкой поставьте плагин из папки: «Персонализация → Плагины → Загрузить из
папки» и выберите папку с `.svedum-plugin/plugin.json`. Попросите агента выполнить задачу,
ради которой плагин делался, и убедитесь, что навыки подхватываются по описанию.